Ipquery

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

Adds significant behavioral detail beyond annotations: explains cost implications (free vs BYO key for Anthropic), return structure with per-model fields and combined view. Annotations already indicate safe, read-only behavior; description enriches with operational context.

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

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

Three sentences, front-loaded with core purpose and output. No wasted words; each sentence earns its place by providing critical information (purpose, default, return, use cases).

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

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

Despite no output schema, description fully explains return format and use cases. Covers purpose, parameters, cost, and practical applications, making it complete for the agent to decide and invoke correctly.

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

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

Schema description coverage is 100%, so baseline is 3. Description adds value by clarifying default model behavior and cost implications for Anthropic, exceeding basic parameter documentation.

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

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

Clearly states the verb 'Probe', the resource 'LLMs', and the output 'score visibility (0-100) per model'. It distinguishes itself from sibling tools like 'scan_competitor_ai_presence' by focusing on specific entity visibility scoring with model probing.

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

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

Explicitly lists use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. Provides guidance on default model and optional API key for Anthropic. Does not explicitly state when not to use or contrast with 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?

The annotations already establish read-only, open-world, idempotent behavior, so the description's main value is its extra routing behavior: it auto-selects from 5,798 tools, fills in arguments, and returns structured answers with stable pipeworx:// citation URIs. That adds meaningful transparency beyond the annotations, though it doesn't discuss failure modes or rate limits.

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

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

The description is relatively long but front-loaded with the most important instruction ('PREFER OVER WEB SEARCH') and densely packed with useful routing and examples. Some repetition exists between the source list and trigger phrases, but nearly every sentence earns its place.

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

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

For a tool with no output schema and a very broad routing responsibility, the description explains the return format (structured answer with citation URIs) and provides enough alternative routing to orient the agent. It could mention failure/handoff behavior when the question doesn't match any source, but overall it is sufficiently 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%, with the 'question' parameter fully explained and all aliases documented. The description gives examples of valid questions but doesn't really add parameter-level semantics beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description states a clear, specific purpose: prefer this tool over web search for current or historical factual data across a long list of source types, and it routes the question to the appropriate sub-tool. It also explicitly differentiates itself from siblings like ask_pipeworx_grounded and deep_research, so an agent can distinguish it without opening schemas.

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 unusually explicit when-to-use guidance: trigger phrases like 'what is', 'look up', 'get the latest', plus concrete examples. It also names alternatives and their conditions: use ask_pipeworx_grounded for fact-driven research and deep_research for broad multi-part questions. This is strong, actionable routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is well covered. The description adds useful context that no candidate is currently active and it matches ask_pipeworx exactly, plus clarifies it 'falls back to nothing' because it is a full working router. However, it doesn't explain what 'routing improvements' or 'outcome evidence' mean behaviorally, leaving some ambiguity about how routing might differ.

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 necessary for the information conveyed. Key facts—beta version, identical to ask_pipeworx, currently no active candidate—are front-loaded, but the middle section about candidate routing improvements is dense and somewhat repetitive. A tighter version would be more effective without losing meaning.

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 is a beta variant of a known sibling, the description provides essential context: its current state, purpose, parity with the stable router, and that it is fully functional. Since there is no output schema, the reference to 'same response shape' as ask_pipeworx is important and helpful. The only gap is a clearer explanation of what 'routing improvements' mean in practice, but the description is sufficient for an agent to use it correctly.

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

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

Schema description coverage is 100%, with all six parameters documented, including aliases like q, text, input, query, and prompt. The description adds a small bonus by saying arguments are identical to ask_pipeworx, which helps agents familiar with the sibling. The schema itself is clear, so the description doesn't need to repeat parameter details.

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

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

The description clearly identifies this as a beta version of ask_pipeworx with the same universal router functionality, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by emphasizing the experimental routing improvements. However, it is somewhat verbose and the core 'answer questions via routing' function is implied rather than explicitly stated.

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

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

The description explicitly says to use it 'exactly like ask_pipeworx when you want the newest routing' and notes results are compared against the stable router. This gives clear context for when to choose it. It could be stronger by explicitly naming ask_pipeworx as the alternative when stable routing is preferred, but the experimental framing implies this.

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

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

Annotations already declare readOnly, openWorld, and idempotent hints, and the description goes well beyond them by specifying the success response shape, the verbatim evidence field, the refusal reasons enum, and the conditions under which refusals occur. It also discloses the extra LLM call cost. There is no contradiction with the annotations.

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

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

The description is dense but every sentence earns its place: mode, routing behavior, return structure, refusal semantics, use cases, and cost tradeoff. It is front-loaded with the most important characterization and contains no filler.

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

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

The description is complete for a grounded-answer tool. Since there is no output schema, it fully describes the return payload and failure modes. It also provides usage context, sibling differentiation, and cost guidance, leaving little 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 schema already documents the question parameter and its aliases. The description does not add parameter-level detail beyond saying the tool 'fills arguments' internally, but because the schema handles parameter semantics completely, the baseline score 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 mode: a hallucination-resistant, grounded answer mode for high-stakes reads. It explicitly contrasts itself with ask_pipeworx by explaining that it extracts answers only from the tool result. This makes it clearly distinguishable from sibling tools like ask_pipeworx, ask_pipeworx_beta, and 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 gives explicit when-to-use guidance: whenever an answer will be quoted, cited, or acted on and the agent must not invent facts. It also gives an explicit when-not-to-use: prefer ask_pipeworx for casual lookups, and it states the cost tradeoff of one extra LLM call. This is exemplary usage guidance.

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

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

Extensive details beyond annotations: fan-out examples, response shapes, resolver contract, parent event extractor, news fields, safety mechanisms, closed/dead market handling, wide-spread markets, and resolution-rule risk. No contradictions with annotations.

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

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

Long but efficiently packed with essential information. Structured with clear sections and front-loaded summary. Every sentence contributes value without redundancy.

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

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

Very comprehensive given tool complexity and lack of output schema. Covers all aspects: input handling, resolution process, response structure, edge cases (low confidence, closed markets), and risk factors (cancellation rules). 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%, but description adds meaningful context: explains 'market' parameter accepts slug, URL, or text; 'depth' (quick/thorough); 'include_raw' (default false, summarized vs. full payload). Adds value beyond 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 researches a Polymarket bet by pulling Pipeworx data, specifying input types (slug, URL, question text). It distinguishes the tool's function but does not explicitly contrast with sibling tools like polymarket_arbitrage or polymarket_edges.

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

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

Explicitly states use cases: 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'. Provides clear context but does not specify when not to use or offer explicit alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by noting 'keyless' (no authentication) and describing the output components (risk score, one-line assessment). No contradictions.

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

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

Two sentences, no wasted words. Front-loaded with key output details and purpose. Every sentence contributes meaning.

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 single parameter and lack of output schema, the description is complete. It explains what the tool returns and the type of question it answers, satisfying the needs 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?

Schema coverage is 100%, so baseline is 3. The description does not add new information about the 'ip' parameter beyond what the schema provides (IPv4/IPv6 examples). The description could have clarified input format or limitations but does not.

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: fraud/security assessment of an IP address, listing specific detection types (VPN, proxy, Tor, etc.) and a risk score. It answers a precise question and is distinct from sibling tools like lookup_ip.

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

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

The description implies usage for security checks but does not explicitly distinguish when to use this tool over alternatives like lookup_ip or ai_visibility_check. It mentions 'keyless' but lacks guidance on prerequisites or exclusions.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context: it makes a parallel call, handles off-calendar fiscal years, sorts results by primary metric, and returns paired data with citation URIs. No contradiction with annotations.

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

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

Description is dense and front-loaded with key use cases. However, it could be slightly more structured (e.g., separating company vs drug details) to improve readability while maintaining conciseness.

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

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

Given the tool's simplicity (2 parameters, no output schema), the description covers all necessary context: entity types, data sources, sorting, return format, and efficiency benefits. An agent can correctly select and invoke this tool.

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

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

Schema coverage is 100% with descriptions for both parameters. The description enhances understanding by specifying that 'type' determines data source (company=SEC EDGAR, drug=FAERS) and 'values' format (tickers/CIKs for company, names for drug).

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 performs side-by-side comparisons of 2-5 companies or drugs. It provides specific example phrases like 'which is bigger' and 'rank these companies', distinguishing it from single-entity tools like entity_profile.

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

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

Explicitly instructs to prefer this over sequential single-pack lookups when comparing entities. It details when to use each type (company vs drug) and what data is retrieved (SEC filings for companies, FAERS for drugs).

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

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

Goes far beyond the annotations (readOnlyHint, openWorldHint, idempotentHint) by disclosing account/plan requirements, latency expectations (15-60s, up to ~90s), the gap[] behavior ('never invented'), contradictions[] for standard/thorough, citation fetchability guarantees, and semantic excerpting for large records. No contradictions with annotations.

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

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

The description is long but dense with operational essentials; every sentence contributes (auth, use case, mechanics, output, latency, gaps, citations). It is front-loaded with the account requirement and alternative. Some minor redundancy and odd punctuation (e.g., repeated em-dashes) prevent a 5, but the structure is clear and scannable.

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

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

For a tool with 2 parameters, no output schema, and no schema complexity, this description covers everything an agent needs: required auth, alternatives, input examples, depth semantics, output shape (findings packet with citations and gaps), latency, and error handling. No critical missing 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 covers both parameters 100%, so baseline is 3. The description adds meaningful context: explains what 'depth' values actually do (quick=3 facets single hop, standard=3 with gap recovery, thorough=6 with iterative hop), clarifies the paid requirement for thorough, and gives example questions. This additional nuance justifies 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?

States a specific verb ('researches') and resource ('Pipeworx's 1517 STRUCTURED data sources'), and explicitly differentiates from open-web search ('this is NOT open-web search'). Names alternative tools (ask_pipeworx) and specifies the best use case ('broad/multi-part questions over structured data'), so an agent can distinguish it from siblings without opening the schema.

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

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

Provides explicit when-to-use guidance: 'Best for broad/multi-part questions' and 'For a single lookup use ask_pipeworx instead.' Also gives a concrete exclusion ('If you are not signed in, use ask_pipeworx') and clarifies that it is not open-web search. This leaves no ambiguity about when to invoke this tool versus alternatives.

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

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

While annotations already mark it as read-only and idempotent, the description adds valuable behavioral details: returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and that each result is 'ready to call directly, no second schema lookup needed.' No contradiction.

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

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

The description is two sentences with a bullet-like enumeration of use cases, but it's well-structured: first sentence states purpose, second sentence lists domains, third explains return format, fourth gives usage tip. No fluff, front-loaded.

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

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

Given the tool's simplicity and rich annotations, the description is complete: purpose, usage, return value. Could optionally mention handling of no results or error states, but not required for a discovery tool. Adequately covers all key aspects.

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 context by explaining aliases for query and setting default/max for limit (20/50). It also gives examples of natural language queries, enhancing the semantic meaning beyond the schema.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists numerous specific domains (SEC filings, FDA drugs, etc.) and explains the return format (top-N tools with schemas), distinguishing it from sibling tools.

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

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

Explicitly instructs to call this tool 'FIRST when you have many tools available and want to see the option set (not just one answer).' It provides example queries and use cases, giving 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 already declare read-only/idempotent, and the description adds substantial behavior beyond them: empty sections are 'a real "no data", not a bug', private companies return resolved:false with an explicit notes line rather than a bare failure, and the FDA section says 'a company with only small-molecule/generic drugs will show none here, that is expected, not a failure'. Also discloses the GDELT→GNews fallback and source-failure semantics via sources_used/sources_failed.

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?

Purpose and trigger phrases are front-loaded, followed by routing, return spec, and edge-case semantics in logical order. It is long, but every sentence earns its place given there is no output schema to carry the return-format burden. The dense enumeration of sources and fields is somewhat heavy, though justifiable.

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 complex multi-source tool with no output schema, the description carries everything an agent needs: the exact fan-out sources, per-source return fields (including pipeworx:// URIs for filings), the meaning of sources_used/sources_failed, accepted input shapes, and both failure modes (private company, empty sections). Nothing an agent needs to invoke or interpret this correctly is missing.

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

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

Schema description coverage is 100%, so both parameters are already fully documented. The description restates the same accepted shapes (ticker, zero-padded CIK, name) and adds a modest edge-case note about private-company resolution, which is genuinely useful but only marginally extends 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?

States a specific verb and resource: 'full cross-source profile of a US public company in ONE parallel call,' reinforced by seven concrete trigger phrases ('brief me on Tesla', 'what does Apple do', etc.). The scope is unambiguous and the 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' line distinguishes it from more granular lookup 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?

Gives an explicit routing rule — 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' — plus trigger phrases that signal the right intent. It does not explicitly disambiguate from sibling research tools like deep_research or resolve_entity, so the when-not-to-use guidance is not exhaustive.

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

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

Annotations already declare destructiveHint=true. Description adds that deletion is by key, but doesn't detail edge cases (e.g., missing key). Still adequate for a simple operation.

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 and resource. Efficient and clear.

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

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

Given the tool's simplicity (one required parameter, no output schema, annotations clear), the description covers all needed context. Mentions pairing with related tools.

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

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

Schema coverage is 100% with the 'key' parameter already described. Tool description adds 'by key' but no new semantics beyond what the schema provides. Baseline of 3 is appropriate.

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

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

The description clearly states the action (Delete) and the resource (previously stored memory by key). It distinguishes from sibling tools like remember (store) and recall (retrieve).

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

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

Provides explicit guidance on when to use: when context is stale, task done, or clearing sensitive data. Also mentions pairing with remember and recall, indicating alternatives/complementary tools.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and non-destructive behavior. The description adds behavioral context: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format' and specifies output is a 'single text blob'. No contradictions with annotations.

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

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

The description is front-loaded with the core purpose and includes all essential information. It is slightly longer than necessary but each sentence adds value. Could be trimmed slightly for perfect conciseness.

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

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

Given no output schema, the description adequately explains the output format ('standard llms.txt markdown format', 'single text blob') and processing steps (fetch, extract, emit). The tool is simple with only two parameters, and the description fully covers what an agent needs to know.

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

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

Schema coverage is 100% for both parameters ('url' and 'max_links'). The description paraphrases the schema (e.g., 'Full URL', 'maximum number of link entries') but does not add significant new semantic meaning beyond what the schema already provides.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, using specific verbs and resource. It includes use cases (client indexing, own project, competitor auditing) that help distinguish it from sibling tools like 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 explicitly lists three use cases for when to use the tool (getting a client's site indexed, drafting for own project, auditing competitor), providing clear context. However, it does not explicitly state when not to use it or suggest alternative tools, which prevents a perfect score.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint as true; description adds return fields and active/inactive scope but doesn't contradict 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: first states purpose and return fields, second gives usage guidance. No filler.

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

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

Simple tool with one optional parameter and clear annotations; description provides enough context including return fields and usage scenarios.

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

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

Schema description coverage is 100% with include_inactive described there. Description does not reference parameters but does not need to as schema already covers 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?

Description clearly states 'List the caller's active subscriptions' with specific verb and resource, and lists return fields. Distinguished from sibling tools like subscribe and unsubscribe.

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

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

Provides clear usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Does not explicitly state when not to use, but context is clear.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds value by detailing the specific data returned (geolocation, ISP, risk score), which is not present in annotations. No contradictions.

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

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

Description is a single sentence that packs substantial information but remains readable. It is front-loaded with the core purpose. Could be slightly more structured (e.g., bulleted list) but still concise and effective.

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

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

Given no output schema, the description thoroughly explains the expected return data: geolocation details, ISP/ASN/org, and security risk flags with a risk score. This is complete for a lookup tool with one parameter.

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

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

Schema coverage is 100% with a clear description for the 'ip' parameter and examples. The description does not add new parameter semantics beyond what the schema provides, so baseline 3 applies.

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

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

Description clearly states the tool provides 'full IP intelligence' for both IPv4 and IPv6 addresses, listing specific data categories like geolocation, ISP/ASN/org, and security risk flags. It distinguishes itself from siblings by being a dedicated IP lookup tool with no direct competitor in the sibling list.

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?

No explicit guidance on when to use this tool vs alternatives. While 'Keyless' implies ease of use, there is no mention of when to prefer this over potential overlapping tools like 'check_risk' or 'entity_profile'. The description could benefit from stating typical use cases or exclusions.

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

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

Annotations only provide non-read-only/non-destructive flags, but the description adds substantial behavior: rate limited to 5 per identifier per day, free and not quota-counted, claim_token flow for later status retrieval, team review cadence, and roadmap impact. 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 front-loaded with the core purpose and every subsequent sentence provides operationally relevant detail: exclusions, token flow, rate limits, and cost. Although it is a long paragraph, the length is warranted for the tool's complexity and no sentence feels wasteful.

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

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

Despite lacking an output schema, the description explains return behavior (claim_token and later status updates), rate limiting, and scoping rules for when to use. Combined with the rich parameter schema, an agent has enough context to select and invoke the tool correctly.

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

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

Schema coverage is 100% for all parameters, so the baseline is 3. The description adds extra semantic detail for claim_token ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})' with no other arguments) and message content guidance ('don't paste the end-user's prompt'), which justifies a score above baseline.

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

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

The description opens with the specific action: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly identifies the resource (Pipeworx tools/packs) and distinguishes this tool from siblings like ask_pipeworx or deep_research by framing it as feedback submission.

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 enumerates when to use: bug, feature/data_gap, and praise. It also provides clear exclusions: only for tools served by this Pipeworx connection, with guidance to file elsewhere for other MCP servers. It adds practical rules like not pasting end-user prompts.

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, and non-destructive behavior. The description adds valuable context: data source (CF analytics-engine), no PII, and caching (5min-1h). No contradictions.

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

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

The description is concise (4 sentences), front-loaded with the core functionality, and each sentence provides essential information without redundancy.

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

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

Given the simple input schema and rich annotations, the description adequately covers purpose, usage, and behavior. It does not specify exact return format but mentions 'top tools, top packs, and total call volume', which is sufficient for a read-only query.

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

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

Schema coverage is 100% for the single parameter 'window'. The description adds semantic guidance: shorter windows for hot trends, longer for steady-state demand, which goes beyond the raw enum values.

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

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

The description clearly states it returns top tools, top packs, and call volume over a window, and provides distinct use cases. It differentiates itself from sibling tools like 'discover_tools' by focusing on real-time usage trends.

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

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

The description lists three specific use cases, giving clear context for when to use the tool. However, it does not explicitly mention when not to use it or compare with alternative tools like 'discover_tools'.

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

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

Annotations declare readOnlyHint=true, and the description adds substantial behavioral context: it walks child markets, checks ordering, performs partition check, includes semantic anchor and partition filter, and describes fill check behavior with clear do-not-trade condition. No contradictions with annotations.

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

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

The description is long but well-structured, with the main purpose stated first, followed by mode explanations, technical details, and output format. Every sentence adds value, though it could be slightly more concise by grouping some technical details.

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

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

Given the complexity (multiple modes, fill check, semantic anchor, partition filter), the description covers all aspects comprehensively. Since there is no output schema, it fully explains the return structure (opportunities[], partition_check fields, fill check results) and provides actionable caveats.

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

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

The input schema already describes both parameters, but the description adds significant meaning: for event it explains the internal checks (date-axis, threshold-axis, partition_check) and gives example slugs; for topic it explains cross-event scanning and semantic anchor. This goes beyond schema descriptions.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between three modes (no args, event, topic) and explains what each does, differentiating it from other Polymarket tools like polymarket_edges.

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

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

The description provides explicit guidance on when to use each mode: no args for trending scan, event for specific market, topic for cross-event scanning. It also warns not to trade when fill check shows realizable edge ≤ 0. However, it does not directly compare this tool to other sibling tools like polymarket_edges or polymarket_kalshi_spread.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral context: it explains the three model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) with detailed methodology, caching ('Cached 1h at the KV level'), diagnostics for empty segments, and tradeable-edge knobs. It also discloses limitations (Fed bets excluded, unreliable OIS/SOFR). No contradictions with annotations.

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

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

The description is detailed but appropriately so given the tool's complexity. It front-loads the main purpose and then logically organizes content: model families, knobs, response structure, diagnostics. While long, every sentence adds necessary context. It could be slightly more concise by using bullet points, but the prose structure is clear and well-formed.

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

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

Despite having no output schema, the description fully describes the response structure: by_segment with three categories, fed_candidates/fed_note, and _diagnostics. It explains caching, filter behavior, and edge calculation details including edge_pp_net, kelly_fraction, and 24h-move warning. The description is comprehensive enough 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%, so parameters have basic descriptions. The tool description adds significant semantics by explaining the 'TRADEABLE-EDGE KNOBS' concept and how parameters like min_partition_leg_kelly apply specifically to partition legs. For example, it clarifies that partition arbs return kelly_fraction_half=0 at parent level, so min_kelly doesn't filter them—this knob does. This provides useful context beyond the schema.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It specifies the verb 'scan' and resource 'Polymarket markets', and distinguishes itself from siblings by focusing on Pipeworx disagreement and multi-model families. The tagline 'Built for "what should I bet on today"' reinforces the 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 provides strong contextual usage guidance: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It implies the tool is for discovering trading edges daily. While it doesn't explicitly name alternatives like polymarket_arbitrage or polymarket_edge_tracker, the detailed explanation of model families and knobs helps an agent infer when to use this vs. other tools. It lacks explicit 'when not to use' statements, but the context is clear enough for an informed agent.

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

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

Annotations declare it's read-only, idempotent, and non-destructive. The description adds rich behavioral details: response structure (tracked, expired, snapshot_dates), field meanings (trend, decay_pp_per_day), limits (60-day TTL, no intraday data), and computational specifics (daily closes). No contradictions with annotations.

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

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

The description is dense but well-organized, front-loading the core question and then detailing output format and limitations. Every sentence adds value, though the length is justified by the amount of 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 no output schema, the description fully documents the return values (tracked, expired, snapshot_dates with fields and interpretation). It also explains limitations and data source. Parameter coverage is complete via schema. The tool is well-specified for an AI 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 contains full descriptions, but the tool description adds valuable context: 'days' is lookback with default 14 and max 30 (plus clamp), 'window' is snapshot family with default '1wk'. This extra detail helps an agent set appropriate parameters 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 states it tracks edge persistence and decay from daily snapshots, answering 'how long has this edge existed and is it shrinking?' It distinguishes from sibling tools like polymarket_edges by focusing on historical persistence 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?

Provides explicit context on when to use (evaluating edge longevity) and parameter defaults with limits. It does not explicitly state when not to use, but the purpose is clear enough to guide appropriate invocation.

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 read-only and non-destructive behavior, and the description adds details like walking the ladder, returning specific fill metrics, and warning about unhedged directional risk, which aligns with and expands on annotations.

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

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

The description is dense but well-structured with bold headings for modes. Every sentence adds value, though slightly long; a more bulleted format could improve readability without losing information.

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

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

Despite no output schema, the description lists all return fields for both modes (e.g., top_of_book, slippage_pp, capture_ratio), covers edge cases like thin legs and forced directional risk, and provides use cases, making it fully comprehensive.

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 further explains parameter meanings in context (e.g., size_usd interpretation differs for single vs basket modes, side defaults auto for basket), adding significant value beyond the schema.

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

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

Clearly states it's a 'realizable-vs-theoretical edge check against live CLOB order-book depth', specifies single-market and basket modes, and distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges as a risk check tool.

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

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

Explicitly instructs when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', and warns against risks of partial fills.

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

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

Annotations already mark the tool as read-only and idempotent, but the description goes far beyond that: it discloses compatibility codes, non-equivalent bet shapes, unclassified leg handling, fee-schedule limitations, and skipped comparison counters. It even explains that returned pairs carry flags that should be read even when matched_pairs > 0. No contradiction with annotations.

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

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

The description is long but densely informative and well-organized with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS, Codes). It earns most of its length given the tool's complexity and the absence of an output schema. Some minor redundancy exists around temporal alignment, where the null meaning is explained twice.

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 must carry the full burden of explaining return values, and it does: it covers top_spreads_pp, compatibility fields, skipped_unclassified, low_confidence_pairs, temporal_alignment, fees_note, and skipped counters. It also provides practical context about when pre-mapped topics return warnings, which is essential for correct interpretation.

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

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

Schema coverage is 100%, so baseline is 3; the description adds genuine value by explaining the semantics of `topic` as pre-mapped shortcuts and by clarifying that explicit ticker/slug override the mapped side. It also states that both modes run the same matching logic, which is not inferable from 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 opening sentence states a specific operation: measuring the cross-venue spread between Kalshi and Polymarket for the same resolving question. This clearly distinguishes it from sibling tools like polymarket_arbitrage, which targets arbitrage, and polymarket_edges, which focuses on single-venue edges. The two modes are named and scoped precisely.

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

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

The description gives explicit usage context: it introduces the `topic` shortcut mode, the explicit ticker/slug mode, and clarifies that explicit parameters override the topic-mapped side. It also warns when not to treat output as tradeable, but it does not explicitly name when to use a sibling tool instead, so it falls short of a full 5.

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

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

Annotations declare readOnlyHint=true and idempotentHint=true, so the description adds value by explaining scoping ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and pairing with remember/forget. 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?

Three sentences, each earning its place: action, usage scenario, scoping and pairing. Front-loaded with core purpose. 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's simplicity (1 optional parameter, no output schema), the description covers purpose, usage, scoping, and relationships to sibling tools. Fully adequate for an agent to select and invoke correctly.

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

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

Schema coverage is 100% with one optional parameter 'key' described. The description adds no new parameter-level details beyond the schema. The instruction to 'omit the key argument' for listing is already implied by the parameter being optional.

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

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

The description clearly states the tool retrieves a value saved via remember or lists all keys when key is omitted. It uses specific verbs (retrieve/list) and resource (memory keys/values). Distinguishes from sibling tools remember and forget.

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

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

The description provides clear context: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It implies when not to use (use forget to delete) and mentions scoping, though it does not explicitly state alternatives beyond pairing with remember/forget.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint (false). The description adds behavioral details beyond annotations: it explains the effect of mark_read (flagging events read so next call is newer), the return fields, and that the feed is persisted. No contradiction with annotations.

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

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

Five sentences, each serving a distinct purpose: purpose, return details, filtering, mark_read effect, alternative access. No fluff, front-loaded with primary action. Every sentence earns its place.

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

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

Given 5 parameters, all described in schema, the description covers key aspects: return fields (no output schema but mentioned), filtering, and mark_read. It might miss ordering or default limit behavior, but for a simple polling tool, it is complete enough.

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 giving an example for type ('sec_8k'), explaining mark_read semantics, and specifying ISO timestamp for since. However, it does not mention the unread_only parameter in the description, though the schema covers it. Overall, it adds meaningful context beyond schema alone.

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

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

The description clearly states it pulls fired events from a subscription feed, with specific verb 'Pull' and resource 'fired events from your subscription feed'. It mentions return fields (source, citation_uri, raw payload). However, it does not explicitly differentiate from sibling tools like list_subscriptions or subscribe, leaving a slight gap in distinguishing its scope.

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

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

The description provides context for use: filtering by type and since, and notes that polls work fine. It also mentions an alternative access method (GET endpoint). However, it gives no explicit guidance on when not to use this tool vs siblings, or prerequisites (e.g., needing a subscription).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds significant behavioral context: fans out to multiple sources, handles rate limits (GDELT preferred, GNews fallback), and soft-fails for USPTO pending reactivation. 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?

Well-structured with example queries front-loaded. However, description is fairly long; some repetition could be trimmed. Still, every sentence provides useful information.

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

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

No output schema, but description explicitly states the return structure: 'structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs.' Covers all necessary details for confident 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 already describes all 3 parameters (100% coverage). Description adds value by explaining valid formats for `since` (ISO date or relative shorthand like '30d', '1y') and suggesting '30d' or '1m' for typical monitoring, but schema already covers basics.

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

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

Description clearly defines the tool as a change feed for a company over a time window, listing specific sources (SEC EDGAR, GDELT/GNews, USPTO). It distinguishes itself from the sibling tool entity_profile by explicitly stating when to use the latter instead.

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

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

Provides explicit example queries ('What's new with X', 'latest on Y') and a clear alternative: 'Use entity_profile instead when you want the static profile.' Also describes fallback behavior (GDELT→GNews) and USPTO status.

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 context beyond annotations: scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous. Annotations already provide idempotentHint=true and destructiveHint=false, and description does not contradict.

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

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

The description is four sentences, each adding value: purpose, usage guidelines, storage details, pairing info. Front-loaded with the main action.

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

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

For a simple tool with two parameters and no output schema, the description fully covers what the tool does, when to use it, and how it behaves. No gaps.

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

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

Schema coverage is 100% with descriptions for both key and value. The description reinforces the usage but does not add significant meaning beyond the schema, warranting baseline 3.

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

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

The description explicitly states the tool's purpose: 'Save data the agent will need to reuse later'. It provides concrete examples (resolved ticker, target address, etc.) and distinguishes from siblings recall and forget.

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

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

Clearly states when to use: 'when you discover something worth carrying forward'. Also gives alternatives: 'Pair with recall to retrieve later, forget to delete.'

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

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

Beyond the readOnly/idempotent annotations, the description discloses substantial behavior: the call cascades through multiple lookup endpoints, unresolved identifiers are returned under an `unresolved` field rather than omitted, ambiguous matches assert nothing and return `figi_candidates`, and LEI/FIGI enrichment degrades gracefully when upstream services are unavailable. This gives the agent a reliable mental model of execution behavior.

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

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

The description is long, but almost every clause adds necessary nuance for a complex multi-source resolver. It is front-loaded with examples and the 'Use FIRST' directive, then organized around supported types and edge cases. The heavy parenthetical in the company section is dense but earns its place; a slightly tighter structure would be ideal.

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

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

For a tool with no output schema and two heterogeneous entity types, the description is remarkably complete. It covers input canonicalization, source attribution, unresolved-identifier behavior, ambiguous-match handling, cross-entity ISIN mapping, non-US issuer coverage, and failure degradation. An agent has enough information to decide when to call it and what to expect back.

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 significant meaning beyond the schema's terse type/value fields. It enumerates accepted input formats (ticker, CIK, ISIN, name; brand or generic drug name), provides explicit examples like 'CH0038863350' and 'ozempic'/'metformin', and explains how ISINs resolve to legal entities via GLEIF. This strongly compensates for any thinness in the schema itself.

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

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

The description opens with concrete user-phrase examples ('What's the ticker for…' / 'find the CIK for…') and states a specific verb+resource: resolve a user-spoken NAME to canonical/official identifiers other tools require as input. It clearly separates itself from siblings like entity_profile by framing this as the first step whenever a name needs to become an ID, rather than profiling or comparing entities.

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

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

It explicitly instructs 'Use FIRST whenever you have a name but need an ID,' which tells the agent when to select this tool over alternatives. It also gives rich selection guidance per type, including the critical negative example that users should pass the issuer name only, never the full noun phrase like 'revenue bonds,' because the FIGI lookup matches instrument names.

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, openWorld, non-destructive. Description adds that it probes each entity with ai_visibility_check and returns ranked list with score, confidence, signal density—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?

Description is four sentences, front-loaded with purpose, efficient but not excessively brief. No redundancy, each sentence adds value.

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

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

Given no output schema, description adequately explains return format (ranked list with score, confidence, signal density). Also covers purpose and usage. Missing details on models and _apiKey but those are documented in 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. Description does not add new parameter details beyond what schema already describes; it refers to entities and context in a general way.

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

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

Clearly states it compares AI visibility across multiple entities side-by-side, using ai_visibility_check, and returns a ranked list. Distinguished from sibling ai_visibility_check which is for single entity.

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

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

Explicitly mentions use case (competitive AI-marketing audits) and references ai_visibility_check as the probe tool, implicitly suggesting when to use this over a single check. No explicit when-not-to-use, but context is clear.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds behavioral details: it fans out across two services, handles partial failures gracefully, and notes that bundlephobia's first measurement can take 5-30 seconds. This adds value beyond annotations with no contradictions.

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

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

The description is a single dense paragraph but communicates all necessary information efficiently. It is front-loaded with the main purpose and covers key details. Could be slightly improved with bullet points or shorter sentences, but currently concise and well-structured.

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

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

Despite no output schema, the description fully enumerates the return fields (summary block with is_latest, license, etc., per-advisory detail, links, alternative versions) and explains error behavior (sources_failed list). This provides complete context for an agent to understand 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 is 3. The description adds meaning by stating that scoped packages are accepted and that version defaults to the latest published version when omitted, which goes 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 clearly states it's a composite check for npm packages using deps.dev and bundlephobia. It specifies the verb 'scan' and resource 'dependency', and distinguishes itself from siblings by focusing on npm package evaluation, which is unique among the listed tools.

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

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

The description explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also notes ecosystem constraints ('NPM ecosystem only in v1') and directs users to alternative tools for other ecosystems, providing 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 discloses critical behavioral details beyond the annotations: embedding model (BGE-base-en), similarity metric (cosine), chunking (500-char overlapping windows), character limit (200K chars with truncation and flagging), and output characteristics (offsets, similarity scores). The annotations only indicate idempotent, read-only, non-destructive, and open-world, so the description adds substantial value.

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

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

The description is concise (5 sentences) and well-structured. It front-loads the purpose, immediately explains the use case, and then provides technical trade-offs. Every sentence adds value without redundancy.

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

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

Despite lacking an output schema, the description explains the return values (top-N passages with offsets and similarity scores), compensating for the missing schema. It covers all parameters and behavioral aspects thoroughly, making the description complete for a tool of this complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by providing context for the `text` parameter (max ~200K chars) and offering specific examples for `query` (e.g., 'supply-chain risk'). This extra context raises the score above baseline.

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

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

The description clearly identifies the tool's purpose: 'Semantic search INSIDE a fetched record.' It specifies the resource (a record's text) and action (search with a query). It distinguishes from siblings by noting it pairs with ask_pipeworx_grounded, implying it's a complementary tool for large documents.

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: 'Use when the record is too big to cram into the prompt.' It explains the benefit (saves context, returns relevant passages) and mentions pairing with a sibling tool. However, it does not explicitly state when not to use it or list alternatives, missing some exclusion guidance.

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

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

The description discloses key behaviors beyond annotations: it returns a subscription id, requires OAuth, details delivery channel constraints (phone verification, 10/day SMS cap, webhook signing and auto-disable on failure). Annotations only hint at idempotency and non-destructiveness, so the description adds substantial value.

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

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

The description is front-loaded with the main purpose and then provides structured, detailed information about types and delivery. While it is comprehensive, some sentences are lengthy and could be broken down for easier scanning. Overall, every sentence adds value.

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

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

For a tool with no output schema, the description covers prerequisites, supported types, delivery options, and constraints thoroughly. It lacks a summary of the return format (just 'returns the new subscription id'), but given the complexity of parameters, it is sufficiently 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% (baseline 3), but the description adds significant meaning with concrete examples for each type, validation requirements for delivery fields (e.g., phone verification, email pattern, webhook signing), and constraints like SMS cap. This goes beyond the schema descriptions.

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

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

The description clearly states the verb ('Create'), resource ('subscription'), and context ('proactive monitoring subscription to a live-data event stream'). It distinguishes from sibling tools like 'unsubscribe' and 'list_subscriptions' by focusing on creation of monitoring subscriptions.

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

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

The description provides explicit prerequisites (requires Pipeworx OAuth account, no anonymous/BYO) and explains supported types with examples. However, it does not explicitly state when not to use this tool or compare to alternatives among the sibling tools, which would further enhance 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 indicate read-only, idempotent, non-destructive behavior. The description adds valuable context about the return format (category-bucketed examples with tool+argument shape) and the live catalog source, but does not disclose any additional behavioral traits beyond what annotations cover.

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

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

The description is moderately long but well-structured, front-loading common queries and explaining purpose, categories, and usage. Every sentence adds value, though it 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 the tool's simplicity (1 optional parameter, no output schema), the description fully covers what the agent needs: what it returns, when to use it, and how it relates to sibling tools. It explicitly mentions the return structure and the meta-tools it helps learn.

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

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

Schema coverage is 100% with a description. The description adds explicit allowed values (finance, pharma, etc.) and clarifies usage patterns (no arguments vs topic), providing meaningful guidance 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 states the tool's purpose: to return category-bucketed example questions with exact tool+argument shapes. It distinguishes itself from siblings by positioning as the onboarding entry point and explicitly mentioning meta-tools like ask_pipeworx, entity_profile, etc.

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

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

The description provides explicit guidance on when to use this tool: 'Use this FIRST when you do not yet know what Pipeworx can do for you'. It also explains how to call it (no arguments for full spread, topic parameter to focus) and mentions it helps learn how to call meta-tools, effectively 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 the tool as non-read-only, idempotent, and non-destructive. The description adds key behavioral details: deactivation instead of deletion and availability of historical events via recent_alerts. 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 two sentences long, front-loaded with the core action, and every sentence provides necessary information without redundancy. It is efficient and easy to parse.

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

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

Given the tool's simplicity (one parameter, no output schema) and the presence of sibling tools like subscribe and recent_alerts, the description adequately covers the effect on data (deactivation, historical events) and ownership, making it complete for an AI 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?

Input schema has 100% description coverage; the 'id' parameter is described as 'Subscription id (uuid) returned by subscribe.' The description only mentions 'by id', adding minimal value beyond the schema. Baseline score 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 clearly states the action (Cancel a subscription by id) and the resource (subscription). It distinguishes from sibling tools like subscribe and list_subscriptions by specifying ownership and the deactivation behavior, making the purpose unambiguous.

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

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

Description provides a clear ownership constraint ('you can only cancel your own subscriptions'), guiding when the tool is applicable. It does not explicitly mention when not to use it or name alternative tools, but the context of sibling tools implies appropriate use cases.

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

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

The description goes well beyond the annotations by explaining the two-path routing (SEC EDGAR + XBRL vs. grounded pipeline), the exact verdict vocabulary, and the critical nuance that could_not_verify does not constitute evidence. It also clarifies the meaning of unsupported. No contradiction with readOnlyHint/openWorldHint/idempotentHint is present.

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

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

Though the description is several sentences long, it is tightly structured and front-loaded with trigger phrases and purpose. Each section (routing, verdicts, caller warnings) earns its place; there is no fluff. The length is appropriate for the tool's complexity.

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

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

With no output schema, the description carries the full burden of explaining return values. It enumerates all possible verdicts, mentions the grounded actual value with citation, and describes reasoning. It also covers error semantics (verification_error with stage/detail) and the distinction between could_not_verify and unsupported, making it fully complete for an agent.

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

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

The input schema already provides 100% coverage for both parameters, including detailed behavior for tolerance_pct. The description adds only a passing reference to 'exact percent-delta math' for the financial path, which does not meaningfully augment the schema's documentation. 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 clearly states the tool's purpose: 'natural-language claim verification against authoritative sources' with specific trigger phrases like 'fact check' and 'verify the claim that…'. It explicitly contrasts this with siblings by focusing on claim verification and returning verdicts, and no sibling tool offers the same functionality.

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

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

It gives an explicit when-to-use directive: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also details the internal routing for company-financial vs. other claims and notes it replaces 4–6 sequential calls, providing clear context for when this tool is appropriate.

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