Fbi Artcrimes

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds valuable behavioral context: default model (free), optional Anthropic key with BYO billing, per-model return fields (score, confidence, signals, raw_response), and combined view. No contradictions with annotations.

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

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

Single, well-structured paragraph. Front-loaded with purpose and action. Every sentence adds value. Could be slightly more structured (e.g., bullet list for return format) but still efficient for an AI agent.

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 summarizes return structure (per-model + combined). All 4 parameters are explained, and annotations cover safety and idempotency. Moderate complexity; description is sufficient 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 description coverage is 100%, but description adds meaning beyond the schema by explaining default model behavior, the role of _apiKey for Anthropic, and the purpose of the 'context' parameter for disambiguation. This enhances the agent's understanding.

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

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

Description uses specific verb ('probe') and resource ('LLMs for what they know about a business...') and scopes it to visibility scoring (0-100). It clearly distinguishes from siblings like 'entity_profile' or 'deep_research' by framing the use case: AI-marketing audits, pre-launch brand checks, competitive monitoring.

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 (AI-marketing audits, pre-launch checks, competitive monitoring). Does not explicitly state when not to use or list alternatives, but the use-case framing provides adequate guidance for selection among 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?

With annotations already marking the tool as read-only, open-world, idempotent, and non-destructive, the description adds meaningful behavioral context: it auto-routes to the appropriate underlying tool, fills required arguments, and returns structured answers with stable pipeworx:// citation URIs. This sets correct agent expectations about indirection, citation format, and the breadth of data sources. There is no contradiction with the annotations.

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

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

The content is front-loaded with the most important instruction, but the description repeats a nearly identical multi-sentence block a second time, which wastes tokens and violates the principle that every sentence should earn its place. The examples, domain list, and exclusions are valuable, but the duplication makes the description unnecessarily bloated.

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 a single semantic parameter and no output schema, the description is unusually complete: it covers when to use it, what kinds of questions it handles, real examples, explicit exclusions, and the citation-bearing return format. It is slightly incomplete in not differentiating ask_pipeworx from its grounded/beta siblings, but overall an agent has enough context to invoke it correctly in most cases.

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

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

Schema coverage is 100%, and the schema already explains that 'question' is a natural-language request and that q, text, input, query, and prompt are aliases. The description reinforces that the input is a question, but it adds no parameter-level detail beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states what the tool does: it takes a natural-language question and routes it to one of 5,798 tools across 1,517 verified sources, filling arguments and returning a structured answer with citation URIs. It also distinguishes itself from plain web search by enumerating concrete domains like SEC filings, FDA data, FRED/BLS statistics, patents, and real estate. This is specific, actionable, and far beyond a tautology.

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

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

The description gives explicit usage guidance: prefer this over web search for factual questions about real-world data, use it when the user asks 'what is', 'look up', 'find', 'get the latest', or 'how much', and it even includes worked examples. It also lists exclusions such as meta-questions about Pipeworx itself, opinions, math, code generation, and personal advice. However, it does not mention sibling tools like ask_pipeworx_beta or ask_pipeworx_grounded, so the agent is not told when to choose those alternatives instead.

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 read-only, open-world, idempotent, and non-destructive; the description adds substantial behavioral context on top: it is the experimental edge, candidate routing improvements are enabled live, no candidate is currently active, and it is a fully working router rather than a fallback stub. This is exactly the kind of status and caveat information an agent needs.

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 identity and purpose, and every sentence contributes useful information: beta status, current state, usage instruction, and fallback clarification. It is slightly longer than strictly necessary due to repeated emphasis that it matches ask_pipeworx, but the details are earned.

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 references the response shape indirectly by saying it is the same as ask_pipeworx, which is adequate only if the agent already understands ask_pipeworx. It also doesn't list the 5,798 tools, but that is not needed to invoke the tool. Overall it gives enough context to select and call 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%, so the schema already documents all six parameters and aliases. The description only says 'same arguments' and adds no additional parameter-level semantics, which matches the baseline of 3 when the schema carries the burden.

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 by naming the tool as 'Beta version of ask_pipeworx' and specifies its exact role: an identical universal router with the same 5,798 tools, arguments, and response shape, plus experimental routing improvements. This clearly differentiates it from the stable ask_pipeworx sibling while still stating what it actually does.

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

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

It gives an explicit usage condition: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also names the stable alternative and explains the comparison/evaluation purpose. It does not explicitly mention when not to use it relative to ask_pipeworx_grounded, but the beta-vs-stable guidance is sufficient.

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

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

Beyond the readOnly, openWorld, idempotent, and non-destructive annotations, the description fully discloses the behavioral contract: the exact success return shape (answer, evidence, confidence, source, fetched_at, refusal_reason:null), the explicit refusal shape with all five refusal_reason enum values, and the grounding constraint that the answer is extracted ONLY from what the tool result contains. It also discloses the extra LLM call cost, which annotations cannot 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 information-dense with no wasted words. It front-loads the core value proposition ('Hallucination-resistant answer mode'), then precisely lists the behavioral contract, return/refusal shapes, usage guidance, and cost trade-off. Every sentence earns its place, and the structure flows logically from behavior to usage.

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

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

For a tool with no output schema, the description supplies a complete answer contract including both success and refusal payloads with reason enums. It also covers routing behavior, use cases, and the cost-based preference relative to ask_pipeworx. The only sibling not contrasted is ask_pipeworx_beta, but the direct comparison with ask_pipeworx covers the main decision point for an agent.

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

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

Schema coverage is 100%, so the 'question' parameter and its aliases (query, q, prompt, text, input) are already well documented by the schema. The description adds contextual meaning by explaining that the question drives routing and argument filling ('fills arguments'), but it does not add syntax-level details beyond the schema. Baseline 3 is appropriate for fully covered parameters.

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

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

The description defines a specific verb and resource: a hallucination-resistant answer mode that routes through available tools and extracts grounded answers, explicitly noting 'Same routing as ask_pipeworx' but distinguished by using 'ONLY what the tool result contains'. This clearly separates it from at least the closest sibling, ask_pipeworx, and even hints at why ask_pipeworx_beta might exist as a separate variant.

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 when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts', with concrete high-stakes examples (financial verdicts, legal claims, medical lookups, public statements). It also states when NOT to use it ('prefer ask_pipeworx for casual lookups') and justifies this with an objective cost trade-off ('Costs one extra LLM call').

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description extensively details behavior: resolver contract with match confidence, parent event extractor, news fields with fallback info, safety mechanisms for low confidence and closed markets, spread handling, and cancellation rules. This adds significant context beyond the annotations.

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

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

The description is comprehensive but verbose, covering many details in a single block. It is structured with paragraphs and examples, but some information (e.g., cancellation rules, low-confidence handling) could be condensed. Front-loading is good with the purpose statement, but overall length may hinder quick 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?

Given the tool's complexity (multiple classifiers, fan-out patterns, response shapes, resolver contract, safety edge cases), the description covers all necessary aspects. No output schema exists, so the description adequately explains return fields (market, analysis, evidence) and error states. It is complete for agent selection and invocation.

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

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

With 100% schema coverage, baseline is 3, but the description enriches all three parameters: explains market input formats and examples, defines depth with 'quick' vs 'thorough' and default, and details include_raw with use cases and payload sizes. This significantly aids correct invocation.

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

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

The description clearly identifies the tool's purpose: researching a Polymarket bet by pulling Pipeworx data. It specifies the input formats (slug, URL, question text) and outlines what the tool does (resolve market, classify bet, fan out to data packs, return evidence packet and comparison). This is specific and distinguishes it from siblings like polymarket_arbitrage or polymarket_edges, which focus on different aspects.

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'. It gives examples of classifiers and fan-outs, implying when to use. However, it lacks explicit exclusions or references to alternatives, which would elevate it to a 5.

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

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

Discloses data sources (SEC EDGAR/XBRL for companies, FAERS/FDA/trials for drugs), handling of fiscal years, and sorting behavior beyond the readOnly, openWorld, and idempotent 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?

Concise yet comprehensive; every sentence adds unique value. Front-loaded with examples and key guidance, no wasted words.

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

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

Thorough for a tool with no output schema: explains input constraints, data sources, sorting, and result format (paired data + URIs). 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?

Adds meaning to 'type' and 'values' parameters, specifying what each entity type returns and confirming the array constraints (2-5 items). Schema coverage is 100% but description enriches understanding.

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

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

Clearly states it performs side-by-side comparison of 2-5 companies or drugs in one parallel call. Provides specific query phrases ('X vs Y', 'which is bigger') and distinguishes from sequential lookups.

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

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

Explicitly instructs to prefer this tool over sequential single-pack lookups when comparing entities, providing clear when-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context beyond annotations: it explains the parallel decomposition, gap recovery, contradiction flags, hop fields, citation URI fetchability, semantic excerpting, and latency. It also explicitly warns that gaps[] are never invented. The only minor shortfall is not detailing authentication error behavior, but the description already mentions account requirements extensively.

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

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

The description is packed with valuable information, but it is a dense wall of text with multiple parenthetical asides and overlapping explanations. It front-loads the account requirement and core purpose well, but the depth-level explanation appears both in the intro and later in the schema-linking sentence, causing some redundancy. It could be restructured with clearer separation of the headline behavior, depth semantics, and return-value details.

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

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

Given the tool's complexity, the description is thorough: it covers authentication requirements, alternative routing, data source scope, processing model, return packet structure, citation guarantee, gap handling, contradiction scans, and latency. There is no output schema, so the description carries the burden of explaining what the agent will receive, and it does so comprehensively.

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

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

Schema coverage is 100%, and the description adds valuable semantics for the depth parameter by explaining what each depth level does in behavioral terms ('quick=3 single hop', 'standard=3 with gap recovery plus contradictions[]', 'thorough=6 with iterative lead chasing and contradictions[]'). It also elaborates on the question parameter by clarifying that broad/multi-part questions are the intended use. This exceeds what the schema alone provides, though the description is a bit dense in its enumeration.

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 is explicit and detailed: it names the tool's core function ('grounded multi-source research across Pipeworx's 1517 structured data sources'), contrasts it with open-web search, explains the multi-facet decomposition, and distinguishes it from sibling ask_pipeworx. It clearly identifies what the tool does and how it differs from alternatives.

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

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

The description gives strong usage guidance: it says to use ask_pipeworx when not signed in, notes that thorough depth requires a paid plan, and gives concrete examples of good use cases. It also sets latency expectations (15-60s, up to ~90s for thorough), helping an agent decide whether this is the right tool for a given task.

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

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

Annotations indicate read-only, idempotent, non-destructive behavior. The description adds that the tool returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed', which provides valuable behavioral context beyond annotations.

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

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

The description is relatively concise for the amount of information conveyed. It is front-loaded with the core purpose, followed by usage guidance and an explanation of the return value. Each sentence adds value, though it could be slightly more concise.

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

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

Given no output schema, the description adequately explains what is returned (tool names, descriptions, schemas with examples). It covers purpose, when to use, and the output's readiness for direct invocation. A small gap is the lack of detail on how results are ordered (top-N relevance), but overall complete.

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

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

Schema description coverage is 100%, so the description does not need to explain parameters in depth. The main description does not add meaning beyond the schema, which already documents multiple aliases for query. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, FDA drugs, etc.) and distinguishes itself from sibling tools like search_within and deep_research by focusing on tool discovery, not data 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 says 'Call this FIRST when you have many tools available and want to see the option set', providing clear when-to-use guidance. It does not explicitly state when not to use, but the context of browsing vs. direct answering is implied.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior, and the description adds substantial behavioral context: fan-out across many sources, sources_used/sources_failed reporting, empty sections meaning genuine 'no data', a GDELT→GNews fallback, and private companies returning resolved:false with a notes line rather than a bare failure. This deeply helps an agent interpret partial results.

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 user triggers and the core preference, and nearly every sentence carries necessary information. It is dense and somewhat run-on with heavy parentheticals; structuring the sources and return fields as bullets would improve scanability, but nothing feels wasteful.

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

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

For a complex multi-source tool with no output schema, the description covers input variants, output highlights, source failure semantics, fallback behavior, private-company edge cases, and name resolution. An agent has enough context to invoke it correctly and interpret unusual responses.

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

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

The input schema already documents both parameters with 100% coverage, so the schema carries much of the load. The description nonetheless adds useful semantics: concrete examples, emphasis on zero-padded CIKs, interchangeability of ticker/CIK/name for both type values, and the private-company resolution behavior.

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

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

The description clearly identifies the resource as a 'full cross-source profile of a US public company' and pairs it with concrete user triggers like 'Tell me about X' and 'company profile for Microsoft'. It also distinguishes the tool from narrower lookups by stating it should be preferred over chaining single-pack SEC/XBRL/news lookups.

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 lookups when the user asks for a holistic view, which is strong when-to-use guidance. However, it does not name or route to sibling tools such as resolve_entity or compare_entities, so the alternative selection guidance is not fully complete.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. Description adds that it clears sensitive data, but does not detail irreversibility or behavior on missing keys, adding minimal value beyond annotations.

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

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

Two sentences, front-loaded with 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?

For a simple, single-parameter tool with good annotations and schema, the description is complete: it states purpose, usage guidance, and pairs with related tools.

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

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

Schema coverage is 100% with the only parameter 'key' described. The description does not add extra meaning beyond the schema, meeting the baseline of 3.

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

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

Description clearly states 'Delete a previously stored memory by key' with a specific verb and resource. It differentiates from siblings by mentioning pairing with 'remember' and 'recall,' which are for storing and retrieving.

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.' It pairs with siblings but does not explicitly exclude alternative tools, which are many.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive. Description adds behavioral details: fetches page, extracts title/description/key links, emits standard format, output is a single text blob. This goes beyond annotations, though it doesn't cover potential issues like rate limits.

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

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

The description is a concise paragraph of three sentences. It front-loads the main action and purpose, and every sentence adds value. No wasted words.

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

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

Given the tool's simplicity (2 params, no output schema), the description covers the purpose, process, and output format. It is complete and leaves no significant gaps for an agent to understand usage.

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

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

Schema description coverage is 100% with clear descriptions for both parameters. The description doesn't add specific parameter details, but the schema is sufficient. Baseline 3 is appropriate.

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

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

The description clearly states it generates a production-ready llms.txt file for any URL. It specifies the verb 'generate', the resource 'llms.txt file', and the scope 'for any URL'. It details the process (fetches, extracts, emits) and lists use cases, distinguishing 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?

The description explicitly provides usage scenarios: getting a client's site indexed, drafting for own project, auditing competitors. It does not mention exclusions, but the context is clear and sufficient for selection.

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

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

Annotations already establish that this is a read-only, idempotent, non-destructive operation. The description adds value beyond those annotations by enumerating the return content (title, description, crime category, maker, materials, measurements, period, images, case URL), which is especially useful because there is no output schema. No contradiction with annotations.

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

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

Two sentences with no filler: the first states the action and key constraint, and the second lists the return contents. The field list is dense but justified because the tool has no output schema.

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 one-parameter get-by-UID tool with strong safety annotations, the description covers the source of the UID, the scope of the record, and the primary returned fields. It does not state what happens when a UID is not found, but this is a minor gap given the simplicity of the operation.

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 property description already says the UID comes from a list_art_crimes result. The tool description repeats this relationship but adds no new format, constraints, or examples beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description identifies a specific verb ('Get'), a clear resource ('full record for a single stolen or missing artwork from the FBI National Stolen Art File'), and the lookup method ('by UID'). It also distinguishes itself naturally from the sibling list_art_crimes tool by emphasizing that this returns one full record rather than a 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 gives an explicit prerequisite: 'Use a UID returned by list_art_crimes.' This clearly tells the agent where the required value comes from and implicitly differentiates this lookup tool from the list/search sibling. It does not enumerate all when-not-to-use cases, but the guidance is concrete enough for correct selection.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering safety and idempotency. The description adds beyond these by clarifying that only active investigations are included, listing returned fields, and noting the thumbnail URL limitation. No contradiction 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 three sentences with no filler. It opens with the core purpose, follows with return fields, then provides essential filter and pagination usage, all in a compact and easily parsed structure.

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

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

For a simple three-parameter list endpoint, the description covers scope, returned fields, filtering, pagination, and points to get_art_crime for fuller records. With no output schema, the return-field list is sufficient, and annotations cover idempotency and read-only behavior, so nothing essential is missing.

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

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

All three parameters have schema descriptions with 100% coverage, so the schema already explains page, maker, and title. The description restates the substring filtering semantics but adds no significant new meaning beyond what the 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?

The description names a specific verb and resource — browse/search the FBI National Stolen Art File — and enumerates the exact fields returned. It clearly distinguishes list_art_crimes from get_art_crime by noting that the latter provides the full record when a UID is passed.

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 operational guidance: filter by title or maker substring, use page for pagination, and pass a UID to get_art_crime for full records. This provides direct, actionable usage context that routes the agent to the correct sibling tool.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds that it returns only the caller's active subscriptions by default, which is a behavioral detail beyond annotations. No contradiction.

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

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

Two concise sentences: the first specifies purpose and output, the second provides usage advice. Every sentence adds value with no redundancy.

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

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

Without an output schema, the description compensates by listing return fields (id, type, params, etc.) and provides usage context. Minor omission: no mention of pagination or rate limits, but acceptable for a simple list with one optional parameter.

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

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

Schema coverage is 100% for the single optional parameter 'include_inactive' with a clear description. The tool description does not add additional semantics 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?

The description clearly states the action ('List'), the resource ('subscriptions'), and explicitly lists the return fields (id, type, params, created_at, last_fired_at, fire_count). It differentiates from sibling tools such as '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 states when to use the tool: 'to review what you're monitoring before adding more or to find an id to cancel.' Does not provide when not to use or alternatives, but the 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 are all false and provide minimal safety hints, but the description adds substantial behavioral context: filing without an account returns a claim_token, that token can be passed back later to read resolution status, the tool is rate-limited to 5 per identifier per day, and it is free and doesn't count against quota. This goes well beyond the structured fields and matches the actual mutation-like behavior implied by readOnlyHint=false.

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

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

The description is longer than average but every section earns its place: purpose, scope restrictions, claim-token mechanics, rate limits, and reporting cadence. It is front-loaded with the core verb and resource, then flows into usage guidance and behavioral details. It could be tightened slightly (e.g., the 'we cannot fix it' point is repeated), but it remains well-structured and readable.

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 and sparse annotations, the description carries the full burden of explaining return behavior and constraints. It covers the claim_token response, how to check resolution status, rate limiting, what to include/exclude, and the relationship to Pipeworx tools. This is complete enough for an agent to correctly invoke and later follow up on the tool.

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

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

Schema coverage is 100% and each parameter already has a description, so the baseline is 3. The description adds value by explaining the claim_token round-trip workflow with a concrete example ('pipeworx_feedback({claim_token:"pwfb_…"})') and by instructing users to describe issues in terms of Pipeworx tools/packs rather than pasting end-user prompts. This supplements the schema without duplicating it.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This clearly distinguishes the feedback tool from sibling tools like ask_pipeworx or deep_research, which are all inquiry/investigation tools rather than a direct reporting channel.

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

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

The description gives explicit when-to-use conditions (bug, feature, data_gap, praise) and an explicit when-not-to-use: if the tool came from a different MCP server, 'file it with that server instead.' It also clarifies scope by noting that Pipeworx tool names are the ones this connection lists, providing unambiguous selection guidance.

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds valuable context: derived from CF analytics engine, no PII, cached 5min-1h. No contradictions.

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

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

Concise, front-loaded with purpose, uses numbered use cases for clarity. Every sentence adds value without redundancy.

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

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

Despite no output schema, description mentions return structure (pack, tool, count) and caching policy. Could clarify output format more, but sufficient for a simple read 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 parameter fully with enum and description. Description adds interpretative context: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' Adds value beyond schema.

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

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

Description clearly states it returns top tools, packs, and call volume over a window. Distinguishes from siblings like 'discover_tools' by focusing on trending/hotness. Provides specific verb and resource.

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 (discovering hot data sources, confirming canonical tools, aligning use cases) and explains window choice (short for hot, long for steady). Missing explicit when-not-to-use or alternative tools.

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

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

The description deeply details behavioral traits beyond annotations (readOnlyHint, openWorldHint, idempotentHint). It explains trending scan behavior, partition checks, fill checks against live CLOB depth, semantic anchor constraints (Jaccard similarity), and partition filtering. 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 comprehensive and front-loaded with the main purpose, but it is quite lengthy due to detailed explanations of modes, filters, and fill checks. Every sentence provides value, but could be slightly more streamlined 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?

Despite lacking an output schema, the description thoroughly explains the response structure: opportunities array with fields like gap_pp, suggested_trade, reasoning, plus fill check details. Covers edge cases like low similarity and placeholder filters. Complete for a complex arbitrage tool.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond the schema: explains that 'event' mode uses Polymarket event slugs and walks child markets, while 'topic' mode uses seed questions for cross-event scanning. Provides examples of values and behavior differences.

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

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

The description clearly states that the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes itself from siblings like polymarket_edges and polymarket_edge_tracker by specifying its arbitrage focus and unique techniques.

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 explains when to use each mode: call with no args for trending scan, 'event' for a specific market, 'topic' for cross-event scanning. Provides guidance on when not to trade (fill check showing realizable edge ≤ 0). Also notes that cross-event mode catches patterns single-event misses.

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

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

Annotations indicate read-only, idempotent, non-destructive; description adds extensive behavioral context including caching (1h at KV level), model methodology, response segments with diagnostics, and tradeable-edge filtering knobs. Goes far beyond annotations with no contradiction.

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

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

Well-organized with numbered lists and section headers, front-loading the purpose. However, the description is quite long; some technical details (e.g., specific α values, funnel counters) could be trimmed or moved to external documentation 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?

Despite no output schema, the description comprehensively explains the return structure (by_segment, fed_candidates, diagnostics) and all fields (edge_pp_net, kelly_fraction, liquidity, etc.). All parameters are fully described, leaving no gaps for an agent to use the tool correctly.

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

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

Schema covers all 9 parameters with descriptions (100% coverage). The main description adds nuanced context for parameter interactions (e.g., min_kelly vs min_partition_leg_kelly, slippage baseline) and practical usage tips, providing 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 it scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It distinguishes from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by detailing three model families and the response structure.

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 'Built for "what should I bet on today"' and provides guidance on knobs and filters. However, it lacks explicit contrast with sibling tools (e.g., when to use polymarket_arbitrage instead) and doesn't state when not to use this tool.

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

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

Beyond annotations (readOnlyHint, etc.), the description details data source, snapshot TTL, response structure (tracked, expired, snapshot_dates), and computation method. No contradictions with annotations.

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

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

The description is detailed but front-loaded with purpose, then response structure, then limits. It is efficient for the information conveyed, though slightly long. Sentences earn their 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 fully explains the return format with key fields and limitations. It covers all necessary aspects for an agent to understand and use the tool correctly.

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

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

Schema coverage is 100%, and the description adds default values and context for both parameters (days lookback, window family). It provides meaningful additional context beyond the schema.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It answers a specific question and distinguishes from sibling tools like polymarket_edges by focusing on history.

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 with a concrete example (fresh vs. old wide edge) and includes limit information. It implicitly guides usage but does not explicitly mention when not to use it or alternatives.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior; the description adds critical behavioral context: walking the order-book ladder, returning specific fields like vwap_fill_price and slippage_pp, and noting that theoretical overround on thin books is not capturable.

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 with bold section headers, clear mode separation, and all sentences are informative; slight verbosity is justified by 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?

The description fully explains return fields for both modes even without an output schema, covering all relevant details for a 4-parameter tool with two modes and no output schema.

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

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

Schema description coverage is 100% with each parameter described, but the main description adds meaning by explaining how parameters behave differently in each mode (e.g., size_usd as 'settlement notional' in basket mode).

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

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

The description clearly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' with two explicit modes (single-market and basket), and distinguishes from siblings 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?

Explicitly advises using this tool before acting on polymarket_arbitrage signals or polymarket_edges trades above $500, and warns about partial basket fills converting arbs into unhedged directional positions.

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 readOnly/openWorld/idempotent/non-destructive, and the description adds substantial context beyond that: token-overlap matching rather than a verified shared resolution source, gross spreads with no Kalshi fee modeling, the meaning of null temporal alignment, and the conditions under which legs are never paired. This is unusually transparent.

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

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

Long, but almost every sentence carries a distinct operational fact needed because there is no output schema. It is front-loaded with the core purpose and organized by modes, response, safety fields, and standing disclosures. There is minor redundancy toward the end, but the length is justified by the tool's complexity.

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

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

For a tool with no output schema and three optional parameters, the description explains return fields, per-entry flags, compatibility codes, skipped categories, temporal alignment semantics, and fee limitations. Nothing necessary for the agent to choose or invoke the tool correctly appears to be missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds interaction semantics: topic auto-fetches from a fixed shortcut list, explicit parameters override the topic-mapped side, and both modes run the same matcher. It stops short of specifying behavior for partial explicit pairings, but the essentials are covered.

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

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

The description names a specific resource (cross-venue spread between Kalshi and Polymarket), a clear verb (computes/returns), and distinguishes two modes: topic shortcuts vs explicit ticker/slug. It is specific enough to separate this from sibling tools on first read.

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 describes when to use topic mode versus explicit pairing, and cautions that pre-mapped topics often return compatibility warnings and are not automatically tradeable. It does not name alternative sibling tools for when this tool is the wrong choice, but the mode guidance and expected-value caveat are 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds useful behavioral context: scoping to identifier and the behavior when key is omitted versus provided. No contradiction.

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

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

The description is concise, front-loaded with the main action, and every sentence adds value. No superfluous words.

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

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

Given a single optional parameter, no output schema, and rich annotations, the description fully covers the tool's behavior, pairing, and scope. It is 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%. Description adds meaning by explaining the optionality of the key parameter and that omitting it lists all keys, which is not explicit in the schema description.

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

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

The description uses a specific verb 'Retrieve' and resource 'value previously saved via remember' or 'list all saved keys'. It clearly distinguishes from sibling tools remember and forget by mentioning they are to be paired.

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: 'to look up context the agent stored earlier... without re-deriving it from scratch'. Also provides scope info and mentions pairing with remember and forget, providing clear usage context.

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

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

Annotations already declare readOnly, idempotent, and not destructive. The description adds the mark_read state management and polling suitability, providing useful behavioral context without contradicting annotations.

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

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

The description is well-structured: first sentence states purpose, second details return fields, third covers filtering and mark_read, and fourth mentions polling and an alternative. No extraneous 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?

The description covers return fields, filtering, mark_read side effect, and alternative access. It does not detail pagination, but the schema covers limit. Given no output schema, the description is sufficiently complete for a read-only retrieval tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds practical usage guidance for type, since, and mark_read parameters (e.g., ISO timestamp, flagging read items), which surpasses the schema descriptions.

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

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

The description clearly states the tool pulls fired events from the subscription feed, specifies the returned fields (source, citation_uri, raw event payload), and distinguishes from siblings like list_subscriptions by focusing on event retrieval. The alternative URL also clarifies use cases.

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 describes filtering by type and since, the mark_read polling pattern, and an alternative endpoint for scripts/dashboards, providing good usage context. It lacks explicit when-not-to-use or direct sibling comparison, but the guidance is clear enough.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint. Description adds behavioral details: fans out to multiple sources, fallback behavior (GDELT→GNews), soft-fail for USPTO, and return structure (grouped changes, citations). No contradictions.

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

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

Description is densely packed but well-structured. Front-loaded with examples; every sentence adds information. Could be slightly trimmed, but no redundancy.

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

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

No output schema, but description adequately explains return format (changes[], total_changes, citation URIs) and mentions soft-fails. Covers essential aspects given tool 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%. Description enriches with examples ('7d', '30d', '1y'), usage guidance ('Use "30d" for typical monitoring'), and explains 'value' accepts ticker or CIK. Adds value beyond schema.

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

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

Description starts with example queries ('What's new with X') and explicitly states it returns a 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It lists the data sources (SEC EDGAR, GDELT→GNews, USPTO) and distinguishes from sibling '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?

Description provides explicit context for when to use (change feed queries) and suggests an alternative ('Use entity_profile instead when you want the static profile regardless of window'). It also notes the GDELT→GNews fallback. Lacks explicit 'do not use' scenarios.

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

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

Annotations indicate idempotentHint=true and destructiveHint=false, and the description confirms it is a write operation. It adds context about persistent memory for authenticated users and 24-hour retention for anonymous sessions, exceeding 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?

Four sentences, all front-loaded with the primary purpose. Each sentence adds essential information without redundancy or fluff.

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

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

No output schema needed; the description covers purpose, usage, scope, persistence, and sibling relations. It fully serves as a standalone guide for a simple write 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 descriptions cover both parameters fully (100% coverage). The description enhances with example keys and clarifies that value is any text, adding slight additional 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 saves data for reuse across conversations or sessions. It provides concrete examples (resolved ticker, target address, user preference) and explicitly distinguishes from siblings recall and forget.

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

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

The description specifies when to use ('when you discover something worth carrying forward') and how it pairs with recall and forget. It also explains scope by identifier and persistence differences for authenticated vs. anonymous users.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive hints. The description adds substantial behavioral context beyond these hints: it cascades through multiple lookup endpoints, degrades gracefully when LEI/FIGI enrichment is unavailable, returns unresolved identifiers explicitly, and returns figi_candidates when a match is ambiguous. This is rich, useful transparency that helps an agent understand side effects and failure modes.

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

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

The description is long but well-structured, front-loading user intents and the 'Use FIRST' directive, then elaborating on types and edge cases. Every sentence adds operational value, though the density is high enough that it could benefit from more explicit section breaks. It is appropriately sized for a tool with this 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?

There is no output schema, so the description must carry the burden of explaining return behavior. It does so impressively: identifiers are labelled with sources, unresolved identifiers are explicit, ambiguous matches return figi_candidates, and drug results include RxCUI, ingredient, brand, and a citation. An agent has enough context to call the tool correctly and interpret its result.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond the schema. It explains the exact form of the value parameter ('Pass the ENTITY NAME ONLY'), gives concrete examples (AAPL, 0000320193, 'NEW YORK ST DORM AUTH'), and warns against trailing security-class words. It also clarifies what each type accepts (ticker/CIK/ISIN/name for company; brand/generic for drug).

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

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

The description states a specific verb and resource: resolving user-spoken names to canonical/official identifiers, with explicit supported types ('company', 'drug') and examples like 'ticker for', 'CIK for', 'RX CUI'. It clearly differentiates itself from siblings by emphasizing its role as the identity-resolution step that feeds IDs to other tools.

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

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

The description gives an explicit trigger: 'Use FIRST whenever you have a name but need an ID.' It also clarifies acceptable inputs for each type and provides formatting caveats (e.g., pass the issuer name only, not the full noun phrase). It does not, however, name alternative sibling tools or state when NOT to use this tool, so it falls short of a full 5.

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

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

Annotations already indicate safe, non-destructive, idempotent, and open world behavior. The description adds extra context: it probes each entity with ai_visibility_check, it returns a ranked list with score, confidence, and signal density. No contradictions with annotations; description enhances understanding of how the tool operates internally.

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

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

Three sentences with no wasted words: first sentence states main action, second explains the process, third gives a concrete example use case. Perfectly front-loaded and efficient.

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

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

For a composite tool with 4 parameters and no output schema, the description covers purpose, usage context, internal behavior (calls ai_visibility_check), parameter semantics (entity order, model choice, context), and output fields (score, confidence, signal density). Minor gap: no mention of error handling or rate limits, but overall highly informative.

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 schema already documents all 4 parameters. The description adds meaningful context beyond schema: entities first entry is treated as subject for narrative, models can be omitted for default workers-ai, and context disambiguates common names. This adds value for correct invocation.

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 compares AI visibility across multiple entities side-by-side, using ai_visibility_check, then ranks and surfaces most/least recognized. The verb 'compare' and resource 'AI presence across entities' is specific and distinct from sibling tools like ai_visibility_check which only probes a single entity.

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

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

Provides explicit use case: competitive AI-marketing audits, with an example question. It reveals that it internally calls ai_visibility_check, hinting at the alternative for single entities. However, it does not explicitly state when not to use this tool or list alternative tools for single-entity checks or other comparison methods.

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

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

Annotations already declare safe read-only behavior. Description adds important details about partial failures, timing (5-30s for bundlephobia first measurement), and sources_failed list.

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

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

Single paragraph, front-loaded with purpose. Every sentence adds value, but could be slightly more concise. Still very 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?

Despite no output schema, description lists all return fields. Covers inputs, outputs (summary block, advisories, links, alternatives), failure modes, and limitations. 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 has 100% coverage, so baseline is 3. Description doesn't add new info beyond what schema says about parameters (e.g., package name, version default). Does not repeat but also doesn't enhance beyond schema.

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

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

Description clearly states it's a composite check for npm packages using deps.dev and bundlephobia. Distinguishes from siblings by specifying NPM ecosystem and the specific question it answers.

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: for questions about safety, popularity, size of npm packages. Also states NPM-only in v1 and directs other ecosystems to deps.dev:version directly.

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

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

The description discloses that it uses BGE-base-en embeddings with cosine similarity over 500-char overlapping windows, a 200K char cap with truncation flagging. Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and nondestructive nature, so the description adds valuable implementation details without contradiction.

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

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

The description is concise (three sentences) with front-loaded purpose. Every sentence adds value: purpose, usage scenario, 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?

Given the absence of an output schema, the description adequately explains return values (passages with offsets and scores). It also covers input constraints (200K char cap) and pairing with sibling tools, making it complete for an AI agent to use correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context by providing example queries and stating the text parameter has a ~200K char limit. It does not explicitly mention the limit parameter, but implies it with 'top-N'. Slightly above baseline due to practical 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 clearly states the tool performs semantic search inside a fetched record, using specific verbs and resources. It also distinguishes from the sibling tool ask_pipeworx_grounded by explicitly explaining the pairing.

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

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

The description explicitly states when to use the tool: when the record is too large for the prompt. It also provides context on how it saves context and returns passage offsets for verification, and mentions pairing with ask_pipeworx_grounded.

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

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

Description adds behavioral context beyond annotations: OAuth requirement, SMS rate limit (10/day), webhook auto-disable after 10 failures, and that the feed is always on. No contradiction with annotations (idempotentHint=true but description implies unique creation per call? Actually, idempotent might mean same params yield same subscription, but not contradictory).

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 somewhat lengthy but well-structured with clear examples and bullet points. Every sentence adds value, though could be tightened. Front-loaded with purpose and key constraints.

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 multiple subscription types and delivery options without an output schema, the description covers return value, required auth, type-specific parameters, delivery channels with limitations, and auto-disable. Minor omission: no mention of error responses or subscription ID format, but generally 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%, so baseline is 3. Description adds examples for each type's params, delivery constraints (phone verification, webhook signing secret), and rate limits, significantly enhancing guidance 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 creates a proactive monitoring subscription to a live-data event stream and returns the subscription ID. It distinguishes from sibling tools like list_subscriptions and unsubscribe by specifying creation and providing details on types and delivery.

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 states the prerequisite of a Pipeworx OAuth account (anonymous/BYO cannot persist) and gives type-specific examples. While it doesn't state 'when not to use', the context implies it's for creating subscriptions only, with no overlap with listing or unsubscribing.

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 context about the output (example questions from live catalog) and confirms no side effects. 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 long but well-organized, with a clear separation between use cases, parameter details, and output description. Every sentence serves a purpose, though minor tightening could improve conciseness.

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

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

Despite no output schema, the description fully explains the return value: category-bucketed example questions with tool and argument shapes. It also covers the single optional parameter and usage scenarios, leaving 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% for the single parameter. The description goes beyond the schema by explaining the effect of omitting 'topic' (full spread) versus providing a specific one, and lists example topic values, adding significant 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 uses a specific verb ('returns') and resource ('category-bucketed example questions'), clearly distinguishing it from sibling tools like ask_pipeworx or discover_tools. It explicitly positions itself as the onboarding entry point for new agents, making the purpose unambiguous.

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

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

The description explicitly states when to use the tool ('first when you do not yet know what Pipeworx can do') and how to customize via the 'topic' parameter. It does not explicitly list when not to use it, but the strong contextual guidance compensates.

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 value beyond annotations by explaining ownership enforcement, soft deactivation, and the impact on historical events. 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?

Two sentences, concise and front-loaded with the action. No unnecessary words.

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

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

For a simple tool with one parameter and no output schema, the description sufficiently explains behavior, side effects, and references relevant sibling tools (subscribe, recent_alerts).

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

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

Only one parameter (id) is present with 100% schema coverage. The description mentions 'by id' but does not add detail 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 clearly states the action ('Cancel a subscription by id') and resource ('subscription'), distinguishing it from sibling tools like 'subscribe' and 'recent_alerts'.

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

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

The description implies when to use (to cancel a subscription) and adds constraints ('ownership is enforced'), but does not explicitly state when not to use or provide alternative tools for full deletion.

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

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

Annotations already declare read-only/idempotent/non-destructive, and the description adds critical behavioral context: the meaning of 'could_not_verify' (check did not happen, not evidence) and 'unsupported' (no source covered). This prevents a caller from misinterpreting a failure as a refutation, which is exactly the kind of disclosure needed.

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

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

The description is longer than average but each sentence adds value: usage examples, routing logic, verdict definitions, and a clear caller warning. It is reasonably front-loaded and well-structured, though it could be tightened without losing critical 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?

There is no output schema, so the description must carry the full burden of explaining return values and edge cases. It covers verdicts, the grounded/structured value with citation, reasoning, and the error structure for could_not_verify. It also explains the routing logic and the tool's purpose relative to sequential alternatives, making it complete for a composite validation 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% for both parameters, so the baseline is 3. The description adds meaningful nuance beyond the schema by explaining that tolerance_pct overrides the claim wording's implied tolerance and recommending 1–2 for hallucination detection. This extra semantic guidance justifies a 4.

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

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

The description clearly states the tool verifies factual claims against authoritative sources, uses a specific verb (validate/verify), and provides example natural-language usages. It distinguishes itself from sibling research/query tools by positioning as a claim-verification shortcut that replaces a multi-step pipeline.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and describes the routing between company-financial and other claims. It does not explicitly name alternative tools or state exclusions, but the context is strong enough to guide selection.

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