Data Nashville

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

Annotations already provide readOnlyHint, idempotentHint, etc. Description adds behavioral details: default model, API key requirement, return structure (per-model {score, confidence, signals, raw_response} + combined view), and that API key is passed straight through. No contradictions.

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

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

Description is three sentences with no wasted words. First sentence states main purpose and output, second explains model flexibility, third gives use cases. Front-loaded with key action.

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

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

Despite no output schema, description clearly explains return structure and all parameter behaviors. Covers use cases and model selection. With annotations covering safety, this is a complete description for the tool's complexity.

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

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

Schema coverage is 100% so baseline is 3. Description adds beyond schema: default model behavior for 'models' param, explanation that '_apiKey' is passed directly to Anthropic, and purpose of 'context' param for disambiguation.

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

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

Description clearly states the tool probes LLMs for knowledge about a business/brand/product/topic and scores visibility 0-100 per model. Uses specific verb 'probe' and identifies resource 'LLMs' and outcome 'score visibility'. Distinguishes from siblings by focusing on visibility scoring.

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

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

Description provides explicit use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' Also explains model selection (default free, Anthropic with API key). Lacks explicit when-not-to-use or direct alternatives, but context is clear.

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

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

Annotations already declare the tool safe (readOnlyHint, idempotentHint, non-destructive), and the description adds genuinely useful behavioral context: it routes to one of thousands of source tools, returns a structured answer with stable pipeworx:// citation URIs, works on every tier, and makes a single fast call. This goes beyond the structured annotations without contradicting them.

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

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

The description is long but information-dense and well-structured: opening directive, scope statement, routing behavior, canonical trigger phrases, examples, and escalation guidance all appear in a logical order. Every sentence adds decision-relevant value, though some trimming of the lengthy domain list would not hurt.

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

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

For a single-parameter Q&A tool with no output schema, the description covers what the tool does, what kind of questions to ask, what the output looks like (structured answer + citation URIs), how it compares to alternatives, and when to escalate. An agent has everything needed to invoke it correctly and interpret the result.

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

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

Schema description coverage is 100% and the sole required parameter 'question' is clearly documented with aliases, so the description does not need to add parameter-level detail. The included examples reinforce what kind of question to pass, but they do not materially add beyond the schema, so baseline 3 is appropriate.

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

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

The description names a specific, high-value purpose: answering factual questions about real-world data across many domains, and frames itself as the default entry point versus its siblings. It explicitly differentiates from ask_pipeworx_grounded and deep_research by scope and use case, so an agent can select it correctly without inspecting other schemas.

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

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

It gives explicit trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much', 'current'), says to prefer it over web search for structured data questions, and names concrete escalation paths: ask_pipeworx_grounded for verbatim evidence and deep_research for broad/multi-part questions. This is model guidance for 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?

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses critical behavioral traits: it may have candidate routing improvements enabled live, the current state has no active candidate and matches ask_pipeworx exactly, and it is a full working router with no fallback. This transparency about variable behavior over time exceeds what annotations convey and directly informs invocation.

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 and front-loaded, leading with the core identity (beta version of ask_pipeworx, identical router) and moving through status, usage, and safety. It is information-dense with minimal redundancy, though the final sentence ('Falls back to nothing...') could be seen as a slightly repetitive reassurance given the earlier claim of being a full working router.

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 is, its current behavior, when to use it, and its relationship to the stable counterpart. Given the rich annotations and high schema coverage, the only missing element is an explicit statement of return value, but no output schema exists and the description already establishes that the response shape matches ask_pipeworx.

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

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

The input schema provides 100% coverage: every parameter is described, including the main 'question' field and all five aliases (q, text, input, query, prompt). The description adds no extra parameter semantics beyond referencing 'same arguments' as ask_pipeworx, so it correctly stays at the baseline for high schema coverage.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, an identical universal router with a specific scope (5,743 tools, same arguments and response shape). It distinguishes it from the stable sibling ask_pipeworx and notes the experimental nature. However, it relies on the reader already knowing what ask_pipeworx does; the core action (routing a question to the appropriate tool) is implied rather than directly stated.

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

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

The description explicitly says to use it exactly like ask_pipeworx when wanting the newest routing, and clarifies that results are compared against the stable router. It names the alternative (ask_pipeworx) and provides the key condition of wanting experimental routing. It does not mention grounded or other alternative siblings, but the provided guidance is actionable and 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 readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, and the description does not contradict them. It goes further by disclosing refusal behavior with specific refusal_reason values, promising verbatim evidence quotes, noting the extra LLM call cost, and explicitly stating the tool will not invent facts. This is rich behavioral context beyond the annotations.

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

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

Although longer than a one-liner, every sentence earns its place: purpose, mechanism, return shape, refusal reasons, use cases, and cost tradeoff are all compressed into a dense but readable block. The critical grounding behavior and refusal semantics are front-loaded, and the alternative routing is stated at the end without wasted words.

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

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

Despite having no output schema, the description fully specifies the success return shape and the explicit refusal shape with enumerated refusal_reason values. It covers when to use, when not to use, cost implications, and the relationship to ask_pipeworx. For a tool of this complexity, nothing an agent needs to decide or invoke correctly is missing.

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

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

Schema description coverage is 100%, with all six parameters documented as aliases for the natural-language question. The description adds no parameter-level details beyond the schema, so the baseline of 3 applies. It mentions natural-language use context but does not need to compensate for any schema gap.

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 identifies a specific verb ('EXTRACTS the answer using ONLY what the tool result contains') and a clear resource ('Pipeworx' with grounded/hallucination-resistant behavior). It explicitly distinguishes itself from the sibling ask_pipeworx by naming the same routing but adding extraction constraints. The success and refusal return structures further clarify the tool's purpose.

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

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

The description gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on' and provides a concrete alternative: 'prefer ask_pipeworx for casual lookups.' It also names the sibling it routes identically to, so an agent can choose between grounded and non-grounded variants without ambiguity.

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

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

The description extensively discloses behaviors beyond annotations: low-confidence short-circuit, closed market handling, wide-spread warnings, cancellation rules, and response shapes. Annotations already indicate readOnly and idempotent, and the description adds safety and edge-case context.

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

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

The description is comprehensive but verbose, spanning multiple paragraphs. It is well-structured with clear headings, but length may hinder quick scanning. Some sentences are dense, impacting conciseness.

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

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

Given no output schema, the description fully explains return values (result.market, result.analysis, etc.), safety conditions, cancellation rules, and news fields. It covers complex edge cases comprehensively, making the tool's behavior transparent.

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 detailed parameter descriptions. The description adds usage examples and context like classifiers and fan-out examples, but these are not parameter-specific extras. Baseline 3 is appropriate as the schema already carries the meaning.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data. It specifies the input (slug, URL, or question text) and distinguishes from sibling tools like polymarket_edges and polymarket_arbitrage by focusing on a single bet 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?

The description gives explicit use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and covers various scenarios (low confidence, closed markets, wide spreads). It does not explicitly list when NOT to use, but the guidance is detailed and practical.

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 confirm read-only, open-world, idempotent, non-destructive behavior. The description adds valuable context: for companies, it pulls latest 10-K data with proper fiscal year handling; for drugs, it pulls FAERS data. It also discloses sorting by primary metric. No contradiction.

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

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

The description is front-loaded with key trigger phrases and usage instructions. Each sentence adds value, though the list of example phrases could be slightly trimmed. Still efficient for its length.

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

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

Given the simple input schema (2 params, no output schema), the description sufficiently covers return format (paired data, citation URIs) and behavioral details (fiscal year handling, sorting). No gaps for this tool's complexity.

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

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

Schema coverage is 100%. The description elaborates on parameters: type enum explained with examples, values array with specific formatting (tickers for company, names for drug) and constraints (2-5 items). 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 clearly states the tool performs side-by-side comparison of 2-5 companies or drugs, providing specific trigger phrases ('compare X and Y', 'which is bigger', etc.). It distinguishes from sibling tools like entity_profile by emphasizing multiple entities in one call.

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 recommends preferring this tool over sequential single-entity lookups when comparing entities. It also explains when to use company vs drug type, giving clear usage context.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral context beyond that: account requirements and paid tier limitations, the multi-hopped depth behavior, the structure of the findings packet (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), the gaps[] and contradictions[] fields, semantic excerpting behavior, and expected latency. There is no contradiction with the annotations; the description thoroughly discloses what happens when the tool runs.

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

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

The description is long and dense, but nearly every sentence earns its place given the tool's complexity: account requirements, alternatives, decomposition behavior, citation semantics, gaps/contradictions, and timing are all relevant operational details. It loses a point because it is a continuous wall of text without any structural segmentation (bullets or paragraph breaks), and some details like '5,743 tools' are colorful but not essential. Still, it is far from bloated or tautological.

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 present, the description carries the full burden of explaining the return value, and it does: 'findings packet: verbatim evidence + confidence + source + fetched_at + a stable pipeworx:// citation... explicit gaps[]', plus contradictions[], hop field, and fetchable citation_uri. It also covers latency, account prerequisites, and the difference from ask_pipeworx. An agent has enough information to invoke the tool and interpret its result without other documentation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful value beyond the schema by explaining depth options in behavioral terms ('quick=3 single hop', 'standard=3... adds a gap-recovery hop', 'thorough=6... chases leads'), giving example questions, and clarifying that the question parameter can be 'broad/multi-part'. This is above baseline but not necessary to the max because the schema already documents the enum values and question semantics 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 states a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1500 STRUCTURED data sources' in one call, and explicitly distinguishes itself from 'open-web search' and from siblings like ask_pipeworx. It clearly identifies the tool's behavior: decomposing questions, routing to 5,743 tools, and returning a findings packet. This is more than sufficient for an agent to understand what the tool does and how it differs from nearby tools.

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

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

The description gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data', and gives direct alternatives with conditions: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', and 'If you are not signed in, use ask_pipeworx instead'. It even explains why deep_research may return empty gaps for non-catalog topics, which is valuable for 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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: the tool returns top-N relevant tools with full schemas and examples, and each result is ready to call directly without a second lookup. This goes beyond annotations but does not disclose all edge cases.

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 at about four sentences, front-loaded with the core action, and every sentence contributes meaningful 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?

The description fully explains the purpose, usage context, return value (tools with schemas and examples), and when to invoke it. Despite no output schema, the description adequately covers what the agent can expect.

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

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

Schema coverage is 100%, so the schema already describes all parameters. The description adds value by listing example domains (e.g., 'SEC filings, financials, FDA drugs') and clarifying that aliases like q, task, search, description are accepted, which reinforces the schema's parameter descriptions.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It provides specific examples of domains and explicitly distinguishes itself from siblings by being a discovery tool to be called first.

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 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It also describes when to use it (browse, search, look up, discover) and lists alternative scenarios implicitly.

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

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

Annotations already mark the tool read-only, idempotent, and non-destructive, and the description adds substantial behavioral context far beyond that: it enumerates the fanned-out sources, return sections, soft-failure behavior for USPTO patents, expected-empty semantics for FDA products, sources_used/sources_failed meaning, name resolution via SEC EDGAR, and private-company handling with resolved:false. Nothing in the description contradicts the annotations.

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

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

The description is dense and long, but the complexity of the tool justifies most of the length. It is front-loaded with the core purpose and usage directive, and nearly every sentence carries useful caveats or behavioral details. Some redundancy exists with the schema (e.g., type/value shapes are repeated), and bullet structuring could improve scannability, but it remains efficiently packed.

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

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

Despite having no output schema, the description provides an exceptionally complete picture: input shapes, source fan-out, return field names, URI examples, soft-fail conditions, expected-empty sections, failure semantics, and private-company behavior are all covered. An agent has enough context to select and invoke this tool correctly and to interpret its outputs.

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, but the description adds meaningful semantics beyond the schema: it clarifies that type values are interchangeable, that value can be a ticker, zero-padded CIK, or company name, explains name resolution behavior, and notes person/place support is coming soon. This goes beyond the schema's own property 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 a specific verb and resource: it builds a full cross-source profile of a US public company in one parallel call, illustrated with concrete user phrasings. It distinguishes itself from the general practice of chaining single-pack lookups, though it does not name any sibling tool explicitly, so it stops short of full sibling differentiation.

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

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

The description gives explicit guidance: ALWAYS PREFER this tool over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view. It also explains what inputs are acceptable and what happens for private companies. It does not explicitly state when not to use it or name alternatives such as compare_entities or resolve_entity, so the exclusion criteria are only implicit.

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 behavior (destructiveHint=true). The description adds practical context (clearing stale/done/sensitive data) without contradicting annotations. No additional behavioral traits are needed.

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 what the tool does, second gives usage guidance. No fluff, front-loaded, every sentence adds value.

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

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

For a simple tool with one fully-documented parameter and annotations covering destructiveness and idempotency, the description adequately covers purpose, usage, and behavioral context. No gaps remain.

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

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

Schema coverage is 100% and the schema already documents the 'key' parameter as a string. The description does not add extra semantics beyond mentioning deletion 'by key', which is inherent.

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

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

The description clearly states the action ('Delete'), the resource ('previously stored memory'), and the mechanism ('by key'). It distinguishes from sibling tools 'remember' and 'recall' by mentioning pairing.

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: when context is stale, task is done, or clearing sensitive data. Also advises pairing with remember and recall, giving context for when to use this tool versus alternatives.

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

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

The description explains that it fetches the page, extracts title/description/key links, and outputs markdown. This adds context beyond the annotations (readOnlyHint, idempotentHint, destructiveHint). No contradiction with annotations.

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

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

The description is two sentences, front-loaded with the main action, and provides essential context without fluff. 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?

Given no output schema, the description explains the output (single text blob). It covers the key parameters and use cases. An example output format would improve completeness but not strictly necessary.

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

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

Schema description coverage is 100% with clear descriptions for both parameters. The description adds context by explaining the output format and that 'url' determines the site to summarize. It clarifies that 'max_links' controls the number of link entries.

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: generating a production-ready llms.txt file for any URL. It uses specific verbs ('generate', 'fetches', 'extracts', 'emits') and identifies the resource (llms.txt). The tool is distinct from all siblings listed.

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

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

The description explicitly lists use cases: getting a client's site indexed, drafting for own project, auditing competitor AI visibility. It does not explicitly state when not to use or alternative tools, but the listed use cases are 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by stating the default behavior (returns active subscriptions only, with an optional parameter to include inactive) and listing the specific returned fields, providing context beyond annotations.

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

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

The description is two sentences, front-loaded with the purpose, and every sentence adds value. There is no wasted text.

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 only one optional parameter and rich annotations, the description covers the essential behavioral details: default active filtering, parameter usage, and return fields. It is complete for a simple list tool, though pagination or sorting details are not mentioned.

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

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

Schema coverage is 100% (one parameter with a clear description). The tool description does not add significantly new information about the parameter beyond what the schema provides, so it meets the baseline of 3.

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

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

The description clearly states the verb 'List' and resource 'the caller's active subscriptions', immediately establishing the tool's function. It also lists the return fields (id, type, params, created_at, etc.), which distinguishes it from sibling tools like 'subscribe' and 'unsubscribe'.

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

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

The description explicitly provides usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This gives clear when-to-use guidance, though it does not explicitly mention alternatives or when not to use.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds context about discovery and return values but does not contradict annotations. It adds minimal behavioral detail 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 concise, front-loaded sentences with no fluff. Each sentence adds necessary information.

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

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

For a simple discovery tool with one optional parameter, the description covers purpose, usage, return value, and how to use output. No 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 a descriptive parameter definition. The description repeats the parameter info and adds an example, providing marginal additional value.

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

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

The description clearly states the tool lists layers of a Nashville ArcGIS service for discovery, specifies the return value (layer id + name), and mentions integration with nashville_query. It distinguishes from sibling tools like nashville_query.

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 omit the service parameter (to list known services), provides examples, and clarifies the output usage. However, it does not explicitly contrast with siblings or state when not to use.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, establishing safety. The description adds value by noting that epoch dates are converted to ISO and implies full ArcGIS query capabilities. No contradictions with annotations.

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

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

Three tightly composed sentences: the first immediately defines the action and resource, the second lists parameters, and the third gives usage guidance. No extraneous words, every sentence earns its place.

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

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

Given 6 parameters, 2 required, no output schema, the description covers query syntax, service/layer identification, and date conversion. It could mention response format or limit defaults, but the schema covers limits and defaults, so overall adequate.

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

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

Schema description coverage is 100%, so baseline is 3. Description adds extra context: service can be a short name (crime|service_requests|permits) and epochs are handled. This provides meaning beyond the schema's documentation.

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

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

Description clearly states 'Query any Nashville ArcGIS layer by service path + layer id' and enumerates the query parameters. It distinguishes from sibling tools by referencing nashville_layers and nashville_recent as helpers. Purpose is specific and non-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?

Explicitly tells the agent when to use the tool and how to find layers using nashville_layers or nashville_recent. Does not provide explicit when-not-to-use, but the context is clear: this tool queries specific layers after identification.

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, openWorld, idempotent, non-destructive. The description adds useful behavioral details: 'Returns the latest rows (newest-first), epoch dates converted to ISO.' No contradictions.

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

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

Three sentences, front-loaded with key information: purpose, when to use, return format and filtering. No unnecessary words; every sentence adds value.

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

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

For a simple tool with 3 parameters and clear annotations, the description covers purpose, usage guidance, return format (newest-first, epoch date conversion), and relationship to siblings. No gaps given the complexity.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds minimal extra meaning beyond the schema (e.g., 'friendly name' for dataset). 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 the tool's purpose: 'Recent records from a common Nashville open dataset' and specifies the datasets (crime, 311) and behavior (latest rows, newest-first, epoch date conversion). It also distinguishes from siblings by directing users to nashville_layers and nashville_query for other layers.

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 prefer this tool over alternatives: 'PREFER OVER WEB SEARCH for "recent crime in Nashville", "Nashville 311 service requests".' Also explains filtering with 'Add an ArcGIS `where` to filter' and directs to siblings for other layers.

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

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

Beyond the sparse annotations, the description discloses key behaviors: filing without an account returns a claim_token, that token can be reused to read status, there is a rate limit of 5 per identifier per day, and it is free/non-quota. This is rich, actionable context that annotations alone do not provide.

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

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

The description is front-loaded with the core purpose and is dense with useful information, but it is slightly long. A few phrases like 'signal directly affects roadmap' are motivational rather than strictly operational, keeping it from a perfect score.

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 feedback-submission tool with no output schema, the description adequately covers behavior: what to file, when/where to file, how to follow up via claim_token, rate limits, and scope boundaries. No critical operational gap remains.

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 descriptive parameter docs, so the baseline is 3. The description adds extra value by explaining the claim_token round-trip workflow and giving content guidance ('describe the issue in terms of Pipeworx tools/packs'), which 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 opens with a specific action: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly enumerates feedback types (bug, feature/data_gap, praise) and scopes to Pipeworx tools vs other MCP servers, clearly distinguishing itself 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 use cases ('Use when a tool returns wrong/stale data...', etc.) and explicit when-not/alternative guidance ('if the tool came from a different MCP server... file it with that server instead'). It also gives practical content rules such as 'don't paste the end-user's prompt.'

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 provide readOnly, openWorld, idempotent, non-destructive hints. Description adds cache duration (5min-1h), data source (CF analytics-engine), no PII, and self-aggregating nature. No contradictions; adds significant context beyond annotations.

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

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

Single paragraph, front-loaded with action and output, then concise use cases, then technical details. Every sentence 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?

No output schema, but description explains return items (top tools, packs, call volume). Missing explicit format or structure, but for a trending tool with simple output and rich annotations, it is adequate. Could mention whether results are sorted or limited.

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 100% with one enum parameter documented. Description adds semantic guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This provides extra context beyond the basic 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?

Clearly states it returns top tools, packs, and call volume over recent windows (24h, 7d, 30d). Lists three specific use cases, distinguishing it from sibling tools like discover_tools by focusing on trending usage by AI agents.

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

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

Explicitly provides three use cases (discovering hot data sources, confirming canonical tools, checking use case alignment). Does not explicitly state when not to use, but context is clear; no direct alternative mentioned but sibling list provides options.

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

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

Adds significant detail beyond annotations: explains monotonicity and partition-check logic, Jaccard similarity anchor, placeholder filtering, fill check with book depth, and response structure. No contradictions with annotations (readOnlyHint, idempotentHint, destructiveHint).

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

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

Well-structured, front-loaded with purpose, clear mode separation. Slightly verbose with technical details, but each sentence adds value. Could be more concise without losing information.

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

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

Despite no output schema, the description thoroughly covers inputs, processing, and response structure (opportunities, partition_check, fill_check). References sibling tool for further steps. Complete for a complex tool.

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

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

Schema coverage is 100%, but the description adds rich context: explains the difference between event and topic modes, provides examples, and details algorithmic constraints (similarity threshold, placeholder filter). 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 clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes the three modes (trending scan, event-specific, cross-event topic) and differentiates from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicit guidance on when to use each parameter (no args, event, topic) with examples. Mentions that for custom sizing, use polymarket_fill_risk. However, lacks direct comparison to similar sibling tools like polymarket_edges for cross-use context.

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

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

Annotations already declare read-only, open-world, idempotent, non-destructive behavior. The description goes far beyond by explaining the three model families, response structure, caching, diagnostics, and edge cases like Fed bets. 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 detailed and well-structured with sections, but it is verbose with specific alpha values and internal details that may not be necessary for a tool description. Some pruning could make it more concise while retaining key info.

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, multiple segments, diagnostics), the description is thorough. It explains response top-level keys, knobs, and even caching behavior. No output schema, so the description fully covers return values.

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

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

All parameters have schema descriptions (100% coverage), so baseline is 3. The description adds extra nuance on parameter interactions (e.g., slippage_pp and edge, min_partition_leg_kelly purpose), enhancing 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?

Description clearly states the tool scans Polymarket markets for opportunities based on Pipeworx data, with a specific use case 'what should I bet on today'. It distinguishes from siblings like polymarket_arbitrage by focusing on discovery and ranking.

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

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

The description provides clear context on when to use (discovery for daily betting) and details on Fed bets exclusion. However, it does not explicitly state when not to use or list alternatives, but sibling tools imply different use cases.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral context: snapshot-based data, gaps meaning no scan, 60-day TTL, and decay computation from daily closes. No contradiction.

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

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

The description is fairly detailed but well-structured, front-loading purpose and response structure. Every sentence adds value, though slightly verbose in response details. Still well-organized.

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 output schema, the description compensates by fully detailing response fields (tracked, expired, snapshot_dates) and limitations. Provides complete context for an agent to understand 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% with clear parameter descriptions. The description repeats 'days' and 'window' defaults but adds minimal new semantic value beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly defines the tool's purpose: tracking edge persistence and decay over time. It answers a specific question ('how long has this edge existed and is it shrinking?') and distinguishes from siblings like polymarket_edges by focusing on historical snapshots.

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 on when to use the tool (e.g., differentiating fresh vs. old edges). However, it lacks explicit guidance on when not to use it or direct comparisons to alternatives, though siblings imply 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 already indicate this is a safe, read-only, idempotent operation. The description adds valuable context: it walks the order book ladder, returns verdicts (clean/degraded/cannot_fill), and warns about forced directional risk in basket mode. However, it doesn't mention any rate limits or cost implications.

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

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

The description is dense and uses uppercase headings for clarity, but it's a single continuous paragraph. It efficiently conveys a lot of information without wasted words, though breaking into bullet points or shorter sentences would improve readability. Still, it earns its space.

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

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

Despite lacking an output schema, the description fully documents return fields for both modes (top_of_book, vwap_fill_price, theoretical_sum, per-leg details, thin_legs, forced_directional_risk, etc.). It also covers required conditions, defaults, and risks (partial fills converting arb to directional position). Very comprehensive for a complex tool with 4 parameters.

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

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

Schema coverage is 100% but the description adds significant meaning: explains mutual exclusivity of `market` and `event`, describes default side logic in basket mode, clarifies interpretation of `size_usd` for single-market vs basket (spend vs target proceeds vs settlement notional), and mentions value clamping. This goes well beyond the schema descriptions.

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

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

The description clearly states it performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth'. It also distinguishes between single-market and basket modes and explicitly mentions it should be used before polymarket_arbitrage or polymarket_edges tools, setting it apart 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 states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains why (theoretical overround not capturable, partial fills lead to directional risk), providing clear decision context.

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

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

Annotations already establish readOnly/idempotent/non-destructive behavior, and the description goes well beyond them by detailing compatibility warning codes, fee treatment (Kalshi fees not modeled, gross spreads), skipped comparison counters, and the rule that legs with 'unknown' metric_type/match_subtype are never paired. This gives an agent the behavioral context needed to interpret warnings and returned data correctly.

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

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

The description is long and dense, but the tool is complex and the length is mostly earned by critical caveats around safety fields, temporal alignment, and fee disclosures. It is front-loaded with the core purpose and modes, and uses clear structural labels like 'TWO MODES', 'RESPONSE', and 'SAFETY FIELDS'. There is some repetition around 'EITHER mode' and the final 'pre-mapped ≠ tradeable' reminder, so it is not maximally 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 that there is no output schema, the description is remarkably complete: it documents the response shape, how spreads are computed, when compatibility warnings appear, what each compatibility code means, temporal alignment semantics including null handling, fee limitations, and skipped comparison types. An agent has enough context to call the tool and interpret its results without guessing.

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

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

The input schema covers all three parameters, so the baseline is 3, but the description adds substantial semantic value: it explains what `topic` shortcuts auto-fetch, that `kalshi_event_ticker` and `polymarket_event_slug` override the topic-mapped side, and that both modes execute the identical token-overlap matcher. This is meaningfully beyond the schema's descriptions.

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

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

The description opens with a clear resource and purpose: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' and further clarifies two modes and pre-mapped shortcuts. It distinguishes itself from siblings mostly through the 'cross-venue' framing, but it never explicitly names or contrasts sibling tools like polymarket_arbitrage, so a perfect score isn't warranted.

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

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

The description gives explicit within-tool guidance: use `topic` for pre-mapped shortcuts, use explicit `kalshi_event_ticker` + `polymarket_event_slug` for custom pairings, and says both modes run identical matching logic. It also gives strong when-not guidance such as 'pre-mapped ≠ tradeable' and tells agents to verify close/strike dates manually when temporal alignment is unknown. It does not compare against sibling tools by name, so the 'alternatives' aspect is only partially covered.

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/not destructive hints. The description adds context about scoping (anonymous IP, BYO key hash, or account ID) and pairing with remember/forget.

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

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

Two sentences, front-loaded with primary action, no wasted words. Every sentence adds distinct 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?

Tool is simple with one optional parameter. Description covers purpose, usage, scoping, and pairing. Missing return format details, but not critical for a retrieval tool.

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

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

Schema coverage is 100%, but the description adds value by explaining the listing behavior when key is omitted. The parameter purpose is clear.

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 retrieves a value saved via 'remember' or lists all keys if no argument is given. Distinguishes from sibling tools 'remember' and 'forget'.

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

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

Describes when to use: to look up context stored earlier without re-deriving. Mentions listing all keys by omitting the key argument. No explicit when-not or alternatives, but context is clear.

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

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

Annotations already indicate read-only, non-destructive, idempotent. The description adds behavioral details: mark_read flags events as read affecting future calls, polling is fine, and the data is also available via HTTP. No contradictions.

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

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

Three sentences, front-loaded with purpose, each sentence adds essential information without redundancy. Highly 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?

Covers purpose, return structure, filtering, mark_read side effect, and alternative access. Lacks explicit mention of ordering (most recent) and return type (list), but sufficient for correct usage given no output schema.

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

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

Schema covers all 5 parameters with descriptions (100% coverage). The description adds value by giving a concrete filter example (type 'sec_8k') and explaining the effect of mark_read, though limit and unread_only are not elaborated.

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 pulls fired events from a subscription feed, specifies return fields (source, citation_uri, payload), and is distinct from siblings like list_subscriptions or recent_changes.

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

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

It provides usage context with filtering by type and since, explains mark_read behavior, and mentions an HTTP alternative for scripting/dashboards. However, it does not explicitly compare to siblings or state when not to use.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint. Description adds significant behavioral context: fan-out architecture, GDELT→GNews fallback, USPTO soft-fail until May 2025, and grouped return 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 dense paragraph front-loaded with example queries, then systematically describes fan-out, parameter semantics, return structure, and alternative tool. Every sentence contributes meaningful information with no fluff.

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

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

For a tool with 3 required params, no output schema, and no nested objects, the description covers all important aspects: parameter format, fallback behavior, return structure, sibling differentiation. Missing details like error handling are minor given the complexity.

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

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

Schema coverage is 100% with descriptions for all 3 parameters. Description reinforces meaning of 'since' with examples ('2026-04-01', '7d', '30d') and suggests typical usage ('30d' for monitoring). Adds value beyond schema by clarifying 'value' accepts ticker or CIK.

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

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

The description clearly states the tool returns a change feed for a company in a time window, fanning out to SEC EDGAR, GDELT→GNews, and USPTO. It also explicitly distinguishes from the sibling 'entity_profile' tool by contrasting dynamic change feed vs static profile.

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

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

Provides explicit example queries ('What's new with X', 'latest on Y'), explains when to use the alternative (entity_profile for static profile), and describes fallback behavior between GDELT and GNews. Covers both 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 indicate idempotentHint=true and destructiveHint=false. The description adds context about persistence (authenticated vs anonymous) and scoping by identifier, which is not in annotations. However, it doesn't detail overwrite behavior or storage limits.

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

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

The description is concise with 4 sentences, efficiently front-loading purpose and usage. 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 the tool's simplicity (key-value store, no output schema), the description covers purpose, usage, behavioral details, and pairing with siblings. It feels complete for agent decision-making.

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

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

Schema coverage is 100% with parameter descriptions already clear. The description adds examples of key naming conventions and reiterates that value is any text, but does not provide significant new semantic information beyond the schema.

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

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

The description clearly states that the tool saves data for later reuse, specifying verb 'Save' and resource 'data'. It distinguishes from sibling tools like recall and forget by mentioning them explicitly.

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

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

The description provides explicit guidance on when to use (discover something worth carrying forward) and alternative tools (recall, forget). It gives concrete examples such as resolved ticker, target address, user preference.

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

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

With annotations already establishing readOnlyHint=true, idempotentHint=true, and destructiveHint=false, the description adds substantial behavioral context: cascading internal lookups, graceful degradation when GLEIF/OpenFIGI are unavailable, explicit `unresolved` fields, source-labelled identifiers, and multi-match behavior returning figi_candidates. This goes well beyond what the 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 long but front-loaded with human-language triggers and a clear 'Use FIRST' directive. While dense and information-rich, some redundancy exists around supported identifiers and fallback behavior, so it is not maximally concise. Still, each section earns its place given the tool's complexity.

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

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

For a tool with no output schema, the description explains return-level behavior sufficiently: RxCUI plus ingredient and brand with citation for drugs, figi_candidates for ambiguous securities, source-labelled identifiers, and explicit unresolved fields. Combined with complete parameter documentation and annotations, an agent can correctly invoke this tool and interpret 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?

Even though schema description coverage is 100%, the description adds critical semantic guidance: pass the entity name only, never the full noun phrase, use issuer name exactly as printed for bonds, and accept ticker, CIK, ISIN, or company name. The value parameter's ambiguity is resolved with concrete examples and failure-mode explanations that the schema alone would not convey.

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

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

The description states a clear, specific purpose: resolve a user-spoken NAME to canonical/official identifiers that other tools require as input. It distinguishes itself by explicitly saying 'Use FIRST whenever you have a name but need an ID' and enumerates supported entity types with concrete identifier examples, making it easy to tell apart from siblings like entity_profile or compare_entities.

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

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

The description explicitly says to use this tool first whenever a name is present but an ID is needed, which is strong contextual guidance. It also details how to handle ambiguous matches via figi_candidates and which inputs are accepted. However, it does not directly contrast itself with sibling tools like entity_profile or validate_claim, so the when-not-to-use guidance is not fully explicit.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as true/true/true/false, indicating a safe, read-only, idempotent operation. The description adds valuable context: it explains the tool probes each entity using ai_visibility_check and returns a ranked list with score, confidence, and signal density. 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 long, with the first sentence stating the core action and output, and the second providing usage context and output details. It is efficient and front-loaded, though the second sentence is slightly verbose. 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?

Given 4 parameters, 100% schema coverage, no output schema, the description explains the output structure (ranked list with score, confidence, signal density) and the composition (uses ai_visibility_check). It does not elaborate on score ranges or the meaning of 'signal density', but the description is fairly complete for a composite tool.

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

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

Schema description coverage is 100%, but the description adds meaning beyond the schema: it explains that the first entity is treated as the 'subject' for narrative, that models default to workers-ai, and that _apiKey is only needed for Anthropic. This helps an agent understand parameter roles and defaults.

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 compares AI visibility across multiple entities side-by-side, specifying the verb 'compare', the resource 'AI visibility', and the scope (multiple entities). It distinguishes itself from sibling tools like ai_visibility_check (single entity) and compare_entities (general comparison) by focusing on AI visibility. The output (ranked list with score, confidence, signal density) is also mentioned.

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

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

The description provides a concrete use case ('competitive AI-marketing audits') and gives an example question ('does Claude know about us as well as our competitors?'). It implies the tool is for multi-entity comparison, suggesting single-entity checks should use ai_visibility_check. However, it does not explicitly state when not to use this tool or list alternative siblings.

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

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

Beyond readOnlyHint, idempotentHint, and openWorldHint annotations, the description discloses that the tool fans out across two services, returns specific fields, has partial failure with 'sources_failed', and notes bundlephobia's first measurement can take 5-30s. This adds valuable behavioral context.

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

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

The description is packed with information in a single paragraph, but it is not overly verbose. It front-loads the main purpose and covers usage, returns, and edge cases efficiently. Minor structure improvement could break into sentences, but overall concise.

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

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

No output schema is provided, yet the description thoroughly explains what is returned: a summary block with specific fields, per-advisory detail, links, alternative versions, and partial failure behavior. For a tool with only 2 parameters, 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 coverage is 100% with both parameters already described adequately. The description does not add significant new meaning beyond stating that package accepts scoped names and version defaults to latest. Baseline 3 is appropriate as schema does the heavy lifting.

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

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

The description clearly states it is a composite check for deciding whether to add an npm package, combining data from deps.dev and bundlephobia. It distinguishes from sibling tools by its specific focus on npm packages and the one-call composite nature.

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

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

Explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me". It also mentions ecosystem limitations (NPM only, others under deps.dev:version directly) and partial failure behavior, 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?

Annotations already declare safety profile (readOnly, idempotent). Description adds specific behavioral traits: BGE-base-en embeddings, 500-char windows, cosine similarity, 200K char cap with truncation flagged, and offsets for verification.

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 (~100 words), front-loaded with purpose, then details. Every sentence provides useful information without redundancy.

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

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

Despite no output schema, description mentions return fields (passages, offsets, scores). Explains truncation behavior and references sibling tool. Complete for a search tool with this complexity.

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

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

Schema has 100% coverage with descriptions. Description adds value by clarifying max chars for 'text', giving example queries for 'query', and specifying default and range for 'limit'.

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 ('Semantic search inside'), the resource ('a fetched record'), and provides concrete examples (SEC 10-K body, article). It also distinguishes from siblings by pairing with ask_pipeworx_grounded.

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 recommends use when 'the record is too big to cram into the prompt' and describes pairing with another tool. Lacks explicit when-not-to-use but gives clear context.

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

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

The description discloses behavioral traits beyond annotations: it mentions the OAuth requirement, delivery channel constraints (SMS 10/day cap, webhook auto-disable after 10 failures, signing secret one-time return). However, idempotency is not fully addressed (idempotentHint true may be misleading).

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, stating the purpose and requirements first. It covers all necessary information without excessive redundancy, though the delivery section repeats some info from the schema. Could be slightly more concise.

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

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

Given the tool's complexity (3 params, nested objects, multiple types), the description is remarkably complete: covers OAuth requirement, type-specific configurations, delivery channels, limits, and return value. Lacks error cases or idempotency clarification, but overall adequate.

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?

Despite 100% schema coverage, the description adds substantial value: explains type-specific params with examples, delivery channel options with constraints, webhook signing details, and validation requirements. It goes far beyond the schema's minimal 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 action ('Create a proactive monitoring subscription'), specific resource ('live-data event stream'), and return value ('Returns the new subscription id'). It distinguishes from sibling tools like 'unsubscribe' and 'list_subscriptions' by focusing on creation.

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

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

The description provides clear usage context: requires a Pipeworx OAuth account, lists supported types and delivery channels. It implicitly differentiates from other tools like 'recent_alerts' and 'unsubscribe' but does not explicitly state when not to use this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds essential context about the output: it 'Returns category-bucketed example questions (company financials, drugs & clinical trials, ...) each with the exact tool + argument shape.' This goes beyond annotations and fully discloses behavior.

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

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

The description is one long sentence with a parenthetical list, which is somewhat dense but efficient. It front-loads the core purpose and includes all necessary details without redundancy. Could be broken into a clearer list, but scores well for informativeness.

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 only one optional parameter and no output schema, the description thoroughly explains what it returns (category-bucketed example questions with tool+argument shapes), when to use it (first for onboarding), and how to narrow by topic. It is fully complete for its complexity level.

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

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

Schema coverage is 100% with a description for the single parameter `topic`. The description adds value by providing concrete examples ('e.g. "finance", "pharma", "betting"') and clarifying that omitting it gives a cross-category spread. This extra semantic 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 clearly states the tool's purpose as an onboarding entry point that returns categorized example questions with exact tool and argument shapes. It distinguishes itself from sibling tools by being the 'FIRST' tool to use when unfamiliar with Pipeworx.

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

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

The description explicitly says to use this tool 'FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains that you can narrow by topic using the `topic` parameter. This provides clear and actionable guidance.

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

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

The description adds significant behavioral details beyond annotations: ownership enforcement, row deactivation (not deletion), and that historical events remain available via recent_alerts. This complements the annotations well.

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 concise sentences, each serving a distinct purpose: action/ownership and side effects. 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?

For a simple tool with one required parameter and no output schema, the description fully covers purpose, constraints, and side effects, including how it integrates with recent_alerts.

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

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

Schema coverage is 100% with a clear description of the 'id' parameter. The description does not add extra parameter semantics, but the schema already provides sufficient meaning, meeting the baseline.

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

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

The description clearly states the action ('Cancel a subscription by id') and specifies the resource ('subscription'). It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by specifying the operation type.

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

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

The description provides clear context by stating ownership enforcement and that only own subscriptions can be cancelled. It does not explicitly state when not to use or alternative tools, but the context is sufficient for most cases.

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

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

Annotations already convey read-only/idempotent, but the description adds critical behavioral nuance: distinguishes could_not_verify from unsupported, explains verification_error payload, and explicitly warns not to treat could_not_verify as evidence. It also notes that the tool consolidates 4–6 sequential calls, giving valuable operational insight.

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

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

The description is long but front-loaded with trigger phrases and functional purpose. Each sentence contributes necessary context such as return verdicts, error handling, and routing logic. No filler, though it is denser than strictly necessary.

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?

Considering there is no output schema, the description compensates by enumerating all possible verdicts, explaining edge cases (could_not_verify vs unsupported), and describing the grounded vs structured paths. It covers the full lifecycle of the tool with no significant 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, providing baseline 3. The description goes beyond by clarifying tolerance_pct behavior (implied by wording, capped at 5) and recommending 1–2 for hallucination detection, which adds decision-relevant semantics not present in the schema.

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

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

The description explicitly defines the tool as 'natural-language claim verification against authoritative sources' and opens with concrete trigger phrases. It clearly distinguishes this from siblings by focusing on verdict-based validation of factual claims, unlike broader QA or research 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 states 'Use whenever the agent needs to check whether something a user said is factually correct' and even explains internal routing for financial vs. other claims. It does not explicitly name sibling tools to exclude, but the usage context is clear and actionable.

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