Nist Beacon

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. The description adds behavioral context: it scores from 0-100, returns per-model results with raw response, and notes that Anthropic calls incur direct costs via a BYO key. 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 two sentences, front-loading the core action and then adding key details. Every sentence adds necessary information with no fluff. The structure is clear and easy to scan.

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 clearly outlines the return structure (per-model {score, confidence, signals, raw_response} + combined view). It covers required and optional parameters, model selection, and use cases. No gaps for an agent to infer missing behavior.

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

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

Schema coverage is 100%, so parameters are already well-documented. The description adds value beyond the schema by clarifying the default model for 'models' (Workers AI), that '_apiKey' is only needed for Anthropic, and that 'context' helps disambiguate. This extra context improves usability.

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

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

The description explicitly states the tool probes LLMs for knowledge about a business/brand/product/topic and scores visibility (0-100) per model. The verb 'probe' and resource 'LLMs' are specific, and the tool clearly differs from siblings like 'ask_pipeworx' or 'bet_research' by focusing on AI visibility audits rather than general Q&A or betting.

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 mentions when to use the tool ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains default vs. Anthropic model usage with API key requirements. However, it does not explicitly state when not to use it or list alternative tools for specific scenarios.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and no destructiveness. Description adds context about routing to tools, filling arguments, and returning citation URIs. No contradictions. Provides behavioral details beyond annotations.

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

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

Description is front-loaded with key directive 'PREFER OVER WEB SEARCH' and includes examples, but is somewhat verbose. Every sentence adds value, though could be slightly trimmed for conciseness.

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

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

Given the tool's high complexity (5,245 tools, 1369 sources), the description is very complete: covers purpose, usage, alternatives, examples, and behavior. No output schema, but return type (structured answer with citations) is described.

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

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

Schema coverage is 100% with clear descriptions for the question parameter and its aliases. The description does not add new parameter semantics beyond what the schema provides, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool routes questions to 5,245 tools and returns structured answers with citations. It uses specific verbs like 'routes', 'fills arguments', and 'returns', and distinguishes from siblings like ask_pipeworx_grounded and deep_research.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and provides detailed when-to-use guidance for various question types. Also lists specific alternatives (ask_pipeworx_grounded, deep_research) and when to use them, including handling breaking news.

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?

Provides context beyond annotations: it is a working router, experimental, with fallback to nothing. Also mentions that results are compared against stable router for merges, adding transparency about its beta nature.

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

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

Very concise single paragraph, front-loaded with purpose and key information, with no unnecessary words.

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

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

Given the tool's nature as a beta router with no output schema, the description is complete: it explains the relationship to the stable version, current status, usage guidance, and behavior.

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

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

Schema description coverage is 100%, so baseline 3 is appropriate. The description does not add new information about parameters beyond what the schema already provides.

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

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

The description clearly states it is a beta version of ask_pipeworx, a universal router with 5,245 tools, and distinguishes it from the stable version by being the edge with candidate routing improvements.

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

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

Explicitly tells when to use: 'Use it exactly like ask_pipeworx when you want the newest routing'. Also explains the current inactive candidate state, so the agent knows it currently matches the stable router.

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

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

Annotations already provide readOnly, openWorld, idempotent, and non-destructive hints. Description adds rich behavioral context: routing over 5,245 tools, extracting answer only from tool result, explicit refusal reasons (not_in_source, no_tool_match, etc.), and cost implication (extra LLM call). 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?

Concise yet comprehensive: one compact paragraph with clear front-loading of purpose, followed by behavioral details, usage guidance, and cost note. No redundancy or filler.

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

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

Given no output schema, the description fully explains the structured response format (answer, evidence, confidence, source, fetched_at, refusal_reason) and possible refusal reasons. Covers all necessary context for high-stakes usage.

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

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

Schema coverage is 100% (6 parameters, all aliases for 'question'), so baseline is 3. The description summarizes that aliases are accepted and instructs to ask in natural language, but adds minimal value beyond the schema definitions.

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

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

The description clearly defines the tool as a hallucination-resistant answer mode for high-stakes reads, with specific verb 'extracts answer' and resource 'tool result'. It distinguishes from sibling 'ask_pipeworx' by highlighting extra LLM call and use case.

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

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

Explicitly states when to use: when answer will be quoted, cited, or acted on (financial, legal, medical, public statements), and when not: prefer ask_pipeworx for casual lookups. 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, indicating safe idempotent reads. The description goes far beyond annotations with exhaustive behavioral details: resolution process, fan-out logic, classifiers, response shapes, resolver contract (market_match_confidence etc.), parent event extractor, news fields with fallback, short-circuit scenarios (low confidence, closed markets, wide spreads), and resolution-rule risk. No contradictions with annotations.

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

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

The description is very long (multiple paragraphs) but densely packed with essential information. It uses all-caps section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) for structure, which aids readability. However, some redundancy exists (e.g., 'RESOLVER CONTRACT' details could be more concise). The length is justified by complexity but still could be trimmed.

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

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

For a tool with 3 parameters, 100% schema coverage, no output schema, and complex behavior (fan-out, classifiers, resolution rules), the description covers all necessary aspects: input formats, detailed response shapes, resolver contract with confidence scoring, parent event extraction, news fallback, safety short-circuits, closed-market handling, illiquid spread notes, and cancellation rule risk. It leaves no important gaps for agent decision-making.

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

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

Schema coverage is 100% for all 3 parameters. The description adds value by explaining the market parameter accepts slug, URL, or question text (also in schema but reinforced), depth parameter includes concrete definitions ('quick = 2-3 evidence sources, thorough = full fan-out. Default thorough.'), and include_raw parameter behavior (summarized vs full payloads). This enriches understanding beyond the schema alone.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, or question text) and output (evidence packet + market-vs-model comparison). This distinguishes it from sibling tools like ask_pipeworx which are for general queries.

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 provides usage scenarios: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' While it doesn't explicitly state when not to use, the specialization for Polymarket bets makes the context clear. It could benefit from mentioning alternatives like ask_pipeworx for non-Polymarket queries, but the guidance is sufficient.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, so the description adds minimal value. However, it fails to disclose any additional behavioral details such as output format or potential limitations.

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?

Extremely concise (two words), but at the expense of informativeness. The structure lacks any meaningful content; it is under-specified rather than efficiently 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?

Despite having an output schema, the description fails to provide sufficient context about the tool's purpose or input. It is incomplete for a tool that has a required parameter and belongs to a large sibling set.

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

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

With 0% schema description coverage, the description must compensate but does not. It offers no explanation of the 'chain_id' parameter's meaning, valid values, or relationship to 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?

Description 'Chain metadata' is a tautology, restating the tool name without a specific verb or resource. It does not clarify what action the tool performs or what kind of metadata is returned.

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

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

No guidance provided on when to use this tool versus its many siblings. The description lacks any contextual hints for selection.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint. Description adds behavioral details: pulls LATEST 10-K data, handles off-calendar fiscal years, sorts by primary metric, returns paired data with citation URIs, and replaces 8-15 sequential lookups. No contradictions; significant added 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?

Single dense paragraph with no wasted words. Front-loaded with example queries, then clear purpose, then type-specific details. Every sentence adds value: efficiency claim, data sources, sorting behavior, return format.

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 (paired data + citation URIs). Covers types, data sources, constraints, sorting, and off-calendar handling. Given tool complexity, the description is comprehensive and leaves no critical gaps.

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

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

Schema coverage is 100% but description adds meaning: explains what each type pulls (company: revenue, net income, cash, debt; drug: adverse-event counts, FDA approvals, trial counts), provides example values (tickers/CIKs for company, names for drug), and clarifies min/max constraints (2-5).

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

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

The description uses specific verbs and resources: 'side-by-side comparison of 2-5 companies or drugs in one parallel call', lists example queries, and explicitly distinguishes from sequential single-pack lookups. It clearly states the data pulled for each type and that results are sorted by primary metric.

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: comparisons like 'X vs Y', 'which is bigger', 'rank these companies', and instructs 'ALWAYS PREFER over sequential single-pack lookups'. Provides context on data sources (SEC EDGAR/XBRL, FAERS) and how off-calendar fiscal years are handled.

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, openWorld, idempotent, non-destructive), the description discloses account tiers, depth behavior (quick=3 facets, standard=5 with gap recovery, thorough=8 with iterative chase), parallel execution, output format (findings packet with citations, gaps, contradictions), expected latency (15-90s), and semantic excerpting. No contradictions with annotations.

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

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

The description is lengthy but every sentence serves a purpose, front-loading account requirements and sibling comparisons. It is well-organized but could be slightly more concise by grouping related details. The density is justified by the tool's complexity.

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

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

Despite no output schema, the description fully explains the return format (findings with evidence, confidence, source, fetched_at, pipeworx:// citation, gaps, contradictions, hop field) and covers all aspects: prerequisites, parallelism, latency, edge cases (gap recovery, excerpting). No critical missing information.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds significant value by explaining depth levels in detail (quick=3, standard=5+gap recovery, thorough=8+lead chase) and clarifying that the question parameter accepts broad/multi-part queries. This exceeds 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 the tool performs grounded multi-source research across 1369 structured data sources in one call, distinguishing it from siblings like ask_pipeworx by emphasizing it decomposes questions into facets and runs tools in parallel. The verb 'research' and resource 'structured data sources' are 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?

Explicit guidance is provided: when to use this tool (broad/multi-part questions over structured data), when to use ask_pipeworx (single lookups, breaking news, or current events), and account requirements (free sign-in, paid for 'thorough'). This leaves no ambiguity about tool selection.

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

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

Annotations indicate readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds beyond annotations by specifying the return format (top-N tools with names, descriptions, schemas, curated examples) and stating results are 'ready to call directly, no second schema lookup needed.' No contradictions.

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

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

The description is concise (3-4 sentences), front-loaded with purpose, and efficiently lists domains. Every sentence adds value; no fluff or redundancies.

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

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

Despite no output schema, the description explains what is returned (names, descriptions, schemas, curated examples, ready to call), which is sufficient for a discovery tool. Examples in the input schema complement this. The tool is simple and fully specified.

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 value by summarizing key parameter info: it explains that 'query' accepts natural language and lists aliases (task, q, description, search) with examples. This aids understanding beyond the schema's per-parameter descriptions.

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

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

The description clearly states the verb 'Find tools by describing the data or task' and specifies the resource (tools). It distinguishes from sibling tools by explicitly saying 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' The list of domains further clarifies scope.

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

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

The description provides clear usage context: 'Use when you need to browse, search, look up, or discover what tools exist for...' and advises calling it first when exploring many tools. It implicitly guides when to use (discovery vs. direct call) but does not explicitly state when not to use or list 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 declare the tool as read-only, idempotent, and non-destructive, which is consistent with the description. The description adds operational details like fanning out across multiple sources, potential soft-failure of patents, and the specific data returned, going 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 examples and a clear summary, followed by detailed behavioral notes. While it is somewhat lengthy, each sentence serves a purpose, and the structure is logical. It could be slightly more concise, but it remains effective.

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

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

Given only two parameters and no output schema, the description fully compensates by detailing every return field (CIK, filings, fundamentals, patents, news, LEI) and even noting edge cases like patent API sunset. It provides a complete picture of the tool's behavior and output.

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 both parameters with descriptions. The description reinforces the schema by providing examples (e.g., 'AAPL', '0000320193') and reiterating the name constraint. However, it adds little semantic value beyond what the schema already provides, earning a baseline score of 3.

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

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

The description clearly identifies the tool's purpose: to provide a holistic cross-source profile of a US public company. It gives example queries ('Tell me about X') and explicitly states it should be preferred over chaining multiple single-source lookups, distinguishing it from sibling tools.

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

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

The description provides explicit guidance: always prefer this tool over chaining individual lookups for a holistic view, and it notes that names are not supported, directing the agent to use resolve_entity first. This covers when to use and 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 destructive hint; the description adds context about when to use and what constitutes destructive behavior (clearing sensitive data). Adds value beyond annotations.

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

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

Two sentences: action and usage. Front-loaded and 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 delete operation with one required parameter and no output schema, the description fully covers purpose, usage, and behavior.

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

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

Schema coverage is 100% and the parameter description 'Memory key to delete' is straightforward. The tool description adds no 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?

Clearly states it deletes a stored memory by key, distinguishing from '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 lists scenarios for use: stale context, task completion, or clearing sensitive data. Also suggests pairing with related tools.

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

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

The description discloses the tool's behavior: fetches page, extracts title/description/key links, outputs standard markdown. Annotations already indicate read-only, idempotent, non-destructive, so the description adds process details. Could mention error handling or rate limits, but overall transparent.

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

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

The description is two sentences plus a bullet list, front-loaded with the primary action. Every sentence adds value without redundancy or fluff.

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

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

Given the rich annotations and full schema, the description covers the tool's operation and output format. The absence of an output schema is compensated by the clear explanation of the returned text blob.

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

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

Schema coverage is 100% with both parameters described. The description adds minimal extra meaning beyond the schema (e.g., 'fetches the page' for url). Baseline 3 is appropriate.

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

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

The description clearly states it generates a production-ready llms.txt file for any URL, detailing the process and output format. It distinguishes from sibling tools like scan_competitor_ai_presence by focusing on creating a specific file for AI crawlers, though not explicitly naming alternatives.

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

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

The description lists explicit use cases (client indexing, own project, competitor auditing) providing clear context. It does not mention when not to use it or alternatives, but the use cases effectively guide selection.

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

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

Annotations already indicate read-only, idempotent, open world. The description adds useful behavioral context: the value is signed by NIST and updated every 60 seconds. 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?

Single sentence, front-loaded with the verb 'Fetch'. Every word adds value, 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 no parameters and an existing output schema, the description fully covers what the tool does: fetches the latest pulse with its key attributes. No additional information is 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?

No parameters exist, so the description need not add parameter info. The schema coverage is 100%, and the description mentions no parameters, which is appropriate. Baseline 4.

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

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

The description clearly states it fetches the most recent NIST Randomness Beacon pulse, specifying the output as a publicly verifiable, timestamped 512-bit random value signed by NIST. This distinguishes it from siblings like pulse_at (which likely fetches a specific timestamp).

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

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

The description implies usage for the latest pulse by saying 'most recent'. It provides clear context but does not explicitly mention alternatives or when not to use this tool. Given the sibling list, the description could be more explicit, but overall it is adequate.

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, but the description adds no behavioral context beyond that. It does not mention what 'pulse' means, edge cases, or response details, missing an opportunity to add value.

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

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

The description is extremely short (4 words), but this is under-specification rather than effective conciseness. It does not front-load critical information to aid agent understanding.

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 low complexity (1 param, no nested objects) and presence of an output schema, the description should at least explain what a 'pulse' is and what the tool returns. It fails to do so, leaving the tool definition incomplete.

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 has 0% description coverage, and the description provides no info about the single parameter 'chain_id'. It only says 'Latest pulse in chain', which does not clarify the parameter's purpose or format.

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 'Latest pulse in chain' is vague and tautological. It does not clearly state what action the tool performs or what a 'pulse' is. Among siblings like 'last_pulse' and 'pulse_at', it fails to distinguish itself.

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

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

No guidance on when to use this tool vs its siblings. For instance, it does not explain how it differs from 'last_pulse' or 'pulse_by_chain_pulse', leaving the AI agent without criteria for selection.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. Description adds return field context and default behavior (active only), which is helpful but does not significantly extend beyond annotations.

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

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

Two sentences: first states purpose and return fields, second gives usage guidance. No fluff, front-loaded.

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

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

Tool is simple (1 optional param, no nested objects, no output schema). Description fully explains purpose, return fields, parameter, and usage context. No gaps.

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

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

Schema coverage is 100% with 'include_inactive' well-described. Description adds no new parameter details, so baseline of 3 applies.

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

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

The description clearly states 'List the caller's active subscriptions' and enumerates return fields (id, type, etc.), distinguishing it from sibling subscription tools like 'subscribe' and 'unsubscribe'.

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

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

Provides explicit use cases: 'review what you're monitoring before adding more' and 'find an id to cancel'. Does not state when not to use, but context is sufficient.

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 minimal (no readOnly, destructive, etc.), so the description provides crucial behavioral context: rate-limited to 5 per day per identifier, free, and doesn't count against quota. This adds significant value beyond annotations.

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

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

Every sentence serves a purpose. The description is front-loaded with the main action ('Tell...') and is concise without unnecessary words. It packs guidelines, behavioral notes, and parameter hints in a compact form.

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 (3 params, 2 required, no output schema), the description provides complete guidance: how to fill each field, what not to do, rate limits, and quota info. Nothing essential is missing.

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

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

Schema coverage is 100% (all parameters described). The description adds meaning by explaining the enum values (e.g., 'bug = something broke...'), message length limits, and that context is optional. It complements the schema well.

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: sending feedback to the Pipeworx team. It uses specific verbs ('tell... team something is broken') and defines the resource (the team). It distinguishes from all 50+ sibling tools, none of which are feedback 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 the tool: for bugs, missing features/data gaps, or praise. It also provides a 'don't' instruction (don't paste the end-user prompt), offering clear guidance on appropriate usage.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false; the description adds valuable details about the data source (CF analytics-engine), privacy (no PII), and caching (5min-1h), enhancing transparency beyond annotations.

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

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

The description is concise (4-5 sentences), front-loads the core purpose, and uses bullet points for use cases, providing maximum information with minimal 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?

The description covers what the tool returns, the optional parameter, data derivation, caching behavior, and absence of PII, making it complete for a simple read-only tool with good annotations.

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

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

Schema coverage is 100% and describes the window enum, but the description adds semantic guidance ('shorter windows surface what's hot right now; longer windows show steady-state demand') that helps agents choose appropriately.

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 returns top tools, top packs, and total call volume over a recent window, distinguishing it from siblings like 'ask_pipeworx' or 'discover_tools' which serve different purposes.

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?

Three explicit use cases are given (discovering hot data sources, confirming canonical tool, aligning use case), providing clear context for when to use, though no exclusions or alternatives are mentioned.

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 thoroughly discloses behavioral traits beyond annotations. It explains the scanning process, partition filter (placeholder check, Jaccard similarity), fill check against CLOB depth, and output structure. Annotations indicate readOnlyHint=true, openWorldHint=true, etc., and the description adds context about monotonicity violations, partition sum checks, and when to avoid trades. No contradictions.

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

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

The description is well-structured and front-loaded with the core purpose, then explains modes. It uses formatting (backticks, bolding) for clarity. While reasonably concise given the complexity, it could be slightly more compact; however, every sentence adds value.

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

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

Despite lacking an output schema, the description explicitly details the response fields: 'opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context)' and partition_check fields. It covers all edge cases (placeholder slugs, fill check, cross-event similarity) and references related tools, providing a complete picture.

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 good parameter descriptions, but the description adds valuable context: for `event`, it notes 'Full Polymarket URLs also accepted'; for `topic`, it explains the cross-event search and monotonicity check. This goes beyond the schema's basic descriptions, providing practical usage tips.

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.' It specifies the verb (find), resource (arbitrage opportunities on Polymarket), and method. It distinguishes from sibling tools like polymarket_edges and polymarket_fill_risk by focusing specifically on arbitrage detection with monotonicity and partition checks.

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

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

The description provides explicit guidance on when to use each mode: 'Call with NO args for a trending_scan...; pass `event` for the strongest per-event partition_check, or `topic` for a themed cross-event scan.' It recommends `event` for specific markets and explains that cross-event mode catches patterns missed by single-event mode. It also warns against trading when the edge is not realizable and references polymarket_fill_risk for custom sizing.

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

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

The description goes well beyond annotations, detailing model families, output segments, edge calculation, caching, and diagnostics. It provides extensive behavioral context that aids agent understanding, without contradicting the readOnly, openWorld, idempotent, or non-destructive 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?

While well-structured with clear sections, the description is quite verbose (over 300 words) and includes many implementation details that could be summarized or moved to output schema. The most important purpose is front-loaded, 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 (9 parameters, no output schema), the description fully covers the tool's operation, output structure, caching, and edge cases like empty segments and diagnostics. The presence of annotations further supports completeness.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add additional parameter semantics beyond what the input schema already provides; it focuses on behavioral explanation rather than parameter details.

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

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

The description clearly states it scans Polymarket markets to return opportunities where Pipeworx data disagrees with market price, specifically for 'what should I bet on today'. This is a specific verb+resource purpose that distinguishes it from sibling tools like polymarket_arbitrage.

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

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

The description implies usage for discovering betting opportunities without paging through hundreds of markets, but it does not explicitly state when not to use it or mention alternatives among sibling tools. Lacks explicit when/when-not/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 include readOnlyHint, openWorldHint, idempotentHint. The description adds behavioral details beyond annotations: it explains the return structure (tracked[], expired[], snapshot_dates[]), that decay is computed on |edge_pp_net|, and that snapshots are written on cache-miss. No contradiction with annotations.

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

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

The description is fairly long but well-structured with ARGS, RESPONSE, LIMITS sections. It is front-loaded with the key question. While it could be slightly more concise, it is efficient given the complexity of the data returned.

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

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

With no output schema, the description thoroughly explains the return format: tracked[] with fields like first_seen, trend, decay_pp_per_day; expired[] with lifespan_days; snapshot_dates[]. It also covers limits like 60-day TTL and snapshot frequency. For a complex analytical tool, this is very 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%, but the description adds context: it specifies default values (days default 14, max 30), clamps, and that window corresponds to snapshot family with default '1wk'. This adds meaning beyond the schema's bare 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's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question: 'how long has this edge existed and is it shrinking?' This distinguishes it from siblings like polymarket_edges which likely provides current edges.

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

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

The description provides explicit context for when to use the tool, contrasting fresh vs. stale edges. It also mentions limits and snapshot behavior. While it doesn't explicitly state when not to use it, the sibling list includes polymarket_edges for current edges, implying the differentiation.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds rich behavioral context: walks the ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), explains risks of unhedged directional position and thin legs. No contradiction with annotations.

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

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

The description is relatively long but well-structured with clear sections (overall purpose, requirements, single-market details, basket details, usage warning). Every sentence adds value for a complex tool. Could be slightly more concise but remains effective.

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

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

Given the tool has 4 parameters, high schema coverage, and no output schema, the description provides comprehensive information: return fields for both modes (verdict, thin_legs, forced_directional_risk, etc.), risk explanations, and usage context. It fully equips an agent to use the tool correctly.

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

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

Schema coverage is 100% (all 4 parameters described). The description adds further meaning: explains side defaults for basket mode ('auto from partition sum'), clarifies size_usd interpretation differences between single-market and basket (settlement notional for basket), and states that one of `market` or `event` is required. This goes 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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes two modes (single-market and basket) and explicitly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by stating when to use this tool before them.

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

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

The description provides explicit usage context: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why (theoretical overround not capturable on thin books, partial fills create directional risk). However, it does not explicitly state when NOT to use it, though it is implied for small trades.

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

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

The description provides extensive behavioral context beyond annotations, such as the compatibility_warning conditions, temporal alignment significance, skipped cross-type/subtype counters, and the caveat that most pre-mapped topics return warnings. No contradiction with annotations.

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

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

The description is well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded with the core purpose. While somewhat verbose, each sentence adds necessary detail for understanding a complex tool.

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

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

Given the absence of an output schema, the description thoroughly explains the response structure, safety fields, and edge cases. It covers temporal alignment, skipped comparisons, and compatibility warnings, making the tool's behavior fully understood.

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

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

With 100% schema description coverage, the baseline is 3, but the description adds significant value: it explains the relationship between topic and explicit tickers, lists all topic shortcuts, and clarifies override behavior. This goes beyond the schema descriptions.

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

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

The description clearly states the tool's function: computing cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes two modes (topic shortcuts and explicit tickers) and explains the output, setting it apart from siblings like 'polymarket_arbitrage'.

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

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

The description explains when to use each mode and interprets the compatibility_warning, effectively guiding when spreads are meaningful. However, it does not explicitly mention when to use sibling tools for single-venue analysis, which would improve guidance.

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

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

Annotations indicate the tool is read-only and safe. The description adds behavioral detail: it returns the 'closest' pulse along with metadata, which is beyond annotation scope. 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?

A single, front-loaded sentence of 20 words that efficiently conveys the action, resource, input, and output. No fluff or redundancy.

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

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

The description covers purpose, input format, and output summary. With an output schema present and comprehensive annotations, the description is largely sufficient, though it omits potential error conditions or range constraints.

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

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

With 0% schema coverage, the description clarifies that time_ms is a Unix timestamp in milliseconds and that the tool finds the closest pulse. This adds meaning beyond the schema's type and required flag.

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

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

The description clearly states the tool fetches the NIST Randomness Beacon pulse closest to a given Unix timestamp, specifying the input format and output contents. It implicitly distinguishes from siblings like 'last_pulse' and 'latest_in_chain' by focusing on historical lookup.

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

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

The description provides context for when to use the tool (fetching a pulse near a specific timestamp) but does not explicitly exclude alternatives or compare with sibling tools, leaving the agent to infer usage boundaries.

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?

Although annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, the description adds no behavioral context. It does not describe the output, side effects, or any prerequisites, offering minimal value beyond the structured metadata.

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 5-word fragment without a complete sentence or structure. It is under-specified rather than concise, wasting the opportunity to provide clarity.

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

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

Despite having an output schema and moderate complexity (2 params, many siblings), the description is woefully incomplete. It fails to differentiate from sibling tools, explain what a pulse is, or give any operational context, making it nearly useless for an agent.

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

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

With 0% schema description coverage, the description must compensate. It hints that chain_id and pulse_id identify a specific pulse, but it does not define valid values, formats, or the meaning of 'pulse index'. The compensation is insufficient for an agent to know what parameters are acceptable.

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 'Pulse by chain + pulse index' is essentially a tautological restatement of the tool name. It fails to specify what a 'pulse' is or what operation the tool performs, leaving the purpose ambiguous.

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 no guidance on when to use this tool versus its many siblings (e.g., 'last_pulse', 'pulse_at', 'latest_in_chain'). No use cases, alternatives, or exclusions are mentioned.

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 (read-only, idempotent), description adds scoping per identifier, dual mode (specific key vs list all), and pairing with forget. Does not contradict annotations and enriches transparency.

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 action and resource, every sentence earns its place. No wasted words 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?

For a simple read tool with one param and no output schema, description covers core usage, scoping, and sibling relationships. Lacks explicit return format, but overall sufficient.

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

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

Schema coverage is 100% and baseline is 3. Description adds examples (ticker, address, notes) and explains behavior when key is omitted, providing meaningful enrichment 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 or lists saved memory values, using specific verbs and referencing the 'remember' sibling for context. It distinguishes from siblings 'remember' (save) and 'forget' (delete).

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

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

Provides clear context: use to look up previously stored context without re-deriving. Implicitly contrasts with remember/forget siblings, but no explicit 'when not to use' or alternative conditions.

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

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

The description discloses key behaviors beyond annotations: it explains what each returned event includes (source, citation_uri, payload), the effect of mark_read on subsequent calls, and that polls work without side effects. Annotations already indicate idempotent and read-only, so the description adds context 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 concise—five sentences, each serving a purpose. It front-loads the main action, then details outputs, filtering, the mark_read mechanism, and an alternative access method. No redundant or irrelevant information.

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

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

Given the tool's moderate complexity (5 parameters, no output schema), the description covers everything needed: what is returned, filtering options, the crucial mark_read behavior for polling, and an external access method. It's 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?

Schema coverage is 100%, so baseline is 3. The description adds value by stating default limit (50) and clarifying how mark_read affects future calls, which goes beyond the schema's simple 'Flag the returned events read.' This extra context justifies a 4.

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

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

The description starts with a clear verb+resource: 'Pull fired events from your subscription feed.' It explicitly states what the tool does and distinguishes itself from siblings like 'list_subscriptions' by focusing on events/alerts, not subscriptions. The purpose is 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 provides explicit guidance: it mentions polling works fine, describes the effect of mark_read for sequential calls, and even offers an alternative URL for scripts/dashboards. This helps the agent decide when to use this tool versus other access methods.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds detailed behavioral context: fan-out to multiple sources, fallback logic (GDELT preferred, GNews when rate-limited), and USPTO soft-fail. Only minor omission: no explicit error handling.

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 with every sentence adding value. It front-loads example queries but could be slightly more structured (e.g., bullet points). Still, very 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?

Given no output schema, the description explains the return structure (changes[], count, citation URIs). It also notes USPTO status. For a complex multi-source tool, it is well-rounded. Minor: does not specify pagination or max 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% with parameter descriptions. The description adds value beyond schema: explains relative date shorthand, recommends '30d' or '1m', and clarifies value can be ticker or CIK. It also explains type is limited to company.

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

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

The description clearly states the tool provides a change feed for a company in a given time window. It uses specific verbs like 'fan out' and 'returns', and distinguishes from the sibling entity_profile tool.

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

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

The description gives example queries and explicitly advises using entity_profile when a static profile is needed instead of a change feed, providing clear when-to-use and when-not-to-use guidance.

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

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

Discloses persistence behavior: scoped by identifier, authenticated vs anonymous sessions (24 hours). Annotations provide idempotentHint=true, and description aligns with 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?

Compact and front-loaded: first sentence states purpose, then usage, then details. Every sentence adds value with no redundancy.

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

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

Given tool simplicity and rich schema/annotations, description fully covers when, how, and what to store, plus pairing with siblings. No gaps.

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

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

Schema covers both parameters with clear descriptions. Description adds value by giving example key names and explaining scoping by identifier, but schema already does the heavy lifting.

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

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

The description clearly states the tool saves data for reuse, with examples of what to store (resolved ticker, address, etc.). It 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 tells when to use: 'when you discover something worth carrying forward'. Also mentions pairing with recall/forget, giving clear guidance on 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=true, idempotentHint=true, destructiveHint=false, which the description does not contradict. Beyond annotations, the description adds valuable behavioral context: internal cascading through multiple endpoints ('replaces 2-3 manual lookups') and detailed return formats for each type, including official IDs and citation URIs.

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

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

The description is well-structured with examples in natural language and a bulleted list of types. Each sentence adds value, though slightly verbose in listing output details; still, no redundancy, and front-loading key instructions ('Use FIRST') aids quick comprehension.

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

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

Given no output schema, the description fully compensates by explaining return values for both types, including official IDs and citation URIs. It also notes internal cascading behavior and auto-disambiguation, making the tool's behavior completely predictable for the 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?

Although schema coverage is 100%, the description significantly enriches parameter semantics by providing concrete examples of valid inputs (e.g., ticker 'AAPL', CIK '0000320193', name 'ozempic') and explaining auto-disambiguation for company type. It bridges the gap between raw schema and real-world 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's purpose: resolve a user-spoken name to a canonical identifier, with specific examples like 'ticker for...' and 'find the CIK for...'. It also lists supported types (company, drug) and distinguishes the tool from siblings by emphasizing it returns IDs needed by other 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 advises 'Use FIRST whenever you have a name but need an ID,' providing clear context for when to use this tool. While it does not explicitly list alternatives among siblings, the directive to use it first implies priority over other lookup tools, which is sufficient guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint, openWorldHint. Description adds that it probes, ranks, and returns score/confidence/signal density, but does not disclose additional behavioral traits like rate limits or auth requirements beyond schema. Adds some context but not significantly 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?

Three sentences, each purposeful: what it does, how it works, use case and return. No redundancy, efficient and front-loaded.

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

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

With no output schema, description adequately describes return (ranked list with score, confidence, signal density). Mentions input structure (entities + optional params). Misses explicit mention of entity count limit (2-8 from schema) but still complete enough for typical 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?

Schema coverage is 100%, baseline 3. Description adds semantics: first entity treated as 'subject' for narrative, entities [2-8], and context disambiguates names. This provides clearer usage guidance beyond the schema definitions.

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

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

Description clearly states tool compares AI visibility across multiple entities by probing each with ai_visibility_check, ranking by score, and identifying most/least recognized. Concrete example clarifies use case. Distinguishes from sibling 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 frames usage for competitive AI-marketing audits with an example question. Does not specify when to avoid or list alternatives, but context is clear enough for an agent to infer single-entity checks use ai_visibility_check.

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

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

Annotations indicate read-only and idempotent. The description adds critical behavioral details: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed list will be included on timeout. 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 a single well-structured paragraph that front-loads the purpose and then details sources, use cases, limitations, and error handling. While comprehensive, it is slightly long but no unnecessary content.

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

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

Given the tool's complexity (multiple external sources, no output schema), the description adequately explains the return values (summary block, advisories, links, alternatives), error handling, and ecosystem scope. It provides sufficient context for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds that version defaults to the latest when omitted, and that scoped packages are accepted for package, which is not in the schema description. This adds meaningful context.

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

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

The description clearly states the tool's purpose as a composite check for assessing npm packages, using deps.dev and bundlephobia. It specifies the ecosystem (NPM only) and the return structure, making it distinct from sibling tools.

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

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

Explicitly tells when to use: 'whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'. Also provides alternatives: '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?

Annotations already indicate readOnly and idempotent. Description adds key behavioral details: embedding model (BGE-base-en), cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag. No contradiction with annotations.

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

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

Two concise paragraphs, front-loaded with the core purpose and use case. Every sentence adds relevant 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?

Despite no output schema, the description adequately explains return values (passages with offsets and similarity scores). The complexity of semantic search with caps is fully addressed.

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

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

Schema coverage is 100% with good descriptions. The description adds value by giving example queries and explaining the truncation behavior for the text parameter, going slightly 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 performs semantic search inside a fetched record, using a natural-language query to return top passages. It distinguishes from siblings by emphasizing it's for searching within already-fetched text, not for broader search or external grounding.

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 the record is too large for the prompt, saving context. It also pairs with ask_pipeworx_grounded for grounding over passages, providing clear usage guidance 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 indicate write operation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds significant context: requires OAuth, returns subscription id, delivery channel behaviors (SMS rate limit 10/day, webhook auto-disabled after 10 failures, HMAC signing). This exceeds what annotations provide.

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

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

The description is front-loaded with the main purpose and is moderately sized. Every sentence adds value, though it could be slightly more concise by trimming some delivery details. Still, it is well-structured.

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

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

No output schema, but the description specifies 'Returns the new subscription id.' It covers all parameters, prerequisites, and behavioral nuances. Given the tool's complexity (multiple types, delivery channels), it is fully complete.

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

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

Schema coverage is 100%, and the description adds concrete examples for each type (e.g., sec_8k: items:['5.02']), explains required vs optional sub-fields, and details delivery behaviors (templated email, SMS verification, webhook signing). This adds 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 explicitly states 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This is a specific verb+resource that clearly distinguishes from siblings like 'unsubscribe' and 'list_subscriptions'.

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

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

The description states when to use the tool (create subscriptions) and prerequisites (Pipeworx OAuth account, anonymous/BYO not allowed). It details supported types and delivery options, but lacks explicit 'when not to use' guidance for alternatives like 'recent_alerts'. However, 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?

Annotations already indicate read-only, idempotent, non-destructive. The description adds value by detailing what the output contains (categorized questions with tool+argument shapes drawn from live catalog) and that it can be called with no arguments or a topic. 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 paragraph but well-organized: begins with common queries, then purpose, then arguments, then usage timing. All sentences add value, though slightly verbose for an onboarding 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?

Despite no output schema, the description adequately explains the return format: category-bucketed example questions with exact tool+argument shapes. It covers all necessary context for an onboarding tool, including parameter options and usage scenario.

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 single optional parameter. The description adds context by listing example topic values (finance, pharma, etc.) and explaining effect of omitting topic, but this is minor additional meaning beyond the schema description.

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

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

The description clearly states it is the onboarding entry point, listing example user queries and explaining it returns category-bucketed example questions with tool+argument shapes. It distinguishes from siblings like ask_pipeworx by explicitly saying 'Use this FIRST when you do not yet know what Pipeworx can do for you'.

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 guidance: call with no arguments for full spread, or pass topic for focus. It also says to use this FIRST when unsure of capabilities or to learn meta-tool calls. It lacks explicit 'when not to use' but context is clear.

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

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

Discloses that the row is deactivated not deleted, preserving historical events. This adds context beyond annotations (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?

Two sentences conveying all essential information without redundancy. Every sentence earns its place.

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

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

Tool is simple (1 param, no output schema). Description fully covers purpose, ownership, and behavioral nuance. No gaps.

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

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

Schema covers 100% of parameters with description. Description adds no extra detail beyond schema's 'Subscription id (uuid) returned by subscribe.' 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?

Clearly states 'Cancel a subscription by id' with specific verb and resource. Distinct from siblings '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?

Specifies ownership enforcement ('you can only cancel your own subscriptions'), providing clear context for when the tool should be used.

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

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

Annotations indicate read-only, idempotent, open-world, and non-destructive. Description adds rich behavioral details: two-tier processing (structured vs grounded pipeline), exact percent-delta math for financial claims, verdict types, and citation format. 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 packs essential info: examples, routing logic, return values. Slightly dense but front-loaded with query patterns. No wasted sentences, though could benefit from brief bullet points for readability.

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

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

Covers main use cases, parameters, return values, and internal routing. Missing edge cases like ambiguous claims or error handling, but given tool complexity and good annotations, it is sufficiently complete.

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

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

Both parameters have schema descriptions (100% coverage). Description adds value by explaining tolerance_pct usage: 'set 1–2 for hallucination detection' and default behavior. Provides practical guidance 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 the tool is for natural-language claim verification, distinguishes between financial claims (SEC EDGAR/XBRL fast path) and other claims (grounded pipeline). Uses strong verb 'verify' and concrete examples of queries. Differentiates from siblings like 'ask_pipeworx_grounded' and 'deep_research'.

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 whenever the agent needs to check whether something a user said is factually correct.' Provides context on when to use, but lacks explicit 'when not to use' statements. However, the scope is well-defined, and siblings cover other use cases like general Q&A.

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