Mfapi India

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

Annotations already cover safety (read-only, idempotent). Description adds valuable behavioral context: default free model, BYO key for Anthropic, cost implications, and return format. No contradictions.

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

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

Two sentences, front-loaded with purpose, no fluff. Every sentence adds value. Excellent structure.

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 structure and model options. Covers all necessary context 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%, but description enhances meaning by clarifying default model and condition for _apiKey. Provides practical usage context not in schema.

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

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

Description clearly states the tool probes LLMs for brand visibility and scores it (0-100) per model. It specifies the verb ('probe'), resource ('LLMs'), and context ('AI-marketing audits'). Differentiates from siblings like 'scan_competitor_ai_presence' by focusing on visibility scoring.

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

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

Explicitly suggests use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' Does not explicitly state when not to use or name alternatives, but the context is clear enough.

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 that the tool internally routes to the right tool, fills arguments, and returns a structured answer with stable pipeworx:// citation URIs. It also notes it is fast ('one fast call') and works on every tier, adding behavioral context beyond the read-only/idempotent annotations. 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 front-loaded with the most important instruction ('PREFER OVER WEB SEARCH') and structured with examples and conditional alternatives. Every section earns its place, though it could be tightened.

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

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

Given the tool's complexity and lack of output schema, the description adequately explains return format (structured answer with citations), performance (one fast call), and tier availability. It also clarifies limits of the base version by contrast with the grounded version. This is sufficient 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?

The input schema already documents the 'question' parameter and all aliases with 100% coverage, so the baseline is 3. The description does not add parameter-specific details beyond examples, but the schema fully covers the parameter meaning.

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

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

The description clearly states the tool routes questions to 5,529 tools across 1,455 verified sources to answer factual queries with structured answers and citations. It explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, and provides concrete examples of supported questions.

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

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

The description explicitly instructs to prefer this tool over web search, labels it as the 'default entry point' and 'START HERE', and specifies when to step up to ask_pipeworx_grounded or deep_research. It provides trigger phrases like 'what is' and 'look up' and covers a wide range of domains, making the usage scope unmistakable.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description adds valuable context: it's an experimental beta with candidate routing improvements enabled live, and results are compared against the stable router. It also clarifies that when no candidate is active, it matches ask_pipeworx exactly. This goes beyond simply restating annotation hints.

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 yet information-dense. It front-loads the beta nature and equivalence to ask_pipeworx, then provides usage guidance and clarifies it's a full router. Every sentence earns its place: definition, current status, usage, and fallback clarification. 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 that this is a beta variant of an existing tool, the description fully covers what an agent needs: identical functionality, experimental nature, current equivalence, and usage instructions. The output schema is absent, but the description points to ask_pipeworx for the response shape, which is sufficient. The sibling context (ask_pipeworx, ask_pipeworx_grounded) reinforces the place of 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 all parameters (question and five aliases). The description adds nothing beyond 'same arguments' as ask_pipeworx, which is already clear from the schema. Since the schema handles parameter semantics, a baseline 3 is appropriate.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router with identical tools and arguments. It distinguishes itself from the stable ask_pipeworx by mentioning experimental routing improvements and current equivalence. The purpose is explicitly stated: it's an experimental edge that routes questions to the same 5,529 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 states when to use this tool: 'Use it exactly like ask_pipeworx when you want the newest routing.' It explains that results are compared against the stable router to decide what merges, and clarifies that it's a full working router, not a fallback. The current state (no active candidate) is also disclosed, so the agent knows it currently behaves identically to ask_pipeworx.

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 behavioral traits well beyond the annotations: it adds the extra LLM call cost, the extraction-only-from-source guarantee, return format with evidence and refusal reasons, and specific failure modes. This significantly enriches the annotated safety profile without contradiction.

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

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

The description is front-loaded with a crisp purpose, followed by clear behavioral details. Each sentence adds value—process, return shape, refusal reasons, usage scenarios, cost tradeoff—without redundancy. It is appropriately detailed for a high-stakes tool.

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

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

Given there is no output schema, the description compensates by fully specifying the success and refusal return structures. It also covers routing scope, cost, and when to use the tool, providing a complete picture for an agent to invoke 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 coverage is 100% with aliases already documented, so the baseline is 3. The description does not add parameter-specific semantics beyond noting that the tool 'fills arguments' during routing, which is already implied by the schema's natural-language question field.

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 'Hallucination-resistant answer mode for high-stakes reads,' which clearly states the tool's function and distinguishes it from the sibling ask_pipeworx by emphasizing grounded extraction. It also explains the routing mechanism and the extraction constraint, making the purpose unmistakable.

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

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

Usage guidance is explicit: 'Use whenever an answer will be quoted, cited, or acted on' and 'prefer ask_pipeworx for casual lookups.' It also names the alternative (ask_pipeworx) and provides a cost-based reason for choosing between them.

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 goes well beyond this by disclosing low-confidence short-circuit behavior (status:'low_confidence_match'), closed/dead market handling, wide-spread market warnings, resolution-rule risk (cancellation_rule parsing), and news fallback mechanisms. This provides rich behavioral context that annotations alone do not 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 very long (multiple paragraphs) and contains extensive detail. While all content is valuable, the length reduces conciseness. It is front-loaded with the main purpose and usage, but the volume of information could be better structured (e.g., bullet points or sections). Every sentence earns its place, but the overall format is dense.

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

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

There is no output schema, yet the description fully explains the response shape (result.market, result.analysis, result.evidence), resolution contract, parent event extractor, news fields, and safety mechanisms. It covers edge cases (low confidence, closed markets, wide spreads, cancellation rules) and provides examples for multiple scenarios (BTC, Fed, Hormuz, sports). The description is 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% with all three parameters described. The description adds significant meaning beyond the schema: for 'market' it gives example formats (slug, URL, question text); for 'depth' it explains quick vs thorough fan-out; for 'include_raw' it clarifies response size implications (20KB vs 50-500KB) and when to use true (recompute deltas, cite observations). This is comprehensive and actionable.

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

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

The description specifies the tool researches Polymarket bets by pulling Pipeworx data, accepts multiple input formats (slug, URL, question text), and clearly distinguishes itself from sibling tools through usage examples like 'should I bet on X'. The verb 'Research' and resource 'Polymarket bet' are specific and unambiguous.

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

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

The description explicitly states when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. It does not mention when not to use it or explicitly exclude alternatives, but the context is clear and the examples provide strong guidance.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description reveals data sources (SEC EDGAR/XBRL for companies, FAERS/FDA/trials for drugs), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs in output. This fully informs the agent of behavior.

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

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

The description is a single, dense paragraph that front-loads example queries and key advantage. Every sentence adds meaningful information without redundancy, achieving high information density.

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

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

Given the tool's complexity (2 params, no output schema), the description covers functionality, data sources, sorting, and efficiency claims. It lacks explicit response structure details but 'paired data + citation URIs' is sufficient. No major 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 description coverage is 100%, providing baseline 3. The description adds value by explaining what each 'type' pulls and giving concrete examples for 'values' (tickers/CIKs for companies, drug names), enhancing usability 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 that the tool compares 2-5 companies or drugs side-by-side, with explicit verbs like 'compare', 'rank', and 'head-to-head'. It distinguishes itself from single-entity lookups by emphasizing efficiency over sequential calls.

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

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

The description provides explicit when-to-use guidance with example queries ('which is bigger', 'rank these companies') and states 'ALWAYS PREFER over sequential single-pack lookups'. It implicitly excludes single-entity use, for which sibling tools like entity_profile exist.

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 substantial behavioral traits beyond annotations: account/tier requirements, latency expectations (15-60s / up to 90s), gap handling (never invented, explicit gaps[]), contradiction scanning, citation resolvability, and semantic excerpting. It adds rich context confirming the readOnly/openWorld/idempotent hints without contradicting them.

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

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

The description is long but each sentence conveys distinct operational or behavioral details (account, alternatives, mechanism, output structure, depth behavior, timing). It is dense rather than wasteful, though the sheer length and run-on first sentence slightly reduce scannability.

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

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

For a tool with no output schema, the description thoroughly explains the findings packet, gaps[], contradictions[], hop field, and citation_uri. It also covers prerequisites (account), performance, and failure modes. This is complete enough for an agent to use correctly in complex 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?

Although schema coverage is 100%, the description adds deep meaning to both parameters: it explains the 'depth' enum with exact facet counts, hop behavior, and contradiction scanning, and elaborates 'question' as decomposable into facets. This goes far 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 uses a specific verb (research) with a precise resource (Pipeworx's 1455 structured data sources), and explicitly distinguishes itself from open-web search and siblings like ask_pipeworx. It clearly states the one-call parallel decomposition behavior, leaving no ambiguity about what the tool does.

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

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

Provides explicit when-to-use guidance ('Best for broad/multi-part questions over structured data'), when-not-to-use ('For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'), and alternatives ('For a single lookup use ask_pipeworx', 'If you are not signed in, use ask_pipeworx instead'). Also clarifies depth tiers and their 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?

Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds valuable context about the return format ('names, descriptions, and full input schemas with curated examples — each result is ready to call directly'). 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 four sentences long, front-loaded with the core purpose. It efficiently lists the domains and key benefit (ready to call). Slightly longer than minimal but 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 6 parameters, no output schema, and 33 siblings, the description adequately explains what the tool returns and how to use it. It clarifies that results include full schemas with examples, eliminating the need for a second lookup. No gaps.

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

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

The input schema covers all 6 parameters (100% coverage), so the description adds limited new meaning. It notes that query accepts multiple aliases and is natural language, which is helpful but not essential beyond the schema.

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

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

The description uses specific verbs ('browse, search, look up, discover') and clearly identifies the resource ('tools'). It distinguishes this meta-tool from its many siblings by stating 'Call this FIRST when you have many tools available and want to see the option set'.

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

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

The description explicitly states when to use: 'when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available'. It implies alternatives are the individual tools but does not explicitly name alternatives or when-not-to-use.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral details: parallel fan-out across multiple sources, soft-fail for patents due to API sunset, and specific return fields with URI patterns. 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 lengthy and includes technical details like full URI patterns and API sunset dates. While informative, these specifics could be trimmed for brevity without losing essential guidance. It is front-loaded with trigger phrases, aiding quick interpretation, but overall it could be 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 complexity (multiple data sources, varied outputs) and absence of an output schema, the description thoroughly explains all return fields, constraints (US public companies only, patents soft-fail), and fallbacks. It warns about unsupported name input and directs to resolve_entity. This is complete for an AI 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 schema covers both parameters with descriptions (100% coverage). The description reinforces that type is limited to 'company' and value can be ticker or zero-padded CIK, providing examples and clarifying that names are not supported. This adds context beyond the schema, but the schema already does much of the work.

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: providing a full cross-source profile of a US public company in one call. It includes trigger phrases and distinguishes from chaining single-pack lookups, making the purpose explicit and specific.

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

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

The description explicitly advises using this tool over chaining individual lookups when a holistic view is needed, and instructs to use resolve_entity first when only a company name is available. This provides clear context and alternatives.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data, which enhances transparency beyond the annotations.

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

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

Three sentences, no fluff. First sentence states core purpose, second gives usage guidance, third references siblings. Front-loaded and efficient.

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

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

For a single-parameter tool with no output schema and good annotations, the description covers purpose, usage, and related tools without gaps.

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

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

Schema coverage is 100%, and the description's 'by key' aligns with the key parameter but does not add additional 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 states 'Delete a previously stored memory by key' with a specific verb and resource, and distinguishes from sibling tools by mentioning 'Pair with remember and recall'.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also provides sibling references for alternative actions.

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 behavioral details beyond annotations: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' This explains the non-destructive, read-only process. No contradictions with annotations (readOnlyHint=true, destructiveHint=false).

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 (under 100 words) and front-loaded with the main action. It efficiently covers purpose, process, and use cases without redundant sentences. Slightly verbose but acceptable.

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

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

Despite no output schema, the description fully explains the output format: 'standard llms.txt markdown format. Output is a single text blob ready to drop at site-root/llms.txt.' It covers process, inputs, and expected result comprehensively for a simple tool.

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

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

Schema description coverage is 100%, so the description adds minimal value beyond what schema already provides. The description mentions 'fetches the page... extracts title/description/key links,' which aligns with the url parameter but does not add new semantics. No additional depth is provided.

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: 'Generate a production-ready llms.txt file for any URL'. It specifies the exact resource (llms.txt) and action (generate), differentiating it from sibling tools like scan_competitor_ai_presence by focusing on the output file format.

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 explicit use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' It provides clear context for when to use the tool, though it does not explicitly mention when not to use it or compare to alternatives.

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

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

Adds value beyond annotations: specifies ordering (newest first), authentication (keyless), and data returned. Annotations already indicate read-only, idempotent, non-destructive, so description complements without contradiction.

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

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

Two sentences, no fluff. First sentence encapsulates purpose and output; second sentence gives usage guidance. Front-loaded with key information.

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

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

Given schema and annotations cover safety and parameters, the description is sufficient for a simple data retrieval tool. Could hint at output structure (e.g., returns an array) but not necessary.

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 fully (100% coverage). Description adds ordering context ('most-recent NAV points (newest first)') but does not significantly enhance parameter understanding beyond schema.

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

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

Clearly states it gets NAV history of a mutual fund scheme, listing specific fields returned (fund house, category, ISIN, latest NAV, points) and ordering (newest first). Identifies the source (MFAPI) and distinguishes from sibling search_schemes by referencing it as a prerequisite.

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 prerequisite ('Use search_schemes to find a scheme_code first') and authentication note ('Keyless'). Does not explicitly contrast with siblings like latest_nav, but the context is clear. Could improve by stating when not to use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds detail about returning the most recent NAV, date, and basic metadata, and mentions it's keyless. Does not contradict annotations, but adds only moderate extra context beyond them.

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

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

Two sentences, concise and front-loaded with the purpose. Every sentence adds value: purpose, return info, usage guidance, and keyless mention. No wasted words.

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

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

For a simple one-parameter tool with no output schema but rich annotations, the description explains return values (NAV, date, metadata) and mentions keyless key property. Adequately complete for its complexity.

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

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

Schema coverage is 100%, with parameter description already including an example and reference to search_schemes. Description repeats this guidance, adding minimal new value. Baseline of 3 is appropriate.

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

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

Description clearly states it performs a fast single-value lookup of the latest NAV for a mutual-fund scheme. It specifies the verb (lookup), resource (latest NAV), and distinguishes from siblings by referencing search_schemes for obtaining the scheme_code.

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 use search_schemes first to find the scheme_code, providing clear context for when to use this tool. Does not specify when not to use or name alternatives explicitly, but the single-value nature implies it's not for history.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds value by listing return fields and the optional include_inactive parameter behavior, without contradicting annotations.

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

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

Two efficient sentences: first states purpose and return fields, second provides usage guidance. No wasted words.

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

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

Given the simple tool with one optional parameter, no output schema, and strong annotations, the description fully covers purpose, return data, and usage context. No gaps remain.

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

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

Schema coverage is 100% with a clear description for the single optional parameter. The description adds no additional parameter meaning beyond what the schema provides, earning the baseline 3.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource. It also enumerates return fields, distinguishing it from sibling tools like subscribe and unsubscribe.

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

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

Explicitly advises when to use the tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This provides clear context and alternatives.

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

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

Annotations are all false, offering no safety/behavior info, so the description carries full burden. It discloses rate limiting (5/day), cost (free, no quota), what happens to submitted feedback (daily digests, roadmap impact), and the claim_token flow for follow-ups. This goes well beyond typical descriptions.

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?

While lengthy, every sentence serves a purpose: usage, exclusions, formatting, claim_token, rate limit, and cost. It is front-loaded with the core function and when-to-use, then layers operational details without redundancy. It's the right length for a tool that must prevent misdirected feedback.

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 explains what filing returns (claim_token) and how to later retrieve resolution status. It covers the full feedback lifecycle, including constraints, cost, and follow-up, making it complete for the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds a critical usage pattern not in the schema: passing claim_token alone with no other arguments to read a prior report. It also reinforces the type enum (bug/feature/praise) and instructs how to frame context (in terms of Pipeworx tools/packs). This is incremental but valuable.

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

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

The description opens with a specific verb+resource combination: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this tool from sibling research/query tools by defining its unique role as a feedback channel for Pipeworx-only 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?

It provides explicit conditions for use ('Use when a tool returns wrong/stale data... a new tool or capability... worked surprisingly well'), and an explicit exclusion ('if the tool came from a different MCP server... file it with that server instead'). It even answers ambiguity about tool ownership, making when-not-to-use unmistakable.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), description reveals caching (5min-1h), data source (CF analytics-engine), and privacy (no PII). Additive context.

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

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

Description is concise (four sentences) and well-structured: core result first, then use cases, then technical details. No fluff.

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

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

Given simple parameter set (1 optional enum) and no output schema, description fully explains behavior, caching, privacy, and intent. Complete for effective use.

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?

Single parameter 'window' with enum is fully covered by schema (100%). Description adds semantic guidance: 'shorter windows surface what's hot right now; longer windows show steady-state demand', going beyond schema.

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

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

Description clearly states verb ('Returns') and resource ('top tools, top packs, total call volume') with explicit time windows. Distinguishes from siblings like discover_tools and ask_pipeworx.

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?

Lists three specific use cases (discovering hot data, confirming canonical tool, checking alignment). Implicitly tells when to use, but doesn't explicitly mention when not to or suggest alternative 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 include readOnlyHint, openWorldHint, idempotentHint, destructiveHint; description adds deep behavioral context: scan types, partition filter (placeholder slugs), fill check against CLOB depth, Jaccard similarity threshold. 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 verbose but well-structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Front-loaded main purpose. Could be slightly shortened, but 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?

Despite lacking an output schema, the description fully explains the response structure (opportunities[] fields, partition_check in event mode, fill check details). Covers multiple modes, edge cases, and constraints completely.

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 elaborates with examples ('fed-decision-may-2026', 'Strait of Hormuz traffic returns to normal') and explains the context of each mode beyond the schema properties.

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 arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' The verb 'Find' and resource 'arbitrage opportunities' are specific, and the technical methods differentiate it from siblings like polymarket_edges or polymarket_fill_risk.

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

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

Explicit usage guidance: 'Call with NO args for a trending_scan... pass event for... or topic for...'. Recommends event mode for specific markets, explains cross-event mode, and notes when not to trade (realizable edge ≤0). Also references polymarket_fill_risk for custom sizing.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context beyond annotations: caching behavior ('Cached 1h at the KV level keyed on all knobs'), response structure with three segments and diagnostics, and details that Fed bets are excluded from ranking. 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 long but dense with information. It is front-loaded with purpose and segments, then covers parameters and response structure. Every sentence adds value, avoiding redundancy. The use of numbered lists and inline explanations (e.g., 'FIVE MODEL FAMILIES grouped into three response segments') maintains structure. Could be slightly trimmed, but for the complexity, it is concise.

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

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

Given no output schema, the description thoroughly explains the response: top-level 'by_segment' with three keys, 'fed_candidates', and '_diagnostics' with funnel counters. It describes the fields within opportunities (edge_pp_net, kelly_fraction, market.liquidity, etc.) and the 24h-move warning. All key aspects are covered, making the tool fully self-contained for an AI agent.

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

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

Schema description coverage is 100%, so baseline is 3. However, the description adds substantive meaning beyond the schema, such as explaining 'min_partition_leg_kelly' in context ('Partition arbs always return kelly_fraction_half=0 at the parent level...'), providing recommended values for 'max_spread_pp' and 'min_liquidity', and clarifying that 'slippage_pp' subtracts from raw edge. These enrich the parameter understanding.

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

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

The description clearly states the tool's purpose: '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 from siblings like 'polymarket_arbitrage' and 'polymarket_edge_tracker' by detailing the unique opportunity segmentation (model-driven, structural arbitrage, concentrated longshot).

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 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It provides guidance on when not to use it (Fed bets excluded, with explanation), and gives concrete parameter recommendations (e.g., 'Set to 2 to require tight books', 'Set to 5000 to drop thin-book opportunities'). It also hints at alternatives by listing sibling tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false. The description adds significant behavioral context: it reads from daily snapshots, returns tracking/expired/snapshot_dates, explains gaps due to cache-miss, and notes the 60-day TTL and start date. No contradiction with annotations.

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

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

The description is long but well-structured: front-loaded purpose, then detailed response fields, then limits. Each sentence provides necessary information without redundancy. Could be slightly more concise, but overall effective.

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

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

No output schema is provided, so the description must fully explain return values. It does so thoroughly: tracked[] with time-series, first_seen, trend, decay_pp_per_day; expired[] with lifespan_days; snapshot_dates[]. Also covers limits like TTL and start date. Complex tool, complete coverage.

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

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

Schema coverage is 100% with parameter descriptions for days (number, default 14, clamp 2-30) and window (string, default '1wk'). The description adds meaning by explaining how days affects history depth and window the snapshot family, plus the response structure that uses these params. This adds 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?

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It answers the question 'how long has this edge existed and is it shrinking?' This distinguishes it from sibling tools like polymarket_edges (current edges only) and polymarket_arbitrage.

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

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

The description gives explicit context for when to use this tool: to evaluate if an edge is fresh or stale, and contrasts with siblings implicitly via the mention of snapshots. It explains that a fresh wide edge and a 3-week-old wide edge are different trades, but does not name alternative tools explicitly.

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, non-destructive. The description adds valuable context: it walks the CLOB ladder, returns verifiable fill details (top_of_book, VWAP, slippage, verdict), and warns about thin legs and forced directional risk. No contradictions; description enriches beyond annotations.

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

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

The description is detailed but structured: overall purpose, requirements, then separate sections for single-market and basket modes, followed by usage guidance. It is front-loaded and avoids redundancy. Could be slightly more concise, but the complexity warrants the length.

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

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

Given there is no output schema, the description fully describes return fields for both modes (e.g., top_of_book, vwap_fill_price, verdict, thin_legs, forced_directional_risk). It also covers parameter behaviors and usage constraints, making it self-contained for an AI agent to correctly invoke the tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaningful context: explains automatic side selection for basket mode, describes size_usd as settlement notional for baskets, and clarifies defaults (side=buy_yes, size=1000). This reduces ambiguity beyond the schema's field-level descriptions.

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

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

The description clearly states it performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' specifying distinct modes (single-market vs basket) and return values. This differentiates it from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on fill feasibility rather than signal generation.

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

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

Explicitly advises to use this tool before acting on polymarket_arbitrage signals or trades above ~$500, explaining why theoretical overround may not be capturable and that partial fills create directional risk. It provides clear when-to-use and when-not-to-use guidance without ambiguity.

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. The description adds rich behavioral context: it explains the compatibility_warning, temporal alignment, skipped_cross_type/subtype counters, and when spreads are meaningless. This goes well beyond the structured annotations and fully informs the agent of the tool's 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 thorough but somewhat verbose, with detailed explanations of safety fields and counters. However, it is well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded with the core purpose. Every sentence adds value, though a slight trim could improve conciseness.

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

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

Given the complexity of the tool and no output schema, the description thoroughly covers response structure (leg-by-leg prices, matched spreads, safety fields), edge cases (compatibility warnings, temporal misalignment), and counters. It provides enough detail for an agent to interpret results correctly and understand limitations.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds significant value beyond the schema: it explains the two modes (topic vs explicit), lists all 10 pre-mapped topics, and describes how explicit parameters override topic mappings. This semantic context helps the agent choose the right parameters.

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

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

The description states the tool's core purpose: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly explains the two modes (topic shortcuts and explicit tickers) and how it compares prices. It differentiates from siblings like polymarket_arbitrage by focusing specifically on cross-venue spreads, making it distinct.

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

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

The description provides explicit when-to-use guidance: to compare prices across Kalshi and Polymarket. It explains the two modes and advises when not to trust results: 'Real cross-venue spreads are rarer than the macro-shortcut list suggests — most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable.' It also describes compatibility conditions, helping the agent avoid misuse.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable context about scoping to identifier (anonymous IP, BYO key hash, or account ID) and pairing with remember/forget. 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?

Two sentences with no wasted words. Core function is front-loaded, and additional context is efficiently provided.

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 simple tool with one optional parameter and no output schema. It covers purpose, usage, scope, and paired tools.

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

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

Schema covers 100% with a clear description for the key parameter. The description adds context about omitting key to list all and gives usage examples, which enhances understanding beyond schema.

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

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

The description clearly states the tool retrieves a value saved via remember or lists all keys when key is omitted. It distinguishes from siblings by naming the associated tools (remember, forget) and specifying the scoping to the agent's identifier.

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 for looking up stored context and provides concrete examples (target ticker, address, notes). It implies when not to use by omission of listing behavior, but does not explicitly exclude alternatives.

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

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

Annotations declare readOnlyHint, idempotentHint, and destructiveHint, establishing safety. The description adds behavioral details: returns the most recent alerts, each with source and citation_uri, explains the mark_read flag's effect on subsequent calls, and confirms that polling is supported. 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 compact (5 sentences), front-loaded with the core purpose, and every sentence adds distinct value: what it does, event structure, filtering, mark_read behavior, and alternative access method. No filler or redundancy.

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

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

Given 5 optional parameters, no output schema, and comprehensive annotations, the description covers the tool's purpose, parameter usage (filtering, mark_read), and even provides an alternative for scripts/dashboards. It is complete for an agent to use effectively.

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

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

Schema coverage is 100%, but the description adds semantic value beyond the schema by providing examples ('e.g. "sec_8k"'), clarifying ISO timestamp format, and explaining the mark_read and unread_only parameters' purpose.

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 begins with 'Pull fired events from your subscription feed,' clearly specifying the action and resource. It further details the contents of each event (source, citation_uri, raw payload), and differentiates from sibling tools like list_subscriptions by focusing on fired events and cursor behavior.

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

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

The description explains when to use the tool: 'Polls work fine' and provides an alternative HTTP endpoint for scripts/dashboards. It mentions filtering by type and since, and the mark_read behavior. While it doesn't explicitly state when not to use, the context is sufficient for an agent to decide.

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. Beyond that, the description adds valuable behavioral details: fans out to multiple sources, mentions GDELT→GNews fallback for rate limits, and notes USPTO patent soft-fail. 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, well-structured paragraph that front-loads with example queries, then explains sources and parameter details. Every sentence contributes useful 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 tool's complexity (multiple sources, fallback logic, parameter formats), the description covers all essential aspects: supported entity types, time window, return structure (changes, count, URIs), and mentions limitation (patents soft-fail). No output schema, but the description adequately describes return value.

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

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

Schema coverage is 100%, but the description adds practical meaning: explains 'since' accepts ISO date or relative shorthand, suggests '30d' for monitoring, and clarifies 'value' can be ticker or CIK. This adds value beyond the schema descriptions.

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

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

The description clearly states the tool provides a change feed for a company (SEC filings, news, patents) within a time window, using verbs like 'fan out' and examples like 'What's new with X'. It distinguishes itself from the sibling 'entity_profile' tool, which gives a static profile.

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

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

The description explicitly tells when to use this tool vs the sibling 'entity_profile', and provides example queries. It also gives guidance on the 'since' parameter (e.g., 'Use "30d" or "1m" for typical monitoring').

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

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

Discloses persistence behavior (authenticated vs anonymous, 24-hour retention) and scoping by identifier, adding value beyond annotations which already show idempotent and non-destructive.

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

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

Four sentences, front-loaded with purpose, efficient with no wasted words. Every sentence adds essential information.

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

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

For a simple key-value store with 2 parameters and no output schema, the description covers behavior, scope, and persistence completely.

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

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

Schema coverage is 100% with clear descriptions, but the description adds example keys (subject_property, target_ticker) that enhance understanding of parameter usage.

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

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

The description clearly states the tool saves data for later reuse, provides concrete examples (resolved ticker, user preference), 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?

Explicitly advises when to use: 'when you discover something worth carrying forward', and pairs with recall/forget, giving clear context for alternative tools.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, but the description adds valuable behavioral details: unresolved identifiers are explicitly listed under `unresolved`, LEI/FIGI enrichment degrades gracefully when upstream sources are unavailable, and each call cascades through multiple endpoints. These go beyond annotation information.

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: opening with usage examples, then supported types, then behavioral details. No filler; every sentence conveys useful information, and the structure flows from triggers to outcomes to edge-case behavior.

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

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

Given the tool's complexity (multiple identifier sources, ownership data, nested `unresolved` field) and no output schema, the description thoroughly covers inputs, outputs, failure modes, and degradation behavior. It tells an agent exactly what to expect and how to use the results.

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

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

Schema coverage is 100%, but the description adds significant meaning: it explains what each `type` returns (SEC EDGAR identifiers, GLEIF ownership, OpenFIGI security FIGI, RxNorm RxCUI with citation) and provides concrete examples for `value` (AAPL, 0000320193, ozempic). This enriches the schema's terse 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 resolves user-spoken names to canonical/official identifiers, with specific verb 'resolve' and the resource being 'entity names to identifiers'. It distinguishes itself from siblings by noting these identifiers are what 'other tools require as input', and it enumerates supported types (company, drug) with detailed identifier outputs.

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: 'Use FIRST whenever you have a name but need an ID.' It also mentions that it replaces 2-3 manual lookups, implying efficiency. However, it does not explicitly name alternatives or exclusions, so it is clear on context but not comparative to sibling tools.

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

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

Adds behavioral details beyond annotations: calls ai_visibility_check multiple times, ranks results, returns ranked list with score/confidence/signal density, treats first entity as subject. No contradictions with readOnlyHint, idempotentHint, etc.

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

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

Two sentences plus parenthetical, front-loaded with main purpose. No redundant information. Each sentence earns its place.

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

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

Despite no output schema, description explains return format (ranked list with score, confidence, signal density). Parameters fully covered. Annotations cover safety. Complete for a tool that composes multiple probes.

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

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

Schema has 100% coverage. Description adds context: entities (2-8, first is subject), models (workers-ai default, anthropic requires _apiKey), _apiKey condition, context for disambiguation. Adds meaning beyond schema.

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

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

Description clearly states it compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks by score, and surfaces most/least recognized. Example use-case given. Distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison).

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

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

Explicitly states usefulness for competitive AI-marketing audits. Implies when to use over alternatives (side-by-side vs single check), but does not explicitly say 'when not to use' or name alternative tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. Description adds behavioral details: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, sources_failed will list timed-out sources. 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?

Single paragraph that is front-loaded with core purpose. Every sentence adds value, covering scope, usage, return values, and error handling. 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?

No output schema exists, but the description fully explains return values (summary block with fields, per-advisory detail, links, alternative versions) and error handling. Given the tool's complexity and lack of output schema, this is complete.

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

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

Schema description coverage is 100%. Description adds meaning: 'package' accepts scoped npm packages, 'version' defaults to latest when omitted. 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 it is a composite check for evaluating npm packages covering licenses, advisories, version history, and bundle size. It distinguishes itself from sibling tools by specifying it is for the NPM ecosystem only and directing other ecosystems to deps.dev:version.

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

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

Explicitly states when to use: when an agent asks 'is X safe/popular/small' or 'what does adding lodash cost me'. Also provides exclusion guidance: NPM ecosystem only in v1; PyPI/Maven/Cargo/Go fall under deps.dev:version directly.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false), the description adds crucial details: it downloads the full ~16,000 scheme list (~1-2MB), filters client-side with case-insensitive token matching, and notes it is 'Keyless'. 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?

Three concise sentences front-loaded with the main purpose. Every sentence adds essential information: what it does, how it works, and its role in the tool ecosystem. 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 and no output schema, the description covers all necessary context: purpose, behavior (client-side filtering, download size), parameter semantics, and its relationship to sibling tools. The output (scheme_code) is explicitly mentioned.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by explaining the matching logic for 'query' (every word must match in any order) and notes the default limit. This goes beyond the schema, which only provides basic descriptions.

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

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

The description clearly states 'Find Indian mutual-fund scheme codes by fund name' with a specific verb and resource. It distinguishes this tool from siblings like get_nav_history and latest_nav by explaining it obtains the scheme_code needed for those 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 gives clear context: this tool is for obtaining scheme_codes for get_nav_history and latest_nav. It also mentions the download size and matching logic. However, it does not explicitly state when not to use this tool or provide alternatives for other lookup purposes.

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

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

Discloses embedding model (BGE-base-en), similarity measure (cosine), window size (500-char overlapping), character cap (200K) with truncation and flagging. Adds value beyond readOnlyHint=true annotations.

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

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

Single well-structured paragraph: purpose first, usage guidance, technical details, all concise without 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?

Covers purpose, usage, technical details, and limitations (cap, truncation) completely. No output schema needed for this tool's 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 description coverage is 100%; description includes default for limit (5) and query examples, adding context beyond schema.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' with specific examples (SEC 10-K, article, tool result). It distinguishes from sibling tools by mentioning pairing with ask_pipeworx_grounded, showing unique value.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and mentions pairing with ask_pipeworx_grounded, but does not explicitly state when not to use or compare to all siblings.

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

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

Annotations indicate non-readonly, idempotent, non-destructive. The description adds meaningful context: returns new subscription ID, requires OAuth, details delivery channels, email/SMS constraints, webhook signing secret given once, and auto-disable after 10 failures. 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 dense but front-loads the core purpose and ID. It packs many details into one paragraph; a cleaner structure with sections could improve readability, but it remains reasonably 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 complexity (3 params, nested objects, no output schema), the description is comprehensive. It covers all types, parameters, delivery methods, and limitations, enabling correct invocation without 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 coverage is 100%, but the description adds substantial value beyond schema: detailed examples for each type-specific params, explanation of delivery sub-objects, and constraints like SMS verification and webhook signing.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the subscription id. It distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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

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

The description provides when to use the tool (for live-data event streams) and requires a Pipeworx OAuth account. It lists supported types with examples but does not explicitly state when not to use it or contrast with alternatives like listing existing subscriptions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as safe/non-destructive. The description adds behavioral context such as returning examples drawn from the live catalog, no arguments gives full spread, and topic filtering, which is valuable beyond the annotations.

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

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

The description is front-loaded with common queries and organized, but it is somewhat verbose with repetitive phrasing (e.g., 'the onboarding entry point') that could be trimmed. Overall, it is functional 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?

Given no output schema, the description thoroughly explains what the tool returns (category-bucketed example questions, tool+argument shapes) and when to use it. It covers the use case and behavior completely for a discovery tool with annotations.

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

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

Schema coverage is 100% with a clear parameter description. The description adds meaning by providing example topics, noting that omitting topic gives a cross-category spread, and explaining the effect of the parameter on the output.

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

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

The description clearly identifies the tool as an onboarding entry point that returns category-bucketed example questions with tool+argument shapes. It distinguishes itself from siblings (like ask_pipeworx, discover_tools) by specifying its role in helping new users understand what Pipeworx can do.

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

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

The description explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools', providing clear when-to-use guidance and an alternative context.

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

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

Adds significant context beyond annotations: ownership enforcement, deactivation instead of deletion, and linkage to recent_alerts. Consistent with annotations (non-destructive, idempotent). 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?

Two sentences, no waste. First sentence delivers core action, second adds key behavioral details. Efficient 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?

Covers ownership, effect (deactivation), and retention of historical data. No output schema, so return value not needed. Could mention idempotency or side effects, but sufficient for a simple mutation 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 already covers id parameter with description 'Subscription id (uuid) returned by subscribe.' Description adds no additional parameter information. Schema coverage is 100%, so baseline 3 is appropriate.

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

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

Clearly states action 'Cancel a subscription by id.' Differentiates by mentioning ownership enforcement and effect on historical events via recent_alerts, distinguishing it from sibling tools like subscribe and list_subscriptions.

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

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

Explicitly states ownership constraint ('you can only cancel your own subscriptions'). Does not explicitly list when not to use, but context with sibling tools implies alternatives. Provides context about deactivation vs deletion.

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; description adds critical operational nuance: distinguishes 'could_not_verify' (check did not happen, carries error) from 'unsupported' (no source exists), defines all verdict values, and discloses the return includes a pipeworx:// citation and reasoning. Also reveals it replaces 4–6 sequential calls.

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: front-loaded query phrasings and purpose, followed by path details, return contract, and an 'IMPORTANT for callers' note. Every sentence adds value, though the run-on opening sentence could be split for readability.

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

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

For a complex tool with no output schema, the description covers the full return contract (verdict values, actual value with citation, reasoning), the two execution paths, and the crucial error semantics. It provides enough detail for an agent to correctly interpret results and handle failure 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?

Both parameters are fully documented in the schema (100% coverage), so baseline is 3. The description adds minor context about percent-delta math and tolerance override, but the schema descriptions for 'claim' and 'tolerance_pct' already convey the necessary semantics.

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 opens with natural-language query forms and clearly states 'natural-language claim verification against authoritative sources.' It distinguishes from sibling research tools by focusing on fact-checking and details two specific execution paths (SEC/XBRL for company financials vs. grounded pipeline for everything else).

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

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

Explicitly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also provides sub-guidance for company-financial vs. other claims. No explicit exclusions or named alternatives, but the scope is clearly bounded.

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