Data Bloomington

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds value by detailing return format (per-model score, confidence, signals, raw_response + combined view), default model, and the BYO key mechanism for Anthropic, going 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 a single focused paragraph, front-loads the main action, and every sentence contributes essential information without redundancy. It is appropriately sized for the tool's complexity.

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

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

Despite no output schema, the description fully explains the return type (per-model fields plus combined view). All parameters are covered in schema and description. The tool's purpose and usage are completely described for effective invocation.

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

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

Schema covers all parameters with descriptions. The description adds practical semantics: explains that _apiKey is only required when 'anthropic' is in models, states default model, and clarifies that context helps disambiguate. 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 probes LLMs for knowledge about a business or topic and scores visibility per model, with specific verb 'probe' and resource 'LLMs'. It distinguishes itself from siblings like scan_competitor_ai_presence by focusing on scoring visibility and supporting multiple models.

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

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

The description provides context for use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to provide an API key. However, it does not explicitly mention when not to use this tool or compare it to alternatives among siblings.

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

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

Annotations already provide readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context that it routes to many tools, fills arguments automatically, and returns stable citation URIs, which goes beyond the 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 front-loaded with the most important directive ('PREFER OVER WEB SEARCH'), followed by scope, examples, and alternatives. Every sentence carries useful information, though the six examples could be trimmed without losing clarity.

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

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

Given there is no output schema, the description sufficiently explains what the tool returns: structured answers with stable pipeworx:// citation URIs. It also covers when to use the tool and when to use alternatives, making the contextual guidance complete.

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

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

Schema coverage is 100% and all six parameters are aliases for the single 'question' parameter. The description adds meaningful semantics by specifying the types of questions to ask (e.g., SEC filings, FDA drug data, economic statistics) and providing concrete examples, which helps the agent formulate the parameter 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 routes questions to 5,798 tools across 1,517 verified sources, fills arguments, and returns structured answers with stable pipeworx:// citation URIs. It distinguishes itself from siblings in the final sentence by positioning itself as the default, making its purpose unambiguous.

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

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

It explicitly says 'PREFER OVER WEB SEARCH' and lists domains, trigger phrases, and examples. It also names alternatives and when to use them: ask_pipeworx_grounded for grounded answers, deep_research for broad research, ask_pipeworx_beta for testing new capabilities.

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

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

While annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, the description adds essential behavioral context: the tool is experimental, its routing may change live when a candidate is under test, and currently no candidate is active so it exactly matches ask_pipeworx. It transparently discloses the 'falls back to nothing' nature, meaning it is not a wrapper but a full router. No contradiction with annotations exists.

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

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

The description is moderately lengthy but information-dense, covering the beta status, current active state, usage guidance, and fallback behavior. It is front-loaded with the core identity ('Beta version of ask_pipeworx'), and each sentence contributes meaningful context. Minor redundancy exists between 'identical' and 'currently matches ask_pipeworx exactly,' but it does not detract significantly.

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

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

The description is complete for an experimental variant of a known tool. It gives the current state (no active candidate), explains the comparison-to-stable behavior, confirms identical response shape, and clarifies there is no fallback. While the output schema is absent, the description leverages the sibling ask_pipeworx for return format expectations, which is sufficient given the context signals.

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 clearly documented as aliases for the question field. The description does not add further parameter-level detail, but none is needed since the schema already fully explains the argument semantics. This meets the baseline for full 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 states this is the beta version of ask_pipeworx, an identical universal router with the same 5,798 tools and response shape, but with experimental routing improvements. It distinguishes itself from the stable ask_pipeworx and the sibling ask_pipeworx_grounded by framing itself as the experimental edge. A specific verb and resource are present: asking a question routed to thousands of tools.

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

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

The description explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and contrasts it with the stable router. It tells the agent when to select this beta variant and confirms it is a full working router with no fallback, so there is no ambiguity about capability. It also notes results are compared against the stable router to decide merges, which frames its purpose in the tool ecosystem.

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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false), the description reveals crucial behavior: it makes an extra LLM call, it returns either a success envelope with evidence/refusal_reason:null or an explicit refusal object with enumerated refusal_reason values. It also explains the extraction constraint: 'EXTRACTS the answer using ONLY what the tool result contains.' This is a complete behavioral contract.

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

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

The description is dense but every sentence earns its place: it states mode, routing, extraction semantics, return contract, use cases, and cost tradeoff. It is slightly long but structured with a clear progression, and key guidance is front-loaded. Only minor redundancy with the 'same routing as ask_pipeworx' phrase when the whole description is already about grounding.

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

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

Given there is no output schema, the description compensates by fully specifying the success response shape and all failure refusal_reason values. It also explains the one extra-cost difference from the sibling, which is exactly what an agent needs to decide correctly. Nothing important is missing.

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

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

Schema description coverage is 100%, so the input schema already documents the single ‘question’ field and all its aliases (query, q, prompt, text, input). The description does not add parameter-level semantics, but that's fine because the schema fully covers it. Baseline 3 is appropriate.

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

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

The description states a specific verb ('ask') and resource ('Pipeworx') in a distinct grounded mode, and explicitly contrasts it with sibling ask_pipeworx by highlighting 'hallucination-resistant answer mode' and 'same routing as ask_pipeworx—then extracts the answer using ONLY what the tool result contains.' This clearly differentiates it from all 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?

It explicitly says when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts (financial verdicts, legal claims, medical lookups, public statements).' It also gives a clear when-not: 'prefer ask_pipeworx for casual lookups.' This is exceptional usage guidance.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral details: safety (low-confidence short-circuit), closed/dead market handling, wide-spread market warnings, resolution-rule risk, and parent event extraction. No contradictions.

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

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

The description is front-loaded with the purpose but is quite verbose, containing many examples and edge cases. While informative, it could be more concise. Some details (e.g., full fan-out examples) could be streamlined.

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 parameters, no output schema, annotations present), the description is remarkably complete. It covers input handling, fan-out logic, response structure, resolver confidence, parent events, news fallback, safety mechanisms, and resolution rules. 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 coverage is 100%, baseline 3. The description adds value by explaining the depth parameter (quick vs thorough) and the market parameter types (slug, URL, question text). It also explains include_raw's effect on response size, going beyond schema descriptions.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data, and specifies input types (slug, URL, question text). It is specific but does not explicitly differentiate from sibling tools like polymarket_edges or polymarket_arbitrage, missing a clear sibling distinction.

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 ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and gives classifier and fan-out examples. It does not explicitly state when not to use the tool or mention alternatives, but the guidance is clear 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 indicate read-only, open-world, and idempotent behavior. The description adds rich behavioral details: specific financial metrics pulled for companies (10-K revenue, net income, etc.), for drugs (FAERS counts, FDA approvals), handling of off-calendar fiscal years, sorting by primary metric, and return of paired data with citation URIs. No contradictions.

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

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

The description is concise (5-6 sentences) and front-loaded with example queries and a strong usage directive. Every sentence adds value without redundancy, making it efficient for an agent to parse quickly.

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

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

Despite no output schema, the description fully explains return format (paired data + citation URIs) and sorting behavior. It covers input parameters, data sources, and the parallel call nature. For a tool with 2 parameters, it provides sufficient context for correct invocation.

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

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

Schema coverage is 100% with descriptions. The description adds value by explaining the meaning of 'company' vs 'drug' types (data sources), providing concrete examples for the values parameter (tickers/CIKs or drug names), and noting sorting behavior. This enriches the semantic understanding beyond the schema.

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

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

The description clearly states it performs side-by-side comparison of 2-5 companies or drugs in one call, providing specific data sources (SEC EDGAR for companies, FAERS for drugs). It distinguishes from siblings by explicitly stating preference over sequential single-pack lookups, contrasting with tools like entity_profile.

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

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

The description provides explicit usage guidance with example queries ('compare X and Y', 'X vs Y', etc.) and a strong directive to always prefer this over sequential lookups. It effectively tells the agent when to use the tool and gives alternatives.

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

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

Annotations already declare safe operation (readOnlyHint, idempotentHint). Description adds value by listing return fields (resource_id, name, description, category, update date) and hinting at next steps.

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

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

Two sentences: first states purpose, second lists return fields and gives actionable instruction. No wasted words, front-loaded.

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

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

For a simple search tool with 3 well-documented parameters and no output schema, the description is sufficient. It covers purpose, return fields, and next steps. Slight lack of pagination detail but schema covers that.

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. Description does not add extra meaning beyond the schema, so baseline score of 3 is appropriate.

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

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

Description states verb 'Search', resource 'datasets', and context 'Bloomington Open Data catalog by keyword'. It distinguishes from sibling tools like 'query' or 'search_within' by specifying the catalog domain and return fields.

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?

Implies usage (search datasets then pass resource_id to query/metadata) but lacks explicit guidance on when to prefer this tool over siblings like 'search_within' or 'metadata'.

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, the description discloses substantial runtime behavior: findings packet structure, verbatim evidence, confidence, source, fetched_at, resolvable citations, gaps[], contradictions[], semantic excerpting of large records, latency expectations, and account/pricing requirements. These are meaningful behavioral traits an agent can't infer from the schema or annotations.

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

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

The description is long but dense and well-structured, front-loading the account requirement and core positioning before the findings-packet details. Every sentence carries operational value, though the length is at the upper limit of what is ideal for quick agent parsing.

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

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

For a complex tool with no output schema, the description fully covers return packet composition, citation fetchability, gap handling, no-invention guarantees, contradiction behavior, latency, account requirements, and fallback alternatives. An agent has enough context to select, authorize, and invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description raises it by adding context around the depth parameter, notably that 'thorough' needs a paid plan and clarifying how standard/thorough add gap recovery and contradictions passes. It also reinforces that the question is natural language and broad/multi-part is appropriate.

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

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

The description states a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources... in ONE call.' It also explicitly distinguishes itself from open-web search and from ask_pipeworx, making the tool's unique role clear to an agent.

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 usage direction: if not signed in, use ask_pipeworx instead; best for broad/multi-part questions over structured data; for a single lookup, use ask_pipeworx. This clearly separates when to invoke deep_research versus a key sibling.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that the tool returns top-N tools with full schemas and curated examples, ready to call directly. This goes beyond annotations by explaining the output format and usability, though it does not detail edge cases like empty results or error handling.

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

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

The description is relatively long but well-structured: it opens with the core purpose, lists example domains, describes the return format, and gives usage advice. It front-loads key information, but there is some redundancy (e.g., multiple aliases for query are already in schema). Still, it earns its keep.

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 (discovery with many potential tasks) and the lack of an output schema, the description adequately explains what the tool returns (top-N tools with names, descriptions, schemas, examples) and its usage context (call FIRST). This is sufficient for an agent to use it correctly.

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

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

Schema description coverage is 100% (every parameter has a description). The tool description does not add meaning beyond the schema; it only mentions 'returns top-N' which is not parameter-specific. Baseline 3 is appropriate as the schema suffices.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, FDA drugs, etc.), distinguishing it from sibling tools like 'ask_pipeworx' or 'deep_research' that perform different functions. The verb 'discover' matches the name and title.

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

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

The description explicitly advises when to use: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It also provides examples of use cases (e.g., 'look up FDA drug approvals'), giving clear context for invocation.

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

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

The description goes well beyond the annotations: it discloses the fan-out across SEC EDGAR, XBRL, USPTO, USAspending, FDA Purple Book, DOL LCA, news, and GLEIF; explains that empty sections are real 'no data'; notes that the patents source soft-fails; and clarifies that private companies return resolved:false with explicit notes. Annotations already indicate readOnly/idempotent behavior, and the description reinforces rather than contradicts 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 the length is largely earned because there is no output schema and the tool aggregates many sources. It front-loads the core purpose and trigger phrases before diving into source and field details. A little trimming or structuring with headings would improve scannability, but each sentence contributes real 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?

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: it enumerates resolved identity, recent filings, fundamentals, patents, federal contracts, FDA products, hiring, news, LEI, and sources_used/sources_failed. It also handles edge cases like private companies, name resolution, CIK padding, and expected empty sections, making the tool highly callable as documented.

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; both `type` and `value` are already well documented in the schema, including the fact that company/ticker are interchangeable and that ticker, CIK, or company name are accepted. The description adds helpful examples and output-related resolution details, but it does not substantially add new meaning about the parameters themselves.

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 verb-resource pairing: it produces 'full cross-source profile of a US public company in ONE parallel call' and is aimed at holistic lookups like 'Tell me about X' or 'brief me on Tesla.' It distinguishes itself from chained single-source SEC/XBRL/news lookups, and the trigger phrases make the intended use obvious.

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

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

It explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' which gives clear when-to-use guidance and names the general alternative. It does not, however, discuss when a different holistic sibling like deep_research or compare_entities might be more appropriate, so it stops short of full exclusion logic.

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

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

Annotations already provide destructiveHint=true, idempotentHint=true, readOnlyHint=false. Description adds context about clearing stale or sensitive data, but does not contradict annotations. No additional behavioral details beyond use 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?

Two sentences, front-loaded with action and purpose, no filler. 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 required parameter and no output schema, the description is complete. It explains the action, use cases, and relationship to sibling tools.

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

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

Schema coverage is 100% with one parameter 'key' described as 'Memory key to delete'. Description adds no further semantics 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?

Description clearly states 'Delete a previously stored memory by key.' The verb 'delete' and resource 'memory' are specific. It also implicitly distinguishes from siblings 'remember' and 'recall' by referencing them.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' Provides alternatives by mentioning 'Pair with remember and recall.'

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

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

Discloses read-only, idempotent, non-destructive behavior consistent with annotations. Adds detail on fetching, extracting, and output format (single text blob). No contradictions.

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

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

Two concise sentences plus a bullet-like list of uses. Front-loaded with main action, no wasted words.

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

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

Covers purpose, behavior, and usage adequately for a simple tool. No output schema, but describes output as ready-to-drop text. Lacks error handling or limitations, but acceptable.

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

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

Schema coverage is 100%, so baseline 3. Description does not add significant new meaning beyond schema descriptions, but contextually it's fine.

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 generates a production-ready llms.txt file for any URL, with specific actions (fetches, extracts, emits). Distinguishes from sibling tools like ai_visibility_check by focusing on file generation.

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

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

Explicitly lists three use cases (client indexing, own project draft, competitor audit). Does not mention when not to use 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 declare read-only, idempotent, non-destructive. Description adds that it returns active subscriptions by default and lists returned fields, providing helpful context without contradiction.

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

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

Two efficient sentences: first states action and output fields, second gives usage guidance. No wasted words, front-loaded.

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

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

With no output schema, description lists return fields. Parameter is simple with full schema coverage. Provides usage context. Complete for a straightforward list 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 covers the single parameter fully (100% coverage). Description implies active-only default, reinforcing schema, but adds minimal extra 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 it lists subscriptions, specifies exact return fields (id, type, params, etc.), and distinguishes from siblings like subscribe and unsubscribe.

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

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

Explicitly tells when to use: to review monitored subscriptions before adding more or to find an ID for cancellation. Does not mention alternatives but context is sufficient.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, establishing the tool as a safe read. The description adds detail on the return fields (schema, metadata) but does not disclose additional behavioral traits beyond what annotations convey.

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

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

The description is a single, well-structured sentence that front-loads the action and key output, with an example. 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 read tool with no output schema, the description adequately lists the returned fields (columns, types, row count, category, last-updated). It does not cover error handling or invalid IDs, but the tool's low complexity and annotations make this sufficient.

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

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

Schema coverage is 100% with a clear description of 'resource_id' as a dataset ID with example. The description text echoes this example but adds no 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 the verb 'Get' and the resource 'dataset's schema + metadata', listing specific fields returned (columns, types, row count, category, last-updated) with an example resource_id. It distinguishes from siblings like 'datasets' by specifying the exact output, though not explicitly differentiating.

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

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

No guidance on when to use this tool versus alternatives. The description explains what it does but does not specify when not to use it or provide explicit comparison to sibling tools like 'datasets'.

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 substantial behavioral detail beyond the all-false annotations: it discloses rate-limiting (5 per identifier per day), the claim_token return flow, that the tool is free and doesn't count against quota, and that reports are read daily and affect roadmap. This is rich, honest context that goes far beyond what annotations alone convey.

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; every sentence contributes unique guidance. It front-loads the core purpose, then layers usage criteria, exclusions, and behavioral details. It is slightly verbose but appropriately so given the tool's nuanced usage rules.

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 4 params, no output schema, and no useful annotations, the description carries the full burden and succeeds. It explains the return behavior (claim_token issuance and later resolution checking), rate limits, target audience, and how to frame feedback. No significant gaps remain for an agent to misuse the tool.

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

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

Although schema coverage is 100%, the description adds crucial semantics: it clarifies that claim_token must be passed alone, gives an explicit syntax example, advises 1-2 sentence messages, and emphasizes not pasting end-user prompts. These usage rules meaningfully supplement the schema's field 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 specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly enumerates the feedback types (bug, feature, data_gap, praise) and distinguishes this tool from siblings by positioning it as the channel for reporting issues about Pipeworx tools, not for general questions or actions.

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 when' conditions for each feedback type and includes an important exclusion: only for tools served by this Pipeworx connection, otherwise file with the other server. It also clarifies ambiguity by pointing to the tool list and instructs users not to paste end-user prompts, making when-to-use and when-not-to-use very 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 mark it as read-only, idempotent, open-world, and non-destructive. The description adds beyond: derivation from CF analytics-engine, no PII, caching behavior (5min-1h), and the self-aggregating nature. No contradiction with annotations.

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

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

The description is a single paragraph with clear front-loading: first sentence states purpose. Each subsequent sentence adds value (use cases, data source, caching). No redundant information; 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 no output schema, the description explains return values (top tools, top packs, total call volume) and caching. For a read-only analytics tool with one parameter, this is sufficient. Minor gap: no mention of response format or pagination, but acceptable.

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

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

Schema coverage is 100% for the single parameter 'window', which includes an enum and description. The description adds meaning: distinguishes shorter vs. longer window use cases. This adds value beyond the schema.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume' for a specified window. It opens with a specific verb+resource: 'What other AI agents are calling on Pipeworx right now'. This distinguishes it from siblings like 'discover_tools' (discovery) and 'query' (specific questions).

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

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

The description enumerates three explicit use cases (discovering hot data sources, confirming popular tool, aligning use case). It provides context for window choice (shorter windows for hotness, longer for steady-state). However, it does not explicitly state when not to use it or mention alternatives from the sibling list.

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

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

Annotations declare readOnlyHint, idempotentHint, and openWorldHint, but the description adds rich behavioral details: scanning top 200 markets by volume, partition checks, fill checks against CLOB depth, and filtering logic. No contradictions; the description greatly enhances understanding of the tool's behavior.

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

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

The description is dense but well-structured: purpose first, then mode details, then advanced checks (semantic anchor, partition filter, fill check). It could be slightly more concise by consolidating some technical details, but 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 the complexity of arbitrage detection with multiple modes, the description is thorough. It explains the algorithm, response structure, fill check validation, and references sibling tools for additional context. No output schema, but the response format is described sufficiently.

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

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

Schema coverage is 100% and each parameter has a description, but the tool description adds significant meaning: explains what event slugs/URLs are accepted, how topic mode searches related events, and the contrast between modes. This goes well beyond the schema's 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 states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It specifies two modes (event and topic) and references a sibling tool (polymarket_fill_risk) for custom sizing, clearly distinguishing it from similar 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 explains when to use each parameter: no args for trending scan, event for per-event checks, topic for cross-event scans. It highlights that cross-event mode catches patterns missed by single-event mode. Absent explicit 'when not to use,' but guidance 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.

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds extensive behavioral context: caching (1h at KV level), three model families with details, tradeable-edge knobs, response structure including diagnostics, and a 24h-move warning. No contradictions. Goes well 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 lengthy but well-structured: high-level purpose, detailed segments, response fields, then parameter explanations. Front-loaded with the key idea. Some redundancy (model families listed twice), but given the complexity, every sentence earns its place. Efficient for the information density.

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

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

For a tool with 9 parameters, 3 segments, diagnostic output, and no output schema, the description is remarkably complete. It covers all aspects: what each model does, how knobs filter, response top-level fields, diagnostics, caching, and warnings. No gaps in practical usage guidance.

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 9 parameters. The tool description adds meaningful context beyond the schema, explaining how parameters like min_kelly vs min_partition_leg_kelly interact and the purpose of slippage_pp. Baseline 3, elevated due to added cross-parameter explanations.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It specifies the verb (scan, return), resource (Polymarket markets), and outcome (disagreement opportunities), differentiating it from sibling tools like polymarket_arbitrage which likely handles execution.

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 targets the use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also describes configurable knobs for filtering, but lacks explicit 'when not to use' or alternative tools. Strong context but no exclusions.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable context: response structure (tracked, expired, snapshot_dates), decay computation details (daily closes, net of slippage), and explanation of gaps. 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 relatively long but well-organized into response fields and limits. It is front-loaded with the core purpose. Each sentence adds value, though 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?

Despite no output schema, the description fully details the return structure (tracked, expired, snapshot_dates) and derived fields (first_seen, trend, decay_pp_per_day). It also covers limitations and data context, making it 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 covers 100% of parameters, but the description adds meaningful constraints and defaults (e.g., days lookback default 14, max 30; window families). It clarifies the role of 'window' as snapshot family, which aids selection beyond schema definitions.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry' and explicitly answers the question it addresses, distinguishing it from sibling tools like polymarket_edges. It uses specific verb-resource combinations and domain language.

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 implicit usage guidance by contrasting fresh vs. old edges, implying when to check persistence before trading. It also notes limits (60-day TTL, snapshot gaps). However, it lacks explicit when-not-to-use or alternative tool references.

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 (readOnlyHint:true, openWorldHint:true, idempotentHint:true, destructiveHint:false) indicate safe, non-destructive, possibly varying results. The description complements this by detailing exactly what the tool does: walks the CLOB order-book ladder, returns top_of_book, vwap_fill_price, slippage, and a verdict (clean|degraded|cannot_fill). It also warns about forced_directional_risk, disclosing the key behavioral trait: partial fills can strand the user unhedged. 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 well-structured with clear sections (SINGLE-MARKET, BASKET) and a usage note at the end. However, it is somewhat lengthy (three paragraphs) and includes some redundancy (e.g., repeating default values mentioned in the schema). While every sentence adds information, a more concise version could improve readability without losing content.

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

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

Given the tool's complexity (two modes, multiple return fields) and the absence of an output schema, the description is comprehensive. It details all return fields for both modes, explains the verdict categories, specifies the forced_directional_risk, and provides constraints (max clean notional). This fully equips an agent to understand and invoke the tool correctly.

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

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

Schema description coverage is 100% (all four parameters described). The description adds meaningful context beyond the schema: clarifies that size_usd default 1000 means max spend on buys and target proceeds on sells for single-market, and settlement notional for basket; explains side defaults (auto from partition sum for basket); and describes that market and event are mutually exclusive modes. This adds significant value, justifying 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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes, explaining what each does, and explicitly positions itself as a prerequisite check for arbitrage and edge trades, differentiating it from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

The description provides explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains when not to use it (when theoretical overround may not be capturable) and the risk of partial basket fills converting an arb into an unhedged directional position, offering clear context for when this tool should be consulted.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds substantial behavioral context: it explains that both modes run the same matcher, that returned pairs can still carry compatibility warnings, that unknown legs are never paired, that spreads are gross of Kalshi fees, and that absent temporal alignment does not imply alignment. This is far beyond what the annotations alone convey.

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 every section earns its place given the complexity: modes, response shape, safety fields, fee disclosures, and caveats are all labeled and front-loaded. It is structured well with clear uppercase headings and logical flow. It could be trimmed slightly, but the density is justified for a tool with this many edge cases.

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

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

With no output schema, the description carries the full burden of explaining the return shape and semantics. It covers leg prices, spread entries, compatibility codes, flags, skipped counts, temporal alignment semantics, and the fee caveat. It also explains what null means and warns against interpreting absence of warnings as confirmation of alignment, making it complete for correct invocation and interpretation.

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

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

The schema already provides 100% coverage with descriptions and examples for all three parameters, including the 'overrides' semantics for explicit ticker/slug inputs. The description repeats this information rather than adding materially new parameter-level meaning. It adds some value by explaining that both parameter modes run identical logic, but that is behavioral context, not new parameter semantics.

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

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

The opening line states the tool's exact purpose: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. It goes beyond a vague description by specifying the two modes, the response contents, and the safety disclosures, making it easy to distinguish from sibling tools like polymarket_arbitrage or polymarket_edges.

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

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

The description clearly explains the two usage modes — topic shortcuts versus explicit ticker/slug pairings — and gives concrete shortcode examples. It also warns that pre-mapped topics are not inherently tradeable and that most currently return compatibility warnings, which is useful guidance. It does not explicitly compare against sibling alternatives, but the mode-selection context is strong.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive, so the description's statement 'Returns matching rows as JSON' adds minimal behavioral context. No mention of error handling, rate limits, or pagination behavior beyond the parameters.

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

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

The description is two sentences with no wasted words, front-loading the core purpose and then specifying parameters. It is efficient and easy to parse.

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

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

The description mentions the return format (JSON) but does not elaborate on structure or error cases. Given no output schema, more detail on return values would improve completeness, but the tool's simplicity and annotations mitigate this.

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 value by clarifying that SoQL clauses should omit the leading dollar sign, which is a helpful nuance 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 clearly states the tool runs SoQL queries against a specific dataset by resource_id, with a specific verb and resource. It distinguishes from sibling tools like 'datasets' (which list datasets) by focusing on querying data.

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 how to filter and paginate with SoQL clauses and limit/offset, but does not explicitly state when to use this tool versus alternatives. The context from sibling names suggests this is for data querying, not metadata or dataset discovery.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by explaining scoping to identifier and the behavior of listing all keys when key is omitted, 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?

Four sentences, each serving a purpose: core function, usage, scoping, and pairing. No fluff, well front-loaded with the main purpose.

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 optional parameter and no output schema, the description covers retrieval, listing, scoping, and related tools completely. No gaps.

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

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

Schema coverage is 100% and the description reinforces the schema by explaining the key parameter's behavior. No additional parameter semantics needed beyond what schema provides, so baseline of 3 is appropriate.

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

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

The description clearly states the tool retrieves a value saved via remember or lists all keys when omitted. It distinguishes itself from siblings remember and forget by specifying its role as retrieval.

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

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

The description explicitly tells when to use the tool: 'look up context the agent stored earlier without re-deriving it from scratch.' It also mentions scoping and pairs with remember and forget, but does not explicitly 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?

The description reveals that setting mark_read:true modifies state (flags events as read), which contradicts the annotation readOnlyHint=true. This is a direct contradiction between the described behavior and the annotation hint.

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 (four sentences) and well-structured, starting with the core purpose. It could be slightly shorter but remains informative without unnecessary detail.

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

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

Given the optional parameters and no output schema, the description adequately explains return fields and provides usage notes (polls, alternative access). It is complete enough for an agent to use the tool effectively.

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

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

All five parameters are described in the schema (100% coverage). The description adds value by explaining the mark_read effect and providing example filter values (e.g., 'sec_8k'). This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool's purpose: 'Pull fired events from your subscription feed.' It specifies the return fields (source, citation_uri, payload) and filtering options, distinguishing it from potential siblings by focusing on alert retrieval from a persisted feed.

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 filtering by type and since, and how mark_read works to manage read state. It also mentions that 'Polls work fine' and provides an alternative URL for scripts/dashboards, offering usage context. However, it does not explicitly state when not to use this tool versus siblings.

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

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

Annotations already include readOnlyHint, openWorldHint, idempotentHint. The description adds substantial behavioral context: parallel fan-out to multiple sources, fallback from GDELT to GNews, soft-fail for USPTO, and output structure. No contradictions.

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

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

The description is fairly concise but includes many examples and parenthetical details. It is front-loaded with example queries. Could be slightly more concise, but still effective.

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

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

Given no output schema, the description adequately explains the output (structured changes[] grouped by source, total_changes count, citation URIs). It covers input, behavior, fallbacks, and alternative tool, making it complete for the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining `since` formats in detail with examples, noting `type` is only 'company', and recommending typical usage. This goes beyond the schema's description.

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

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

The description explicitly defines the tool as a change feed for a company over a recent window, with examples of queries and a clear list of data sources. It distinguishes itself from sibling tool entity_profile by contrasting temporal vs static profiles.

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 guidance on when to use this tool (temporal changes) and contrasts it with entity_profile for static profiles. It also advises on typical `since` values ('30d' or '1m'). Lacks explicit 'when not to use' but is still helpful.

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?

Disclosures beyond annotations: scoping by identifier, persistence differences (authenticated vs anonymous with 24h expiry). No contradiction with annotations (idempotentHint=true, destructiveHint=false).

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

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

Four sentences, front-loaded with main purpose, no wasted 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?

No output schema, but description covers storage behavior, scoping, and retention. Fully complete for this simple tool.

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

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

Schema coverage is 100% and already describes key/value with examples. Description adds minimal extra value beyond what schema provides, 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?

Starts with a clear verb+resource: 'Save data the agent will need to reuse later.' Examples (ticker, address, preference) and explicit pairing with recall/forget distinguish it from siblings.

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

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

Explicitly states when to use: 'when you discover something worth carrying forward.' Mentions pairing with recall/forget. Does not explicitly state when not to use, but context is sufficient.

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

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

Annotations already mark this as read-only and idempotent, and the description adds substantial behavioral detail: multi-endpoint cascading lookups, multiple-match behavior returning 'figi_candidates', explicit 'unresolved' fields, source-labeled identifiers, and graceful degradation when GLEIF/OpenFIGI are unavailable. This goes well beyond what annotations provide.

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

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

The description is long but organized with clear sections and front-loaded example queries and usage direction. It loses a point because some clauses are run-on and a few explanations are redundantly worded, such as the repeated clarification about ambiguous bond issuers.

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?

Even without an output schema, the description conveys what each entity type returns, how ambiguity is handled, how unresolved identifiers are represented, and what happens when upstream enrichment sources fail. An agent has enough behavioral context to invoke the tool correctly and interpret partial results.

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

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

Schema coverage is 100%, but the description adds crucial practical guidance: pass only the entity name, for bonds use the issuer exactly as printed, and avoid trailing security-class words. These details prevent real invocation errors and are not inferable from the schema alone.

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

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

The description anchors on a clear verb and object: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It gives concrete example queries and explicitly lists supported entity types, making the tool's role unmistakable even without reading the schema.

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

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

It provides explicit trigger conditions ('What's the ticker for...', 'Use FIRST whenever you have a name but need an ID') and explains edge cases like non-equity instruments. However, it does not explicitly name sibling alternatives or state when not to use this tool, so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint false, but the description adds behavioral details: each entity is probed with ai_visibility_check, results include score/confidence/signal density, and the first entity is treated as the 'subject' for narrative. 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 three sentences, front-loaded with the primary action and use case. Every sentence adds value without redundancy or extraneous detail.

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

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

Despite no output schema, the description explains the return format (ranked list with score, confidence, signal density) and covers the tool's complexity (multiple entities, models, API key option, shared context). It is sufficiently complete for an agent to understand the tool's behavior and results.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds contextual meaning for the 'entities' parameter (first entry is subject) and explains the 'context' parameter, but does not significantly enrich understanding beyond the schema.

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

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

The description clearly states the tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It uses specific verbs ('compare', 'probes', 'ranks') and distinguishes itself from the sibling tool 'ai_visibility_check' by explicitly noting it probes multiple entities and produces a ranked list.

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

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

The description explains when to use the tool: 'Useful for competitive AI-marketing audits' with an example question. It implicitly contrasts with 'ai_visibility_check' (single entity) but does not explicitly mention or exclude alternatives like 'compare_entities' or specify when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: partial failures degrade gracefully, first measurement on a new version can take 5-30s, and sources_failed lists timeouts. This goes 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 long but efficiently structured. It front-loads the core purpose, then provides usage guidance, return details, ecosystem limitations, and behavioral notes. Every sentence adds value, 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?

Despite no output schema, the description details the return contents: summary block fields (is_latest, license, bundle_kb_min, etc.), per-advisory details, links, and alternative versions. It also covers edge cases like partial failures and timeouts, making it 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 coverage is 100% with both parameters described. The description adds minimal extra: package name accepts scoped packages (already implied by schema description 'npm package name'), and version defaults to latest (already in schema). No significant added 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's purpose: a composite check for npm packages aggregating data from deps.dev and bundlephobia. It specifies the resource (npm package) and action (scan for safety/popularity/size), distinguishing itself from sibling tools like deps.dev:version for other ecosystems.

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

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

The description explicitly states when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides clear limitations: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', differentiating from alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds significant behavioral details: max 200K chars with truncation and flagging, embedding model (BGE-base-en), window size (500-char overlapping), similarity measure (cosine), and that every passage has an offset for verification. This goes far beyond annotations.

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

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

Description is compact (5 sentences), front-loaded with core action. Every sentence adds value: purpose, use case, pairing, technical details. No wasted words.

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

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

No output schema exists, but description compensates by explaining return format (passages with offsets and similarity scores). It covers technical behavior, limits, and truncation. Also mentions pairing with another tool. Complete for a tool of this complexity.

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

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

Schema description coverage is 100% (all three parameters documented in schema). Description does not add new parameter-level information beyond what schema provides, though it recontextualizes 'text' as 'already pulled' and gives query examples. At high coverage, baseline is 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?

Description clearly states 'Semantic search INSIDE a fetched record' with verb-resource pair. It distinguishes from siblings by specifying it operates on already-fetched text, contrasting with tools that fetch or search externally. The phrase 'Pairs with ask_pipeworx_grounded' further differentiates.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and explains benefit (saves context, returns only passages that matter). Mentions pairing with a sibling tool. However, does not explicitly list when NOT to use or provide exhaustive alternatives among siblings.

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

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

The description adds behavioral context beyond annotations, such as the need for OAuth, delivery limits (SMS 10/day cap), and that webhook secret is returned once. Annotations indicate mutation (readOnlyHint=false) and idempotency, which aligns with the description.

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 well-structured, but it is somewhat lengthy. However, every sentence adds value, so it earns a 4.

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

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

Given no output schema, the description explains the return (subscription ID) and covers all aspects: prerequisites, types, delivery channels, and limitations. It is thoroughly complete for a complex tool with nested objects.

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 description elaborates on parameter semantics with examples for each subscription type and delivery channel, adding 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 creates a proactive monitoring subscription to a live-data event stream and returns the subscription ID. It uses specific verbs and resources, distinguishing it from siblings like list_subscriptions 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 explains when to use the tool (to set up alerts) and prerequisites (Pipeworx OAuth account, anonymous/BYO cannot persist). It does not explicitly state when not to use it but provides sufficient context given the sibling tools.

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

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

Annotations already declare readOnly, openWorld, and idempotent hints. The description adds behavioral details: it returns category-bucketed example questions with exact tool+argument shapes, drawn from the live catalog, and explains the effect of omitting vs. providing a topic. No contradictions.

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

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

The description is longer but well-structured: starts with common queries, explains output, then usage guidance. Every sentence adds value, though some repetition of categories could be trimmed. Front-loaded with the key purpose.

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?

Without an output schema, the description fully explains the return type (category-bucketed example questions with tool+argument shape) and source (live catalog of thousands of tools). It also references meta-tools, making it complete for the agent to decide to invoke.

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

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

The input schema already describes the `topic` parameter with valid values and default behavior (omit for cross-category). Schema coverage is 100% so baseline is 3. The description adds narrative context by listing categories and reinforcing the logic, providing incremental 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 it is the onboarding entry point for learning what to ask Pipeworx, listing specific example queries and its output of category-bucketed example questions with tool and argument shapes. It distinguishes itself from sibling tools like ask_pipeworx by positioning itself as the first step.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools', providing clear when-to-use guidance. It also implies alternative uses like when the user asks for ideas or getting started, and mentions focusing via topic parameter.

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

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

The description adds significant context beyond annotations: ownership enforcement, deactivation (not deletion), and historical event availability. Annotations indicate destructiveHint=false and idempotentHint=true, which align with the description. No contradictions.

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

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

The description is concise (two sentences) and front-loaded with the core action. Every sentence provides necessary information without redundancy.

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

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

Given the tool's simplicity (one required parameter, no output schema), the description covers all necessary behavioral aspects: purpose, ownership, deactivation, and historical data retention. It is fully complete for effective use.

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

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

Schema coverage is 100% for the single 'id' parameter, which already describes it as a 'Subscription id (uuid) returned by subscribe.' The description adds little parameter-specific detail beyond 'by id,' but the baseline of 3 is appropriate given the schema's completeness.

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

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

The description clearly states the action ('Cancel a subscription by id') and the resource ('subscription'). It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by emphasizing ownership enforcement and deactivation behavior.

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

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

The description specifies that ownership is enforced ('you can only cancel your own subscriptions'), indicating when it is appropriate to use. It also explains that the row is deactivated, not deleted, which guides usage expectations. However, it does not explicitly mention alternatives or 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?

The description goes well beyond the readOnly/openWorld/idempotent annotations by detailing return semantics: the set of verdicts, the meaning of 'could_not_verify' (including verification_error{stage,detail} and the warning not to treat it as evidence), and the distinction with 'unsupported'. It also discloses the routing behavior and evidence requirement, giving agents critical behavioral knowledge not available from annotations alone.

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

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

The description is longer than average but almost every sentence carries information. The initial list of query phrasings is slightly redundant but useful for pattern matching, and the 'IMPORTANT for callers' callout is necessary. It is front-loaded with purpose and usage, then provides structured details on return values and caveats.

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, two parameters, and no output schema, the description supplies the essential context: verdict outcomes, routing logic, evidence/citation behavior, and error-state semantics. The description is sufficiently complete for an agent to understand both function and failure modes without additional 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 coverage is 100%, so the baseline is 3, but the description adds meaningful value: it explains how tolerance_pct interacts with claim wording, provides the default cap of 5, and clarifies the override use case for hallucination detection. It also supplies concrete examples for the claim parameter beyond the schema's examples.

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 explicit natural-language query forms and states the core action: 'natural-language claim verification against authoritative sources.' It clearly distinguishes this from siblings by specifying the two pipeline paths (SEC EDGAR/XBRL for company-financial claims, grounded pipeline for all other facts), making the tool's scope unambiguous.

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

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

Provides explicit when-to-use guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It further differentiates between company-financial and other claims, and explains the benefit over sequential calls ('Replaces 4–6 sequential calls'), giving the agent clear context for choosing this tool over alternatives.

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