fuiwanted

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

The description adds meaningful behavioral context beyond the annotations: it discloses the default free model (Workers AI Llama-3.3-70b), explains the BYO-key cost implication for Anthropic ('you pay Anthropic directly'), and outlines the per-model response fields. These details address auth needs and external costs, which are valuable for using the tool correctly.

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

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

The description is three sentences long, front-loaded with the main purpose, and every sentence adds functional information—no filler or repetition. It efficiently covers action, models, key parameter, return format, and use cases.

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

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

Given the absence of an output schema, the description compensates by explicitly listing return fields ('per-model {score, confidence, signals, raw_response} + a combined view'). It also explains the two supported models, default behavior, and typical use cases. For a tool with 4 parameters and moderate complexity, this is sufficiently complete for an agent to select and invoke it accurately.

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 specific value by naming the default model ('Workers AI Llama-3.3-70b') and clarifying the role of `_apiKey` in enabling Anthropic probes. This goes slightly beyond what the schema states (e.g., schema does not mention the Llama-3.3-70b model name), so a 4 is appropriate rather than the baseline 3.

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

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

The description clearly states a specific action ('Probe one or more LLMs'), a defined resource ('what they know about a business / brand / product / topic'), and a measurable outcome ('score visibility (0-100) per model'). It also distinguishes itself from broader 'ask' tools by focusing on AI visibility scoring, and provides a concrete output 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?

The description gives clear contexts for use: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains when to pass `_apiKey` (to also probe Anthropic) versus using the free default. However, it does not explicitly name alternative tools or edge cases when it should not be used, stopping short of 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?

Beyond the readOnly/openWorld/idempotent annotations, the description discloses the routing mechanism, the scale of the underlying tool/source network, argument-filling behavior, and the stable pipeworx:// citation URI output. This gives an agent a useful mental model of what happens when the tool is called. It does not mention latency or failure modes, but for a read-only meta-router the added behavioral detail is meaningful.

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 opening is strong and front-loaded, but the description becomes repetitive: the 'START HERE for most questions — even if web search could also answer it. Examples: ...' block appears multiple times in the provided text. This redundancy wastes token budget and obscures the otherwise-crisp guidance. A trimmed version would score much higher; as written, it is poorly structured.

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

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

For a single-required-parameter router tool with no output schema, the description is largely complete: it covers the domain space, trigger examples, routing behavior, and the return value (structured answer with citation URIs). It could be improved by explicitly naming sibling tools to use for alternative cases (e.g., deep_research), but it gives an agent enough to invoke the tool correctly.

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

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

The schema already documents the 'question' parameter and all its aliases (q, text, input, query, prompt) at full coverage, so the schema carries the parameter-semantic burden. The description adds trigger phrases and examples but no new parameter-level meaning beyond what the schema states. The 100% schema coverage sets the baseline at 3.

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

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

The description clearly states what the tool does: it routes factual questions to 5,710 tools across 1,494 verified sources, fills arguments, and returns a structured answer with citation URIs. This is a specific verb+resource and it distinguishes the tool from general web search. However, it does not differentiate it from sibling tools such as ask_pipeworx_grounded or deep_research, so it falls just short of a 5.

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 when-to-use guidance: 'PREFER OVER WEB SEARCH', explicit trigger phrases ('what is', 'look up', 'get the latest', etc.), and example queries. It also says 'START HERE for most questions', making the default usage clear. It lacks when-not-to-use guidance or explicit routing to sibling alternatives like deep_research or ask_pipeworx_grounded, so it is clear but 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?

Even with readOnlyHint and idempotentHint annotations, the description adds meaningful behavioral context: candidate routing improvements may be live, none are currently active, and it is a full working router rather than a fallback. This is genuinely informative beyond the annotations.

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

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

The description is front-loaded with the beta identity and uses every sentence to clarify status, current behavior, and usage. No wasted words; the extra detail about the retired candidate is valuable transparency.

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 the essential beta context and current routing state, and points to ask_pipeworx for response-shape expectations. However, since there is no output schema, the response shape is only referenced by sibling identity rather than described directly, leaving a small completeness gap.

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

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

Schema coverage is 100%, so the schema already documents the question aliases fully. The description mentions 'same arguments' as ask_pipeworx, which is a useful cross-reference but does not deepen parameter meaning beyond the schema.

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

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

The description plainly identifies this as a beta version of ask_pipeworx, an identical universal router with the same tools, arguments, and response shape. It distinguishes itself from stable ask_pipeworx by calling out the experimental edge and candidate routing improvements.

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

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

It explicitly says to use it like ask_pipeworx when wanting the newest routing, and explains that results are compared against the stable router. It does not give explicit when-not-to-use guidance or name alternatives besides ask_pipeworx, but the usage context is clear.

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

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

Beyond the readOnly/idempotent annotations, the description discloses the grounded extraction behavior, the success return contract, the refusal contract with its specific refusal_reason enums, and the extra LLM-call cost. It clearly communicates that the tool will refuse rather than invent facts.

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

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

Every sentence earns its place: purpose, method, return/refusal contract, use cases, and cost/alternative. The most important trait (high-stakes, hallucination-resistant, grounded) is front-loaded, and the rest flows logically without 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?

There is no output schema, so the description compensates by specifying the exact return shape and refusal reason options. It also covers when to use it, when not to, the alternative tool, and the extra LLM-call cost, making the tool fully contextualized for an agent deciding whether to invoke it.

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

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

Schema description coverage is 100%, so the input schema already documents all six parameters. The description adds no per-parameter detail, but it frames the required parameter as a natural-language question and mentions that routing fills arguments, which provides mild context without duplicating the schema.

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

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

The description states a specific verb and resource: it is a hallucination-resistant answer mode that routes across sources and extracts an answer grounded only in the tool result. It also distinguishes itself from the sibling ask_pipeworx by naming the same routing but a stricter extraction behavior.

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

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

It explicitly says when to use the tool ('Use whenever an answer will be quoted, cited, or acted on') and when not to ('prefer ask_pipeworx for casual lookups'). It also names the alternative tool and the cost tradeoff ('Costs one extra LLM call'), giving unambiguous routing guidance.

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

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

Beyond readOnly/idempotent annotations, the description discloses extensive behavioral traits: parallel fan-out, resolution contract (market_match_confidence, alternatives), blocking statuses (low_confidence_match, market_closed_or_inactive), illiquidity warnings, news fallback mechanics, and cancellation-rule risk. No contradictions with annotations.

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

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

The description is exceptionally detailed but well-structured with section labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and front-loaded purpose. Some minor redundancy (e.g., de-indexing nuance) keeps it from a 5, but every sentence adds value.

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

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

Without an output schema, the description thoroughly explains all return shapes: result.market, analysis, evidence, resolver contract, parent_event, news fields, and statuses. It even covers edge cases like cancellation rules and wide spreads, making it highly complete for a complex tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds minimal extra meaning for parameters beyond what the schema already states, though it does contextualize the market parameter's role in resolution and fan-out. It does not discuss depth or include_raw semantics further.

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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly differentiates from siblings by emphasizing single-call bet research with fan-out and evidence packaging, and explicitly defines input formats (slug, URL, question text).

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

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

It provides explicit usage context: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' However, it does not explicitly state when not to use it or name alternative tools like validate_claim, so it falls short of 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?

Adds rich behavioral context beyond annotations: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and returning paired data with citation URIs. This far exceeds the minimal readOnly/idempotent hints from 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 longer than ideal, but every sentence carries practical weight—trigger phrases, preference guidance, data sources, fiscal year nuance, and output format. Front-loading examples makes it scannable, though minor redundancy (e.g., repeating '2–5') could be trimmed.

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

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

Given no output schema, the description explains the return format (paired data + citation URIs), covers both entity types, and mentions behavioral details like sorting. It is fully self-sufficient for an agent to know what to expect and when to invoke it.

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

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

Although the schema describes both parameters (100% coverage), the description adds significant meaning: explains what type='company' vs 'drug' do, provides example values for values, and clarifies constraints (2–5 items). This enriches the schema beyond mere field descriptions.

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

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

The description clearly states the tool performs side-by-side comparisons of 2–5 companies or drugs in a single parallel call, using specific verbs like 'compare', 'rank', and 'head to head'. It distinguishes itself from sequential single-entity lookups, making its purpose unmistakable.

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

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

Explicitly instructs to 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', and provides concrete trigger phrases like 'X vs Y' and 'rank these companies'. This directly tells agents when to use this tool and implicitly when not to, establishing 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 (readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false) already establish a safe read operation. The description goes far beyond them: it explains the parallel decomposition into facets, the gaps[] field that is never invented, the hop field, citation_uri only when fetchable, semantic excerpting instead of head-truncation, contradictions[] for standard/thorough, and time expectations (15-60s, up to ~90s). No contradiction with annotations.

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

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

The description is long but information-dense; every clause adds behavioral or routing value (account prerequisite, tier semantics, gaps field, hop field, citation URI condition, latency). It is front-loaded with the most decision-critical info (account requirement and alternative). It loses one point for being dense/run-on in places, but no filler.

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

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

There is no output schema, so the description must carry the return-format burden, and it does: findings packet with verbatim evidence + confidence + source + fetched_at + pipeworx:// citation, gaps[], hop, citation_uri, contradictions[], latency. It also covers auth/pricing and routing to the sibling. For a 2-param tool with rich behavior, this is complete.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful meaning beyond the schema: it explains what 'quick' vs 'standard' vs 'thorough' actually change in behavior (facet count, gap-recovery hops, contradictions[] scan, paid tier), and clarifies that the question parameter supports broad/multi-part natural language. This is substantial added value.

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

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

The description clearly states a specific verb ('research') and resource ('Pipeworx's 1494 STRUCTURED data sources... in ONE call'), and explicitly distinguishes itself from open-web search. It names sibling ask_pipeworx as the alternative for single lookups, and 'Best for broad/multi-part questions' gives concrete use cases. This is highly differentiated from the sibling 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 explicit when-to-use guidance ('Best for broad/multi-part questions over structured data'), an explicit alternative ('For a single lookup use ask_pipeworx instead'), and a critical prerequisite (ACCOUNT REQUIRED; if not signed in use ask_pipeworx). It also explains depth-tier tradeoffs and expected latency, so an agent can route correctly.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond this: it discloses the return format (names, descriptions, full input schemas with curated examples), the fact that results are ready to call directly (no second schema lookup), and the top-N relevance behavior. This goes beyond what annotations provide.

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

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

The description is three sentences and front-loads the core purpose. The second sentence lists many domains, which is slightly verbose but relevant for a discovery tool. Every sentence earns its place, though the domain list could be trimmed without losing essential meaning.

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 (meta-tool, many siblings, no output schema), the description is quite complete. It explains what is returned (names, descriptions, schemas, examples), when to use it (first when browsing options), and hints at the default/max via the schema's limit parameter. It does not explicitly state pagination behavior, but this is not critical for a discovery tool with a limit 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 description coverage is 100%, with all parameters (query, q, task, limit, search, description) already described in the input schema. The description provides examples of query values but does not add significant meaning beyond what the schema already contains. Baseline 3 is appropriate given the high schema coverage.

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

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

The description clearly states the tool's purpose with a specific verb ('Find tools') and resource ('by describing the data or task'). It explicitly distinguishes itself from siblings by focusing on discovering tools rather than answering queries directly, and reinforces this with 'Call this FIRST when you have many tools available.'

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

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

The description provides explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It lacks an explicit when-not-to-use clause or named alternatives, but the 'not just one answer' implies a contrast with direct-answer tools.

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

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

The description discloses detailed operational behavior beyond the annotations: it fans out across multiple sources, returns specific fields with sorting, handles patents soft-fail (sunset), and uses a GDELT→GNews fallback. It also clarifies input constraints (only ticker/CIK, not names). The annotations already cover safety facets, and the description adds rich behavioral context without any 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 longer than a typical tool description, but it is efficiently packed with examples, use-case guidance, output summary, and limitations. The structure front-loads the purpose with example queries, then details the fan-out and return fields, and ends with input constraints. Every sentence contributes, so it earns a high score.

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

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

Since there is no output schema, the description fully covers expected return values (cik, recent filings with URIs, fundamentals, patents, news, LEI). It also mentions failure behavior for patents and fallback for news, and notes the 'names not supported' edge case. For a complex multi-source tool, this is complete enough for an agent to select and invoke correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description repeats the input format (ticker/CIK) and adds a few example values, but these are already present in the schema. No additional parameter semantics beyond what the schema provides.

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

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

The description is highly specific with concrete verbs and resource: 'full cross-source profile of a US public company in ONE parallel call.' It also lists example user phrases and explicitly contrasts with chaining single-pack lookups, making the tool's primary purpose unmistakable even among many 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 gives explicit when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also provides a clear exclusion: names are not supported, and instructs to use resolve_entity first if only a name is available, naming the alternative 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 destructiveHint=true and idempotentHint=true, so the agent knows the operation is destructive and safe to repeat. The description adds context beyond annotations by explaining why deletion is appropriate (stale, done, sensitive data) and that it removes data saved earlier. It does not contradict 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 the core action, and every clause adds value: the action, the conditions for use, and the pairing with related tools. No filler or repetition.

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 annotations covering safety and idempotence, the description fully covers purpose, usage, and relationships. No output schema exists, but none is needed for a deletion action. The tool is contextually 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%; the 'key' parameter is documented as 'Memory key to delete'. The description repeats 'by key' without adding new semantics. Baseline of 3 is appropriate when the schema fully documents the parameter.

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 ('Delete') and resource ('previously stored memory') and clearly identifies the action by key. It distinguishes from siblings like remember (store) and recall (retrieve), making the tool's 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?

Explicit when-to-use guidance is provided: 'Use when context is stale, the task is done, or you want to clear sensitive data.' It also suggests pairing with remember and recall, indicating relationship to sibling tools. No alternative tools are named for exclusion, but the guidance is concrete 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?

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false), the description adds meaningful behavioral detail: it 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' This clarifies the tool's internal operations and output type, which is valuable context not present in the annotations. It does not contradict any annotation.

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: it begins with the core purpose, explains the process in one sentence, defines the output format, and then lists concrete use cases. Every sentence adds valuable information, and there is no redundant or filler content. It is front-loaded and appropriately sized for the tool's complexity.

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

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

Given the tool has no output schema, the description compensates by clearly stating the output is 'a single text blob ready to drop at site-root/llms.txt.' It also explains the context (AI crawler indexing) and the process. While it does not cover edge cases like invalid URLs or rate limits, for a relatively straightforward read-only generation tool, this is nearly complete. A slight gap is lack of explicit error-handling behavior, but that is not critical for such a 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?

The schema provides 100% coverage for both parameters (url and max_links) with descriptive text. The description does not add any additional parameter semantics beyond what the schema already states. The mention of 'any URL' aligns with the url parameter description, but there is no extra meaning added for max_links. Thus, baseline 3 is appropriate.

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

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

The description clearly states the tool's action: 'Generate a production-ready llms.txt file for any URL.' It specifies the resource (llms.txt), the input (URL), and the process (fetches, extracts, emits). This is distinct from sibling tools like ai_visibility_check or scan_competitor_ai_presence, which focus on visibility audits rather than generating the llms.txt file itself.

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

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

The description provides explicit use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' This gives clear context for when to use the tool. However, it does not explicitly mention when not to use it or offer alternatives from the sibling list, so it falls short of 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context beyond those: it states the data is keyless and official FBI data, and clarifies that caution/remarks/details are returned as plain text. This gives useful behavioral and source transparency without contradicting 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 two efficient sentences with no filler. The first sentence front-loads the tool's purpose and a complete list of returned content, while the second adds access context. Every phrase earns its place.

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

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

With a single required parameter, full schema coverage, and annotations covering safety and open-world behavior, the description provides all essential context: what is returned, that it is keyless, and that the data is official. There is no output schema, but the description enumerates the return fields sufficiently. The lack of explicit invalid-uid error behavior is minor and not necessary 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?

The input schema fully documents the single uid parameter, including its provenance from search_wanted / most_wanted results. The description confirms the parameter is a uid but adds little semantic meaning beyond what the schema already provides. With 100% schema description coverage, 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 uses a specific verb-object construction—'Get the full FBI Wanted profile for one person by uid'—and explicitly enumerates the returned fields. This clearly distinguishes it from sibling tools like search_wanted or most_wanted, which return lists rather than a single detailed profile.

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

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

The description establishes clear context: use this when you already have a specific uid and need the full profile. It also notes the keyless, official nature of the data, implying no auth prerequisites. It does not explicitly name alternatives or state when not to use it, but the context is clear enough for an agent.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive. The description adds behavioral context by clarifying that it lists 'active' subscriptions by default (matching the include_inactive parameter default) and enumerates the exact return fields, which goes beyond the annotation baseline. It does not contradict any annotation.

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

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

The description is two sentences, front-loaded with the primary action, then return fields, then usage guidance. Every sentence adds value, and there is no redundant or filler content.

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

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

For a simple list tool with one optional parameter and strong annotations/schema coverage, the description fully covers purpose, output, and usage scenarios. No output schema is needed, and the description is sufficient for an agent to select and invoke the tool correctly.

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

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

The schema fully describes the sole parameter 'include_inactive' with its default behavior, so schema coverage is 100%. The description's mention of 'active subscriptions' implicitly reinforces the default but does not add additional semantic detail beyond the schema, warranting the baseline score of 3.

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

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

The description begins with 'List the caller's active subscriptions,' which uses a specific verb and resource, clearly stating what the tool does. It also distinguishes itself from siblings like subscribe/unsubscribe by focusing on read-only enumeration of existing subscriptions and lists the exact fields returned.

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

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

The description provides explicit usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This directly tells when to use the tool relative to subscription management actions, referencing adding (subscribe) and canceling (unsubscribe) without naming them explicitly.

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

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

Annotations already declare the tool as read-only, open-world, idempotent, and non-destructive, so the description only needs to add context beyond that. It usefully adds 'current,' 'Keyless,' and 'official FBI data,' but it doesn't disclose output format or pagination behavior.

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

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

Two short sentences deliver the subject, the returned data, and the access model with no filler. The key facts are front-loaded and every sentence earns its place.

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

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

For a one-parameter read-only tool, the definition is mostly sufficient, but the description's 'top-ten list' sits awkwardly with `page_size` allowing up to 20, and it doesn't clarify how `page_size` interacts with the ten-fugitive list. It also doesn't describe the response container/format, though there is no output schema to fall back on.

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 only parameter, `page_size`, is fully documented in the schema ('How many to return (default 10, max 20)'), so the description does not need to restate it. The description adds no parameter-level meaning beyond what the schema already provides.

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

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

The description clearly identifies the resource (the FBI's Ten Most Wanted Fugitives) and the action ('Returns the current top-ten list with reward, warning, and image for each'). It is specific enough to understand what the tool does, though it doesn't explicitly distinguish itself from the sibling tools `get_wanted` and `search_wanted`.

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 its use case: get the current top-ten list rather than a filtered search. However, it does not explicitly say when to use this tool instead of `get_wanted` or `search_wanted`, nor does it mention any exclusions 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?

Beyond the sparse annotations, the description discloses the claim_token mechanism ('returns a claim_token; pass it back later...'), rate limits ('Rate-limited to 5 per identifier per day'), and operational expectations ('The team reads digests daily and signal directly affects roadmap'). It also clarifies that reporting is free and doesn't consume quota, providing full behavioral context.

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

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

The description is long but every sentence earns its place. It is front-loaded with the core purpose, then flows into usage, exclusions, token instructions, and limits. The structure is dense but well-organized, making it slightly less scannable than a shorter equivalent, yet nothing is redundant.

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 the tool's purpose, usage boundaries, claim_token flow, rate limiting, and what happens after submission. It explains the absence of an output schema by describing the return value inline. For a feedback tool with these nuances, the description is fully complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the claim_token usage pattern ('with no other arguments'), advising users not to paste the end-user's prompt, and giving guidance on message specificity. This enriches parameter understanding without contradicting the schema.

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

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

The description opens with a specific, action-oriented verb: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly identifies the resource (Pipeworx team) and the feedback categories (bug, feature, data_gap, praise), and explicitly differentiates from other MCP servers' tools, which uniquely defines its scope among the sibling tools.

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

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

The description gives explicit when-to-use conditions ('Use when a tool returns wrong/stale data... when a tool you wish existed isn't in the catalog...') and when-not-to-use guidance ('if the tool came from a different MCP server... file it with that server instead'). It also tells users how to disambiguate ('Pipeworx tool names are the ones this connection lists').

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 declaring readOnly/openWorld/idempotent, the description adds meaningful context: data provenance ('derived from CF analytics-engine'), privacy ('no PII'), return shape ('just (pack, tool, count)'), and caching behavior ('Cached 5min-1h depending on window'). This goes well beyond the structured annotations.

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

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

The description is front-loaded with the core purpose, followed by use cases and technical caveats. It is longer than strictly necessary but every sentence adds value (use cases, privacy, caching). Structure is clear and scannable.

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

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

For a simple tool with one optional parameter, no output schema, and strong annotations, the description fully covers what the agent needs: return content, use cases, data source, privacy, and cache semantics. No critical gaps remain.

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

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

The single parameter 'window' is fully described in the schema, including the enum values and the trade-off between 'hot right now' and 'steady-state demand'. The description only mentions the window values without adding new meaning, so the baseline of 3 applies.

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

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

The description clearly states what the tool does: 'Returns the top tools, top packs, and total call volume over a recent window.' The opener 'What other AI agents are calling on Pipeworx right now' provides a specific, distinctive purpose that separates it from siblings like discover_tools or 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 'Useful for' list gives explicit scenarios (discovering hot data sources, confirming canonical tools, aligning use cases), which is clear context. However, it does not name alternative tools or explicitly say when not to use it, stopping short of the highest bar.

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

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

The description goes well beyond the annotations (readOnly, openWorld, idempotent, non-destructive). It discloses detailed behavioral traits: monotonicity and partition-sum methodology, Jaccard similarity threshold (≥0.30), placeholder filtering (>20% returns null), and the FILL CHECK logic with realizable_edge_pp ≤ 0 meaning 'do not trade.' No contradictions with annotations; the rich behavioral context fully justifies a top score.

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 densely informational and well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and clear mode-by-mode details. Every sentence adds value—examples, thresholds, response shape, and risk warnings. This is appropriately sized for a complex tool with multiple modes and edge cases.

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

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

Although there is no output schema, the description specifies the response structure (opportunities[] fields, partition_check fields, fill_check results) and explains failure/degenerate cases (null arb signal, thin_legs[], realizable_edge_pp). It covers input modes, semantic pairing, and practical trading advice, making the tool fully actionable without ambiguity.

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% (both `event` and `topic` have descriptions), and the description adds substantial meaning: concrete slug examples like 'fed-decision-may-2026', seed question examples, parameter selection guidance, and what each mode outputs. This exceeds the baseline 3 by providing actionable parameter semantics beyond the schema.

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

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

The description opens with a specific verb+resource combination: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes the tool from siblings like polymarket_edges and polymarket_fill_risk by focusing on arbitrage detection and explicitly referencing polymarket_fill_risk for custom sizing.

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?

Use guidance is explicit: call with NO args for trending_scan, pass `event` for single-event scan, or `topic` for cross-event scan. It recommends `event` for specific markets, explains cross-event mode advantages, and names an alternative (polymarket_fill_risk) for custom sizing. This fully covers when and how to use the 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?

Even with annotations marking read-only/idempotent, the description adds significant behavioral context: response segmentation (by_segment), diagnostics (_diagnostics), 24h-move warnings, caching behavior ("Cached 1h at the KV level keyed on all knobs"), and the Fed note. It discloses limitations and edge-case handling, providing transparency well 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 long and technically dense, but it is well-structured with clear sections (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL). The first sentence front-loads the core purpose. Some redundancy exists, but the complexity of the tool justifies the length.

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

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

Given 9 parameters and no output schema, the description fully covers response structure, filtering knobs, diagnostics, and caching. It even explains why the Fed signal is unreliable, and why a segment may be empty. This is thorough and leaves little ambiguity for an agent invoking 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%, but the description adds actionable depth beyond the schema. For example, it explains that "min_partition_leg_kelly" applies per-leg inside top_legs because "Partition arbs always return kelly_fraction_half=0 at the parent level by design." It also gives guidance like "Bump for very thin partitions; drop to 0 if you have a smarter fill model" for slippage_pp.

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

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

The description opens with a specific verb+resource: "Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price." This clearly states what the tool does and its unique value proposition. It distinguishes itself from siblings like polymarket_arbitrage by focusing on edges from Pipeworx data, not just arbitrage.

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

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

The description provides a clear use case: "Built for 'what should I bet on today' — agents discover opportunities without paging hundreds of markets." It also explains how to tune tradeable-edge knobs. However, it does not explicitly mention when to use this tool vs. sibling alternatives like polymarket_arbitrage or polymarket_edge_tracker.

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 signal read-only, idempotent, and non-destructive behavior. The description adds substantial context beyond annotations: decay is computed on daily closes, snapshots have gaps when no scan occurred, history is bounded by a 60-day TTL, and expired opportunities are precisely defined. This fully discloses the tool's operational behavior.

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

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

The description is long but densely structured with labeled sections (Args, RESPONSE, LIMITS). Every sentence adds critical information for a complex telemetry tool. It is front-loaded with the core question and then elaborates without fluff, making the length justified.

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 documents the response structure (tracked[], expired[], snapshot_dates[]) and their semantics. It covers edge cases like snapshot gaps, TTL limits, and sign conventions, making it self-contained for an agent to invoke correctly.

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

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

Schema coverage is 100%, so both parameters are already described. The description reinforces defaults and adds meaning by explaining that days controls the lookback for the time-series and window selects the snapshot family. The detailed RESPONSE section clarifies how these parameters shape the output, 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 the tool's function: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question about edge age and decay, distinguishing itself from sibling tools like polymarket_edges by focusing on historical persistence. The concrete example of fresh versus old wide edges further clarifies the purpose.

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

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

The description gives clear context for when to use the tool: when you need to know how long an edge has existed and whether it is shrinking. It contrasts fresh versus old edges, making the use case explicit. However, it does not explicitly name alternative tools or state when not to use it, so it falls slightly short of the highest bar.

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?

No contradiction with annotations (readOnlyHint=true, destructiveHint=false). The description adds rich behavioral context: walks the order-book ladder, returns specific fields like top_of_book, slippage_pp, shares_filled, max_fillable_usd, verdict, etc., and warns about forced directional risk in basket mode. This goes well beyond what annotations indicate.

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 with SINGLE-MARKET and BASKET labels. Every sentence provides necessary detail for a complex tool. Not overly verbose; it efficiently packs mode-specific behavior, return fields, and warnings into a structured format.

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

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

Comprehensive for a tool with no output schema. It covers both modes, parameter meanings, return values in detail, risk warnings, and when to use. The description fully compensates for the lack of structured output information, making it complete for an agent to decide and invoke.

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

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

Schema covers 100% of parameters, but the description adds meaningful interpretation: explains how size_usd is interpreted differently in single-market vs basket mode, how side defaults work, and that market/event are exclusive modes. This enhances understanding beyond the schema.

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

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

States a clear, specific purpose: checking realizable-vs-theoretical edge against live CLOB order-book depth. This distinguishes it from sibling tools like polymarket_arbitrage and polymarket_edges, which focus on finding edges rather than assessing fill risk.

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

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

Explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains why: theoretical overround on thin books is not capturable and partial basket fills create unhedged directional risk. This is clear when-to-use and why.

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

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

The description goes well beyond the annotations, disclosing compatibility warning codes, skipped-leg logic, temporal alignment output, and the important caveat that returned pairs may still be unsafe. It also clarifies that legs with unknown metric_type or match_subtype are never paired. This is rich behavioral transparency and does not contradict the read-only annotations.

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

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

The description is long, but the density is justified because there is no output schema and the tool has complex safety semantics. It is structured with clear labels for modes, response fields, and compatibility codes, and it front-loads the core spread concept. Some repetition of schema examples prevents a perfect score.

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

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

For a tool with no output schema, the description is remarkably complete: it explains response contents, spread direction, safety fields, compatibility codes, skipped-pair counters, temporal alignment, and real-world caveats. An agent has enough context to call the tool, interpret the result, and avoid treating unsafe pairings as tradeable signals.

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

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

Schema coverage is 100%, so the schema already documents all three parameters with examples and override behavior. The description mostly restates the same material, adding only mode-level context such as auto-fetching for topic shortcuts. That is useful but does not add substantial parameter meaning beyond the schema.

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

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

The description clearly defines the resource: the cross-venue spread between Kalshi and Polymarket for the same resolving question. It also distinguishes itself from the Polymarket-only sibling tools by emphasizing the two-venue comparison and by laying out two concrete modes of operation.

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 mode-selection guidance: use the topic shortcuts for 10 pre-mapped macro events, or use explicit kalshi_event_ticker and polymarket_event_slug for custom pairings. It also provides a caution that pre-mapped topics are not necessarily tradeable, but it does not name sibling alternatives or state when not to use the 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 establish readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is known. The description adds valuable behavioral context beyond annotations: it discloses scoping to an identifier (anonymous IP, BYO key hash, or account ID) and the dual behavior when the key is omitted, which is not fully captured by the schema alone.

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

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

The description is three sentences, front-loaded with the primary action, and every sentence provides essential information (retrieval behavior, use case, scoping, sibling relationships). No fluff or redundancy.

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

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

Given the tool's simplicity (one optional parameter, no output schema, and coverage by strong annotations), the description is complete: it explains what the tool does, when to use it, how scoping works, and how it relates to remember/forget. Nothing critical is missing for an agent to invoke it correctly.

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

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

Schema description coverage is 100% for the single optional 'key' parameter, and the schema itself already explains 'omit to list all keys.' The description adds illustrative examples of key values (target ticker, address, research notes) but does not meaningfully extend the parameter semantics beyond the schema.

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

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

The description states a specific verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys.' It distinguishes itself from sibling tools by explicitly naming its complementary counterparts (remember, forget), clarifying it is the read operation of a memory trio.

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

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

Explicit when-to-use guidance is present: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also outlines alternatives and relationships via 'Pair with remember to save, forget to delete,' and scopes usage by identifier, implying the tool is not for cross-user data access.

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 mark_read behavior: 'Set mark_read:true to flag returned events read so the next call only shows newer ones,' which directly contradicts idempotentHint: true. A call with mark_read:true changes state for subsequent calls, so repeated identical calls yield different 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?

Four sentences, ~70 words. Front-loaded with purpose, then return format, filtering, and polling/alternative endpoint. Every sentence adds 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?

Without an output schema, the description still explains return fields, filtering, mark_read behavior, and polling suitability. It's comprehensive for a read tool, aside from the idempotency contradiction.

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

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

Schema covers all 5 parameters with descriptions, so baseline is 3. Description adds value by giving an example type ('sec_8k') and explaining the cross-call consequence of mark_read, which the schema doesn't mention.

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

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

The description opens with a clear verb 'Pull' and specifies the resource 'fired events from your subscription feed.' It also details return contents and filtering, differentiating it from sibling tools like list_subscriptions or recent_changes.

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

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

Provides context on suitable use: 'Polls work fine' indicates polling is acceptable, and the alternative endpoint for scripts/dashboards gives an explicit alternative. However, it doesn't explicitly name sibling tools for when not to use this tool, so not 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?

Despite annotations already covering read-only, open-world, idempotent, and non-destructive behavior, the description adds rich context: fan-out to SEC EDGAR, GDELT→GNews fallback with rate-limit/5xx conditions, USPTO soft-fail due to API sunset, and return structure with grouped changes and citation URIs. This goes well beyond annotations.

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

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

The description is dense but every sentence contributes: examples of user queries, the fan-out logic, the `since` format, return details, and the sibling alternative. It is front-loaded with usage examples and remains focused without fluff.

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

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

For a complex tool with no output schema, the description explains the return shape (changes[], total_changes, pipeworx:// URIs), the source-specific behaviors, fallback logic, and soft-fail conditions. Combined with the schema and annotations, an agent has enough to invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description repeats the `since` format but adds no new parameter-specific details beyond what the schema already provides. It does contextualize the 'company' type implicitly, but not significantly more.

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 is a change feed for a company, with examples like 'What's new with X' and 'latest on Y', and specifies it fans out to multiple sources in one call. It explicitly distinguishes from sibling entity_profile by noting when to use that instead.

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 (e.g., 'What's new with X', 'updates on Acme') and gives a clear alternative: 'Use entity_profile instead when you want the static profile... regardless of window.' This helps an agent decide between 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?

Beyond annotations, the description discloses key behavioral details: storage is scoped by identifier, authenticated users get persistent memory, anonymous sessions retain for 24 hours. This adds significant context that annotations (idempotentHint, non-destructive) do not cover.

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

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

Three sentences with the main action front-loaded. Each sentence adds essential information (what, when, persistence), with no wasted words or repetition of schema content.

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

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

Covers purpose, usage, persistence, and integration with sibling tools. The schema is simple and fully covers parameters, so the description is complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% with both 'key' and 'value' described with examples. The description adds only the general 'key-value pair' context, which doesn't go beyond what the schema already 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 clearly states 'Save data the agent will need to reuse later' with a specific storage mechanism (key-value pair). It distinguishes this tool from siblings like recall and forget by focusing on the act of saving, not retrieving or deleting.

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

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

Explicitly says 'Use when you discover something worth carrying forward' and provides concrete examples. It also names the alternative tools ('Pair with recall to retrieve later, forget to delete'), giving clear when-to-use and alternative 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 cover readOnly/idempotent, but the description adds crucial behavior: unresolved identifiers are listed under `unresolved` rather than omitted, LEI/FIGI enrichment degrades gracefully, and every identifier is labelled with its source. These details go well beyond the annotations and help the agent anticipate 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 dense but well-structured with SUPPORTED TYPES and examples. It is a bit verbose with long parentheticals, but every section conveys operational information, and the front-loaded examples help with intent recognition.

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

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

Despite having no output schema, the description thoroughly explains return behavior: identifiers returned for each type, source labelling, explicit unresolved field, graceful degradation, and internal cascading. This makes the tool's behavior predictable and complete 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?

The schema already provides 100% parameter coverage including descriptions. The description adds value by extending the `value` parameter to accept ISIN for company type (not mentioned in the schema) and clarifies 'user-spoken NAME' semantics, which is meaningful 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 the tool's purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It uses a specific verb ('resolve'), identifies the resource (entity names to identifiers), and explicitly positions it with 'Use FIRST whenever you have a name but need an ID,' distinguishing it from sibling tools like entity_profile that likely work with existing IDs.

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 an explicit directive: 'Use FIRST whenever you have a name but need an ID,' along with example queries and supported input formats. It gives clear context for when to use, but lacks explicit 'when not to use' or named alternative tools for cases where an ID is already known.

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. The description adds behavioral context by explaining that it probes each entity with ai_visibility_check, ranks by score, and returns a structured comparison. This goes beyond the annotations without contradicting them, though it does not disclose potential rate limits or external API dependencies beyond the optional _apiKey.

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

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

The description is three sentences, front-loaded with the core purpose, followed by a concrete use case and return value summary. Every sentence contributes substantive information with no fluff or redundancy.

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

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

Given the tool's moderate complexity and the presence of a thorough schema with annotations, the description adequately covers what the tool does, why it would be used, and what it returns. It does not describe error handling or rate limits, but such details are not essential for this read-only, idempotent 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%, so the baseline is 3. The description adds minimal extra meaning beyond the schema; it mentions the ranking behavior but the schema already documents parameter details including the special role of the first entity. No additional parameter clarifications are needed.

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

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

The description clearly states a specific action: 'Compare AI visibility across multiple entities side-by-side.' It distinguishes itself from sibling tools like ai_visibility_check by focusing on multi-entity comparison and ranking, and specifies the output (ranked list with score, confidence, signal density).

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

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

The description provides a clear use case ('competitive AI-marketing audits') and an illustrative example ('does Claude know about us as well as our competitors?'), implying when this tool is appropriate. It references ai_visibility_check as the underlying probe, which helps differentiate, but does not explicitly state when not to use it or name alternative tools.

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

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

The description adds significant behavioral context beyond annotations: composite fan-out across two services, graceful degradation on partial failures, and the 5-30s first-measurement timeout for bundlephobia. It also names the specific failure field (sources_failed) and that the rest of the result still returns, which is critical for an agent to handle unexpected delays.

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

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

The description is dense but every sentence earns its place: purpose, use cases, return summary fields, per-advisory details, ecosystem limitation, and failure behavior are all covered in four sentences. It is front-loaded with the core intent and organized from 'what' to 'when' to 'details' to 'edge cases'.

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

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

With no output schema, the description compensates by listing the exact summary block fields (is_latest, license, published_at, advisory_count, bundle_kb_min, bundle_kb_gz, dependency_count, has_esm, tree_shakeable) and additional outputs (per-advisory detail, links, recent versions). It also covers ecosystem scope and timeout behavior, giving an agent a complete mental model of the tool's capabilities and limitations.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add extra parameter semantics beyond what the schema already offers (package name, version defaulting). It mentions version behavior indirectly but does not duplicate or expand the schema details, so no bonus is warranted.

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

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

The description clearly states a specific verb+resource: a composite 'should I add this npm package' check using deps.dev and bundlephobia. It distinguishes itself from sibling tools by explicitly naming its singular scope (npm packages) and the two data sources, making it unmistakable.

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

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

Explicit when-to-use guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also includes a clear exclusion — NPM ecosystem only in v1, with direction to use deps.dev:version directly for PyPI/Maven/Cargo/Go. This exceeds basic expectations.

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 behavior. The description adds useful context beyond that: 'Returns compact records with reward, warning, and image' and 'Keyless, official FBI data', which clarifies output shape and authentication expectations.

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 compact sentences with no filler. The main action and resource are front-loaded, followed by category coverage, return fields, and access model. Every sentence earns its place.

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

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

For a 7-parameter, no-output-schema search tool, the description covers scope, return highlights, and authentication. The schema handles parameter details. A possible gap is not explaining pagination behavior, but page and page_size are already documented in the 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 coverage is 100%, so the schema already explains all parameters. The description adds value by mapping the enumerated categories to common search/filter values, especially poster_classification, and by indicating that query matches subject name/case title.

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?

Clear verb+resource: 'Search the FBI's Wanted persons database' with an explicit list of covered categories. It is easily distinguished from get_wanted and most_wanted even without naming them, but it does not explicitly call out the sibling differentiation.

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

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

The description implies when to use the tool — whenever you need to search across the FBI Wanted database — and lists the covered categories. However, it gives no explicit guidance about when to use get_wanted or most_wanted instead, leaving the selection between siblings to inference.

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 read-only/idempotent annotations, the description discloses technical behavior: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, a 200K char cap with truncation warning, and offsets for verbatim verification. This is substantial operational context 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?

Four information-dense sentences front-load the core purpose before usage, technical, and pairing details. Every sentence contributes meaningful information with no filler or repetition.

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 tells the agent what comes back (top-N passages, character offsets, similarity scores) and covers constraints, performance characteristics, and a concrete use case. This is complete for a retrieval tool.

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

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

Schema coverage is 100%, and the description enriches each parameter: text is contextualized as 'already pulled' content with size limitations, query gains concrete examples, and limit's default/range is reinforced. The description adds value beyond the schema definitions.

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

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

Description opens with 'Semantic search INSIDE a fetched record' — a specific verb+resource with clear scope. It differentiates from siblings by explicitly pairing with ask_pipeworx_grounded and framing itself as a passage-level retrieval over user-supplied text rather than a general ask tool.

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

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

Provides explicit guidance: 'Use when the record is too big to cram into the prompt' and describes the intended workflow with ask_pipeworx_grounded. This tells the agent when to choose this tool and how it fits with a sibling, exceeding minimal usage instructions.

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 annotation idempotentHint=true directly conflicts with the description's implication that each invocation creates a fresh subscription and returns a new subscription ID ('Returns the new subscription id'). This is a serious annotation contradiction, as the tool would not be idempotent if duplicate subscriptions can be created. Although the description adds useful behavioral details (OAuth requirement, phone verification), the contradiction overrides the dimension score.

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

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

The description is concise yet information-dense, with the main action stated first, followed by supported types and delivery channels. Each section is clearly separated, and no sentences are wasted. The length is appropriate given the complexity of the tool, and the structure is easily scannable.

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 combined with the rich schema covers all necessary aspects: types, parameters, delivery methods, return value (subscription id), and important prerequisites like OAuth and phone verification. It does not mention error handling or rate limits beyond the SMS cap, but for a create-subscription tool, the provided context is sufficient. The idempotency contradiction is a separate issue, though it slightly diminishes overall completeness.

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

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

The input schema already provides 100% coverage, and the description adds extra value by giving concrete examples for sec_8k (e.g., items:['5.02']), polymarket_edge (topic:'fed'), and fred_series (series_id:'UNRATE'). However, the description does not cover all enum values (patent_grant, clinical_trial), which are only present in the schema. This is a minor gap, but overall the description enhances parameter understanding beyond the schema.

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

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

The description clearly states the action and resource: 'Create a proactive monitoring subscription to a live-data event stream.' It distinguishes itself from sibling tools like list_subscriptions and unsubscribe by emphasizing the creation aspect. It also provides a detailed overview of supported subscription types and delivery channels, making the purpose unmistakable.

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

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

The description provides solid usage context including the OAuth account requirement, always-on feed consumption method, and delivery constraints (phone verification, 10/day cap). It also explains how to retrieve alerts via recent_alerts or the public JSON endpoint. However, it does not explicitly name alternative tools for one-time queries or comparative scenarios, leaving some room for ambiguity.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds meaningful behavioral context beyond those: it synthesizes examples from the 'live catalog of thousands of tools' and returns 'each with the exact tool + argument shape,' which sets expectation about the richness and groundedness of results. It does not describe return structure or potential performance impact, but the annotations lower the bar for safety disclosure.

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

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

The description is a single dense paragraph but well-organized: starts with example queries, then states the tool's function, return value, parameter behavior, and usage guidance. It earns its length by packing in user intents, category examples, and explicit when-to-use instructions without redundancy. It might be slightly long, but every sentence adds value.

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

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

Given there is no output schema, the description fully explains what the tool returns (category-bucketed example questions with exact tool+argument shape) and covers parameter behavior (omit for full spread, pass topic to focus). It also addresses the onboarding use case and ties into meta-tool learning, making it complete for a discovery/onboarding 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?

The schema description for `topic` is 100% covered (states allowed values and omission behavior). The description's mention of 'pass `topic` (e.g. "finance", "pharma", "betting")' merely reinforces the schema without adding new semantic detail. Therefore baseline 3 is appropriate because the schema does the heavy lifting.

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

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

The description clearly identifies the tool as the onboarding entry point for discovering what to ask Pipeworx, with a specific deliverable: category-bucketed example questions with the exact tool and argument shape. It lists concrete user intents ('what can I ask Pipeworx?', 'give me ideas', 'getting started') and distinguishes its role from other tools by framing it as the 'onboarding entry point' and referencing meta-tools.

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

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

Explicitly states when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also differentiates by explaining the optional `topic` parameter for focused use versus the full spread, and contrasts with meta-tools like ask_pipeworx, entity_profile, and compare_entities, making the usage context clear.

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

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

Beyond the annotations (idempotent, not destructive), the description reveals that the row is deactivated rather than deleted, and that historical events remain available via recent_alerts. This is valuable behavioral context that annotations alone do not provide.

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

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

Two sentences, front-loaded with the core action, no wasted words. The additional details about ownership and deactivation are essential and presented efficiently.

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 one parameter and no output schema, the description covers the action, the constraint, the underlying behavior, and the downstream effect on recent_alerts. It doesn't mention error cases or success return values, but these are not necessary given the tool's simplicity.

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 fully describes the 'id' parameter as a uuid returned by subscribe. The description reinforces this by saying 'by id' and linking to subscribe, adding a small layer of semantic meaning not in the schema.

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

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

The description starts with 'Cancel a subscription by id' — a specific verb and resource that clearly states the tool's action. It distinguishes itself from sibling subscribe (which creates) and list_subscriptions (which lists) by focusing on cancellation.

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

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

The description provides clear context: you can only cancel your own subscriptions, which is an important usage constraint. It doesn't explicitly name alternatives, but the purpose is self-evident and the ownership caveat effectively guides when this tool should be used.

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

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

The description goes far beyond the annotations by explaining the meaning of verdicts, especially the critical distinction that can_t_verify means the check did not happen and must not be treated as evidence. It also reveals internal routing and tolerance behavior, plus the warning about unsupported, providing substantial behavioral context not available in structured metadata.

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

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

Although the description is long, it is rich with purpose, examples, routing details, verdict semantics, and caller warnings—every sentence earns its place. It is front-loaded with the core purpose and example queries, then smoothly transitions into operational details, making it highly scannable despite its length.

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

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

With no output schema, the description compensates by enumerating all possible verdicts, explaining the meaning of could_not_verify vs unsupported, and detailing both the structured SEC EDGAR path and grounded fallback. It also notes the efficiency advantage over sequential calls, giving an agent complete context to invoke and interpret 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?

The input schema already covers both parameters at 100%, but the description adds meaningful extra semantics: it explains that tolerance_pct overrides the claim-implied tolerance, recommends 1-2% for hallucination detection, and discloses the default cap of 5%. This is valuable beyond the schema's bare field descriptions.

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

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

The description clearly states the tool performs natural-language claim verification against authoritative sources, gives immediate example phrasings, and explains the two routing paths (SEC EDGAR for financial claims, grounded pipeline for all others). It distinguishes itself from simpler lookup tools by describing a combined pipeline that replaces 4-6 sequential calls, making its unique role explicit.

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 when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also describes routing logic for different claim types. However, it does not name specific alternative tools or provide explicit when-not-to-use exclusions, though 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.