wikifeed

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

Beyond the readOnly/idempotent annotations, it discloses that the default model is free, that passing _apiKey calls Anthropic and incurs direct cost, and that returns per-model score/confidence/signals/raw_response plus combined view. This adds useful operational 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?

Three sentences, no filler. Front-loaded with the core purpose, then model details, then return and use cases. 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 tool with no output schema, the description compensates by specifying the return shape. It covers when to use, how to choose models, and key caveats, making it fully navigable for an agent.

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

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

Schema covers 100% of parameters, so the baseline is 3. The description adds value by clarifying that _apiKey is optional unless anthropic is in models, and notes the cost implication of using it. This is extra context beyond the schema.

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

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

The description opens with a specific verb 'Probe' and clear resource (LLMs), and explains the output (visibility score 0-100 per model). It distinguishes itself from siblings like scan_competitor_ai_presence by focusing on probing LLMs directly.

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 states explicit use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It doesn't name alternatives or exclusions, but the context is clear enough for an agent to select it.

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

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

Annotations already cover read-only, idempotent, open-world, and non-destructive behavior. The description adds valuable behavioral context: it auto-routes the question, fills arguments, and returns a structured answer with stable pipeworx:// citation URIs. It stops short of a 5 because operational details like rate limits, timeout behavior, or result-size characteristics are not mentioned.

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

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

The description is long but front-loaded and dense with useful routing rules, examples, and exclusions. The opening imperative and concrete alternatives earn their place, though some redundancy between 'Use whenever...' and 'START HERE for most questions' and the wall-of-text formatting keep it from a perfect score.

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

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

With no output schema, the description explains what the tool returns: a structured answer with stable pipeworx:// citation URIs. It provides trigger phrases, concrete examples, precise alternatives, and explicit exclusions, giving an agent everything needed 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 all six parameters documented as aliases for the natural-language 'question' field. The description's examples reinforce the expected question format but do not add substantive parameter-level semantics 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 states a precise mission: answer factual questions about current or historical real-world data using authoritative structured sources with citations. It names concrete domains, explains that it routes across 5,798 tools from 1,517 verified sources, and differentiates itself from web search and 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 usage guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and clear routing conditions to alternatives like ask_pipeworx_grounded for numeral verification and deep_research for breaking-news or broad multi-day questions. It also lists forbidden use cases such as system capabilities and non-real-world questions.

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, it discloses the beta nature, that candidate routing improvements are enabled live only when under test, that no candidate is active as of 2026-07-26, and that it is a full working router with no fallback. This gives an agent accurate expectations about variability and current parity.

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 compact and front-loads the beta identity, then explains current state, usage, and experimental role. It is slightly wordy with the emphasis sentence, but every sentence adds useful context.

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?

It covers identity, current live state, usage, parity with ask_pipeworx, response shape, and absence of fallback, which is sufficient for a single-required-parameter tool. It does not spell out the concrete response format, but references the same response shape as ask_pipeworx.

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

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

Schema description coverage is 100%, with six aliases fully documented as natural-language question fields. The description adds no parameter-level detail beyond stating that arguments are identical to ask_pipeworx, so the schema carries the burden and the baseline 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 identifies the tool as a beta variant of ask_pipeworx, a universal router with the same 5,798 tools, arguments, and response shape. It distinguishes itself from the stable sibling by its experimental routing intent and current parity state. This is a specific, non-tautological statement of 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?

It explicitly says to use it exactly like ask_pipeworx when the newest routing is desired and notes that results are compared against the stable router. It doesn't provide an explicit when-not-to-use list, but the beta/experimental characterization and the stable alternative are clear enough.

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

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

Beyond the annotations (readOnly, idempotent, openWorld), the description discloses the grounded-extraction behavior, the exact success and refusal return shapes, the possible refusal reasons, and the extra LLM call cost. It gives the agent a clear model of what happens when data does or does not directly answer.

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: core purpose, routing behavior, return contract, refusal contract, usage guidance, and cost trade-off. It is front-loaded with the most important differentiator and avoids 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?

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: success shape, evidence semantics, confidence, source, and refusal reasons. It also covers cost and alternatives, so the agent has everything needed 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?

Schema description coverage is 100% for the single required parameter, and the schema already describes the question parameter and its aliases. The tool description adds no parameter-level semantics beyond that, so the baseline score of 3 is appropriate.

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

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

The description opens with a specific verb and resource: a 'hallucination-resistant answer mode for high-stakes reads.' It clearly distinguishes itself from ask_pipeworx by emphasizing grounded extraction solely from tool results, making its purpose and differentiation immediately obvious.

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

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

The description explicitly states when to use this tool: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also names the alternative, ask_pipeworx, and gives the cost-based preference: 'prefer ask_pipeworx for casual lookups.'

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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false), the description adds substantial behavioral detail: safety short-circuits on low-confidence matches, handling of closed/inactive markets, wide-spread market warnings, resolution-rule risk (e.g., refund_50_50), and fallback behavior for news sources. It also explains that both blocked routes are 'BLOCKING' mechanisms. 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?

Though lengthy, the description is well-structured with clear labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, SAFETY, etc.) and is front-loaded with the main purpose and input format. Every section provides necessary operational details that would be important for an agent to use the tool correctly and interpret results. There is no fluff; each sentence earns its place.

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

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

Given the tool's complexity and the absence of an output schema, the description thoroughly explains the return contract: result.market, result.analysis, result.evidence, resolver contract fields, parent_event extractor, news fallback fields, status codes, and resolution-rule risk. It covers edge cases like low-confidence matches, closed markets, and wide spreads, making the response fully interpretable.

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 has 100% coverage with descriptions for all three parameters. The description adds valuable extra context: examples for the 'market' parameter, clear definitions for depth ('quick = 2-3 evidence sources, thorough = full fan-out'), and the size implications of include_raw (~20KB vs 50-500KB). This augments the schema but doesn't fundamentally change parameter understanding, so a 4 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 primary function: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the input formats (slug, URL, or question text) and outlines the core workflow (resolve, classify, fan out, return evidence + comparison). This distinguishes it from sibling tools like polymarket_edges or validate_claim by emphasizing the market-vs-model analysis and evidence packet.

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

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

The description explicitly provides usage contexts: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also gives extensive fan-out examples showing when specific classifiers apply. However, it does not explicitly state 'when not to use' or name alternative sibling tools for other scenarios, so it falls short of a perfect score.

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/non-destructive annotations, the description discloses rich behavioral details: data sources (SEC EDGAR/XBRL, FAERS), scope (latest 10-K financials, adverse-event counts), edge-case handling (off-calendar fiscal years like AAPL and NVDA), output sorting, and return format (paired data + pipeworx:// URIs). This significantly exceeds what annotations alone convey.

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

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

Although somewhat long, the description is dense with actionable information: trigger phrases, usage rule, data source details, edge-case handling, sorting behavior, and output description. It is front-loaded with the most important trigger patterns, and every sentence contributes to selection or invocation; no filler 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?

With no output schema, the description sufficiently covers return values (paired data + citation URIs), sorting, scope, and performance benefit (replaces 8–15 sequential lookups). Given the tool's moderate complexity and the strong annotations/schema, the description is fully complete for an agent to decide when and how to call this 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 input schema provides enum values and min/max counts, but the description adds crucial semantic meaning: what 'company' and 'drug' types actually retrieve, the exact financial metrics for companies, the data categories for drugs, and the implication that values translate to tickers/CIKs or drug names. This fully compensates and extends the schema descriptions.

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

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

The description opens with specific trigger phrases and clearly states the tool's function: side-by-side comparison of 2–5 companies or drugs in one parallel call. It distinguishes itself from sequential single-pack lookups and from sibling tools by emphasizing parallel comparison and by listing exact data pulled per entity type.

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

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

The description explicitly says to 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear when-to-use guidance. It further details type-specific behavior (company vs drug), result sorting, and the bundled citation URIs, giving the agent concrete instructions for selection and invocation.

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

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

Annotations already mark the tool read-only, idempotent, and non-destructive, and the description adds substantial context beyond that: auth/plan requirements, facet decomposition, parallel routing to 5,798 tools, findings-packet contents, gaps[] never-invented behavior, contradictions[] on some depths, citation_uri fetchability, semantic excerpting, and latency expectations. 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?

Long, but every sentence carries operational or behavioral value. The description front-loads the account requirement and fallback tool, then proceeds through core behavior, ideal use cases, depth semantics, return details, and latency. The length is proportionate to 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 a complex tool with no output schema, the description is complete: it covers the return payload, gap/contradiction behavior, citation_uri conditions, excerpting behavior, auth and tier constraints, depth differences, and timing. An agent has enough context to select the right depth, craft an appropriate question, and interpret the result.

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

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

Schema coverage is 100%, and the description still adds meaning beyond the schema. It explains that questions should be broad/multi-part and that decomposition is the point, and it enriches the depth parameter with concrete hop/recovery/contradiction behavior plus the paid plan constraint for thorough.

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 specific verb ('research') and resource ('1517 STRUCTURED data sources'), details the decomposition and parallel-routing behavior, and explicitly contrasts itself with open-web search and ask_pipeworx. An agent can clearly distinguish this from sibling tools like ask_pipeworx or validate_claim.

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 routes unsigned-in users to ask_pipeworx, says to use ask_pipeworx for single lookups, and recommends deep_research for broad/multi-part questions over structured data. It also explains depth-tier tradeoffs and the paid requirement for thorough, giving clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds valuable behavioral context: it returns ready-to-call schemas, includes curated examples, and avoids a second schema lookup. This goes beyond the annotations without contradicting them.

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

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

The description is concise yet front-loaded: first states the verb and resource, then the use cases, return behavior, and 'call first' guidance. Every sentence adds useful information with no redundancy.

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

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

Despite no output schema, the description clearly explains what is returned (names, descriptions, full schemas, curated examples, ready-to-call). It also covers when to use it and the top-N behavior. For a discovery tool with 6 params and high schema coverage, 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 description coverage is 100%, so the schema fully documents all parameters including aliases and default limit. The description does not add significant semantic detail beyond the schema, per the baseline for high 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 opens with a specific verb and resource: 'Find tools by describing the data or task.' It clearly states the tool's discovery purpose, enumerates relevant domains, and distinguishes itself from sibling tools by emphasizing meta-discovery of available tools (e.g., 'Returns the top-N most relevant tools... ready to call directly').

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.' It also hints at an exclusion ('not just one answer'), but does not explicitly name alternative tools, so it falls short of a full 5.

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

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

This is a major strength. The description reveals the fan-out across multiple sources, names each source, lists exact return fields, explains that sources_used/sources_failed indicate real results, and calls out expected non-results (e.g., FDA-licensed biologics for small-molecule-only companies, USPTO sunset soft-fail, private companies returning resolved:false). This goes far beyond the annotations and prepares the agent for ambiguous-looking but intended 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 proportionate to the tool's complexity, with critical guidance front-loaded before the source list. A small amount of redundancy with the schema (e.g., repeating that type values are interchangeable) costs it a perfect score, but overall every substantial section 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 no output schema, the description must explain return structure, and it does thoroughly: fields, sources, URI format, sorting for fundamentals, and the meaning of sources_used/sources_failed. It also covers edge cases like private companies and soft-failing sources, making the tool self-contained for an agent attempting correct invocation and response interpretation.

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

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

The schema already covers both parameters at 100%, and the description adds even more: concrete examples for value ('AAPL', '0000320193', 'Moderna'), the fact that name resolution happens via SEC EDGAR, and the interchangeability of 'company' and 'ticker' types. This gives the agent confidence in the exact shapes accepted.

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 concrete query examples and immediately states the tool's function: 'full cross-source profile of a US public company in ONE parallel call.' This is a specific verb+resource with clear scope, and it explicitly tells the agent to prefer this over chaining single-pack lookups, distinguishing it from related 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 explicitly states when to use the tool ('when the user asks for a holistic view') and when to prefer it: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups.' It also mentions the expected empty-section behavior and private-company resolution path, giving the agent enough context to decide when invocation is appropriate.

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 the date-scoping constraint but does not disclose additional behavior such as output format or error handling. The annotations already cover read-only and non-destructive hints, so the bar is lower, and the description adds some context beyond the annotations.

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

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

The description is a single, succinct sentence with no filler words. It conveys all necessary information 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?

The tool is simple, with complete schema descriptions and an output schema. The description is adequate for this simplicity, though it could mention that the date is required, but that is already 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 description coverage is 100%, with each parameter described. The description adds no extra parameter semantics beyond stating 'specific date', which is already implied by 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 'Get' and the target resource 'Wikipedia's featured article' with a specific date scope. This distinguishes it from siblings like 'on_this_day' or 'picture_of_day'.

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

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

The description clearly implies usage: when you need Wikipedia's featured article for a specific date, use this tool. However, it does not explicitly mention alternatives or when not to use it.

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

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

Annotations already disclose destructive and idempotent behavior. The description adds context that the tool acts on 'previously stored memory' by key and can be used to 'clear sensitive data,' which clarifies the operational effect beyond bare annotations. No contradiction with annotations.

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

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

The description is three concise sentences: purpose, usage guidance, and companion tools. It is front-loaded with the core function and contains no unnecessary words 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 destructive tool, the description fully covers purpose, usage, and pairing. Annotations handle safety/behavior, and no output schema is needed since it's a delete operation. The description is sufficient for an agent to decide when and how 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?

The schema already provides 100% coverage for the single parameter ('Memory key to delete'), so the description adds little semantic value beyond reinforcing 'by key.' Baseline of 3 is appropriate since the schema carries the parameter meaning.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Delete a previously stored memory by key.' It distinguishes itself from sibling tools like remember and recall by explicitly mentioning pairing with them, clarifying it is the deletion counterpart.

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 scenarios: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also names companion tools (remember and recall), offering clear situational guidance relative to alternatives.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds behavioral detail by explaining the process: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It also specifies the output format ('single text blob') which is useful context beyond the annotations.

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

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

The description is three sentences long, front-loaded with the core purpose, and every sentence adds value. It covers what the tool does, how it works, and concrete use cases without redundancy.

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

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

For a tool with only 2 parameters and no output schema, the description is remarkably complete. It explains the output format ('single text blob'), the process (fetch/extract/emit), and the intended use cases. Even without an output schema, an agent can infer what to expect.

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

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

The schema already provides 100% coverage for both parameters (url and max_links) with clear descriptions. The tool description mentions 'any URL' and maximum links indirectly via schema, but it does not add new semantics beyond the schema. Baseline 3 applies because the schema handles parameter meaning.

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

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

The description clearly states the tool's function: 'Generate a production-ready llms.txt file for any URL.' It specifies the resource (llms.txt), the action (generate), and the target (any URL). It also distinguishes itself from siblings like ai_visibility_check or scan_competitor_ai_presence by focusing on generating the actual file rather than just analyzing visibility.

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.' It does not explicitly mention when not to use the tool or name alternative tools, but the use cases are concrete and clearly guide selection.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is known. The description adds useful behavioral context by specifying the scope is limited to the caller's subscriptions and that the default excludes cancelled ones (which is also in the schema but reinforced). 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-loads the purpose, and concludes with practical usage guidance. Every sentence earns its place with 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?

With a simple single-parameter schema, comprehensive annotations, and no output schema, the description provides sufficient context by listing return fields and specifying scope. It covers purpose, usage, and expected output, making it complete for this read-only list tool.

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

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

The schema fully describes the single optional parameter include_inactive with a clear description and default. The tool description does not elaborate on it further, which is acceptable given 100% schema coverage. It adds no extra semantic meaning beyond the schema.

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

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

The description clearly states the tool's function with a specific verb ('List'), the resource ('the caller's active subscriptions'), and enumerates the returned fields. This distinguishes it from sibling tools like subscribe and unsubscribe.

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

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

The second sentence explicitly advises using this tool before adding more subscriptions or to find an id to cancel, which signals when to use it relative to subscribe/unsubscribe. It doesn't explicitly name alternatives but the context makes it clear.

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

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

Annotations already provide robust safety hints (readOnly, idempotent, non-destructive). The description adds no behavioral context beyond what the schema and annotations convey, such as pagination, date validation, or return format limitations. It only restates the date constraint.

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, front-loaded sentence with no unnecessary words. It efficiently states the tool's purpose without redundancy.

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

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

For a simple read-only tool with an output schema and comprehensive annotations, the description is sufficient. It doesn't explain return values (covered by output schema) or safety (covered by annotations), but it could optionally mention that the date must be valid/historical. Overall, it meets the needs of a straightforward data-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 descriptions cover 100% of the parameters with format examples. The description merely says 'for a specific date,' adding no extra semantics beyond the schema's detailed parameter explanations.

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

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

The description clearly states the tool's action ('Get') and resource ('most-read Wikipedia articles') for a specific date. This differentiates it from siblings like featured_article or on_this_day, which focus on other content.

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

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

The description implies usage when a specific date is known and the user wants top articles, but it does not explicitly mention when to prefer this tool over alternatives or discuss exclusions. The context is clear but not fully elaborated.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well-established. The description adds meaningful behavioral context: the types of content returned (events, births, deaths, holidays) and the 'across all years' scope, which informs the user about the tool's comprehensive temporal nature.

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

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

The description is a single, well-structured sentence that front-loads the action and clearly states the resource and input. There is no redundant or extraneous wording, making it extremely concise and effective.

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

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

The tool is simple with only two parameters, and the schema plus annotations already provide substantial context. An output schema exists, so the description does not need to explain return values. The description covers the core scope and content categories, making it fully complete for this low-complexity 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 input schema has 100% description coverage, with both 'month' and 'day' parameters clearly documented as two-digit strings with examples. The description adds no parameter-specific meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function with the verb 'Get' and specifies the resource: historical events, births, deaths, and holidays. It also defines the input scope (a given month and day) and temporal span (across all years), distinguishing it from all sibling tools, none of which offer date-based historical data.

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

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

The description clearly conveys when to use the tool: whenever a user needs historical events, births, deaths, or holidays for a specific month and day. It provides a clear context without explicit exclusions, but since no sibling tools share this exact purpose, strong differentiation is not needed.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds valuable behavioral context by specifying the return contents (title, description, image URL) and the date-scoped nature of the retrieval, going 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 a single, concise sentence that gets straight to the point. It front-loads the main action ('Get Wikipedia's picture of the day') and adds necessary details without filler. Every sentence (and word) 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 simple 3-parameter retrieval tool, the description is complete. It explains what the tool does, what it returns, and the input scope (specific date). Output schema exists, and annotations cover safety. No critical information is missing.

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

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

Schema description coverage is 100%, with each parameter (year, month, day) clearly described. The description does not add syntax details beyond what the schema provides, so the baseline score of 3 is appropriate. It reinforces the date concept but doesn't enhance parameter understanding.

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

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

The description clearly states the tool's purpose: 'Get Wikipedia's picture of the day for a specific date'. It uses a specific verb ('Get'), identifies the resource ('Wikipedia's picture of the day'), and mentions the return contents (title, description, image URL). This distinguishes it from siblings like featured_article or on_this_day.

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?

Usage context is implied: the tool retrieves a picture based on a specific date, but there is no explicit guidance on when to use it versus alternatives or exclusions. Sibling tools like featured_article are clearly different by name, but the description doesn't mention them or provide when-to-use/when-not-to-use guidance.

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

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

The description discloses rate limiting ('Rate-limited to 5 per identifier per day'), the claim token flow ('Filing without an account returns a claim_token; pass it back later...'), and that it's free and doesn't count against quota. These are behavioral details beyond the annotations, which are minimal (all hints false). 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?

While the description is fairly long, every sentence conveys a distinct, essential piece of information: what it does, when to use it, when not to use it, how to identify Pipeworx tools, what not to include, the claim token mechanics, and rate limits. It starts with the core purpose and then layers actionable details, maintaining full reader value per sentence.

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 explains what to expect (a claim_token when filing without an account) and how to later retrieve the outcome. It covers limitations (rate limit, only Pipeworx tools, no end-user prompts) and even notes the team's daily digesting and roadmap impact, giving a complete picture of behavior and scope.

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 meaningful semantics for the claim_token parameter by explaining the workflow: pass the token back as pipeworx_feedback({claim_token:"pwfb_…"}) to read resolution status. It also maps the different feedback types (bug, feature, data_gap) to concrete scenarios in prose, reinforcing the enum meanings.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes itself from the sibling research and information tools by framing the action as feedback submission to the Pipeworx team, with no other tool serving a similar 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?

Explicit when-to-use guidance is provided: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear exclusion: 'ONLY for tools served by this Pipeworx connection' and tells the user to file with the other server if the tool is from a different MCP. This is strong alternative-switching guidance.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable context: data source ('CF analytics-engine'), privacy ('no PII'), output shape ('just (pack, tool, count)'), and caching ('Cached 5min-1h depending on window'). This goes beyond the structured hints.

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

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

Three sentences, well-structured, with the main purpose front-loaded. Each sentence adds value: what it returns, why it's useful, and behavioral details. 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?

For a simple tool with one optional parameter, no output schema, and rich annotations, the description is thorough. It covers the return contents, use cases, data provenance, privacy, and caching. There are no apparent gaps for an agent to invoke this 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 provides 100% coverage for the single 'window' parameter, including enum values and a description. The tool description repeats the window guidance but doesn't add new semantic meaning beyond what the schema already documents. 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 function: returns top tools, top packs, and total call volume over a selected window. It specifies the resource (Pipeworx trending data) and distinguishes it from sibling tools by focusing on aggregated usage patterns of other AI agents.

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

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

Provides explicit use cases: discovering hot data sources, confirming canonical tools, and checking alignment with agent needs. It also explains the trade-off between window lengths ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). However, it doesn't mention when not to use or name alternative tools, 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?

Although annotations declare readOnlyHint=true and destructiveHint=false, the description adds substantial behavioral context: the fill check logic (realizable_edge_pp ≤ 0 means do not trade), the partition filter and placeholder-slug dropping, the semantic anchor Jaccard threshold, and the response structure. This goes far beyond the annotations and provides essential operational nuance.

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 carries substantive information. It uses clear section-like markers (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) that aid scanning. It's slightly over-stuffed for a tool description, but the density is justified by the tool's complexity; no sentence 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?

For a tool with 2 optional params and no output schema, the description is remarkably complete. It explains the no-arg mode, both named modes, response fields (opportunities[], partition_check, gap_pp, suggested_trade, etc.), and critical edge-case behavior (thin legs, last-trade vs book). It even cross-references a sibling tool for sizing. Nothing essential is missing.

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

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

Schema coverage is 100% (both params have descriptions), but the tool description adds extensive meaning: what 'no args' does, the difference between event and topic modes, example event slugs and topic seeds, and the fact that full URLs are accepted. It transforms the params from schema stubs into a full decision guide.

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 statement: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes the tool's focus (arbitrage detection) from siblings by detailing event vs topic modes and mentioning polymarket_fill_risk as a separate tool for custom sizing. The purpose is unmistakable and unique.

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 usage guidance is provided: 'Call with NO args for a trending_scan... pass event... or topic...' It also gives recommendations ('event (recommended for a specific market)', 'topic (for cross-event scanning)') and points to an alternative: 'For custom sizing use polymarket_fill_risk.' This fully covers when and how to invoke 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral context beyond these hints: caching at the KV level for 1h, the 24h-move warning, per-leg Kelly quirks for partitions, placeholder-slug filtering, and the rare-by-design nature of concentrated longshots. It also explains why Fed bets are excluded from ranking. 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 an extremely long, single-paragraph wall of text with dense acronyms (FRED, GDELT, EFFR, OIS/SOFR) and complex nested explanations. While every sentence adds value, the lack of section breaks or bullet points makes it difficult to parse quickly. It could be restructured with headings for model families, knobs, and response format without losing information.

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

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

With no output schema, the description fully specifies the response top-level structure (by_segment, fed_candidates, _diagnostics), the model families and their inputs, the filters and their effects, and the diagnostic counters. It covers caching, edge calculation, and caveats like the unreliable Fed signal. For a tool with 9 parameters and no output schema, this is thoroughly complete.

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

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

Schema coverage is 100% with each parameter well-documented. The description adds extra semantic context: slippage_pp default is explained (zero fees but 20-50bp per trade), min_kelly is tied to half-Kelly, and min_partition_leg_kelly applies to per-leg Kelly inside partitions rather than the parent level. This enhances the agent's understanding beyond the schema definitions.

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

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

The description states the tool 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This is a specific verb+resource+outcome, clearly distinguishing it from sibling tools like polymarket_arbitrage or polymarket_edge_tracker by focusing on model-driven and structural opportunities. The 'what should I bet on today' phrase further clarifies the intended use case.

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

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

The description explicitly targets the use case of discovering betting opportunities without paging hundreds of markets, and it explains the tradeable-edge knobs for filtering. It does not explicitly name alternative tools or say 'use this instead of X', but the purpose is clear enough that an agent can infer when to select it over siblings. No exclusions are provided, but the context is sufficiently explicit.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds significant behavioral context: snapshots are written on cache-miss so gaps mean no scan, history is bounded by a 60-day TTL, and decay is computed from daily closes rather than intraday. This goes far 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 verbose but well-structured with labeled sections (Args, RESPONSE, LIMITS). It earns most of its length given the tool's complexity, though some elaborative phrases could be trimmed without losing 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?

With no output schema, the description fully explains the response shape (tracked, expired, snapshot_dates), the meaning of edge values (negative = SELL YES), and all relevant limitations. It covers every aspect an agent would need to use the tool correctly.

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

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

The input schema already provides 100% coverage with descriptions and clamps for both parameters. The description restates defaults and adds the 'snapshot family' concept, but this is marginal reinforcement rather than substantial new meaning.

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

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

The description explicitly identifies the tool as 'edge persistence and decay telemetry' and states the exact question it answers ('how long has this edge existed and is it shrinking?'). This distinguishes it clearly from siblings like polymarket_edges, which focus on current edge data.

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

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

It provides a strong contextual use case by contrasting fresh vs. old edges and implying when to use it (when edge age/decay matters). However, it does not explicitly name alternative tools or state when not to use it (e.g., for current edges, use polymarket_edges).

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

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

Annotations declare read-only, idempotent, and non-destructive behavior; the description adds substantial detail: it walks the order-book ladder, interprets size_usd differently for buys vs sells and for basket mode, returns fields like slippage_pp and max_fillable_usd, and warns that partial fills convert an arb into an unhedged directional position. 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, with clear structural separation for single-market and basket modes. The opening line states the core purpose, and the subsequent details are organized and purposeful; no sentence is wasted, though the length is substantial.

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 fully by enumerating return fields for both modes (e.g., top_of_book, vwap_fill_price, slippage_pp, verdict; theoretical_sum, realizable_sum, capture_ratio, thin_legs, forced_directional_risk). It also covers edge cases like partial fills, provides risk context, and explains the tool's role among siblings. This is 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?

The schema descriptions already cover all parameter meanings (100% coverage), so the baseline is 3. The description adds critical nuance: it states that one of market or event is required (schema shows 0 required), explains size_usd default and clamping (default 1000, clamp 10-1,000,000), and contrasts the interpretation in single-market (max spend or target proceeds) vs basket (settlement notional). This goes beyond simple type/description.

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

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

The description opens with a specific purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes itself from sibling tools by explicitly positioning itself as a pre-trade check before polymarket_arbitrage or polymarket_edges trades, and it describes the two modes (single-market and basket) with concrete outputs.

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 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500,' giving unambiguous when-to-use guidance. It also indirectly tells when not to rely on it by warning that theoretical overround on thin books is not capturable, framing the tool's necessity.

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

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

Annotations already mark the tool as readOnly/idempotent/non-destructive, and the description adds substantial operational context beyond that: the standing fee disclosure ('this tool does not model Kalshi's fee schedule — every spread_pp is gross, not a net tradeable edge'), the pairing_unverified caveat, the rule that unknown metric_type/match_subtype legs are never paired, and the precise meaning of null in temporal_alignment. No contradiction with the annotations; the description earns its keep.

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

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

Long but deliberately structured with capitalized section labels (TWO MODES, RESPONSE, SAFETY FIELDS, Codes) and front-loaded purpose. Nearly every sentence carries a distinct caveat an agent needs — fee grossness, null semantics, skip counters — though a few points (e.g., the temporal_alignment_unknown/null warning) are restated across sections and 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?

With no output schema, the description must carry the full burden of explaining the response, and it does: response shape (leg-by-leg prices 0-1, top_spreads_pp with Kalshi − Polymarket), safety fields and their codes, per-entry flags, skipped/unknown-leg handling, fees_note, and skip counters. For a tool with this much edge-case nuance, nothing an agent needs to invoke it safely is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds value on top by framing the three parameters as two mutually exclusive modes (topic vs explicit pairing) and clarifying that both modes run the identical token-overlap matcher with identical disclosures. This mode-based semantics is not present in the schema itself.

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 first sentence states the tool's job precisely — 'Cross-venue spread between Kalshi and Polymarket for the same resolving question' — naming both venues and the scope. It differentiates from siblings like polymarket_arbitrage and polymarket_edges by being the explicitly cross-venue (Kalshi + Polymarket) comparison tool, and it explains the two operating modes without tautology.

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

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

Clear guidance is given for when to use each mode: 'topic' for 10 pre-mapped macro shortcuts and explicit kalshi_event_ticker + polymarket_event_slug for custom pairings, with an explicit note that both run the identical matcher. It also sets expectations ('Real cross-venue spreads are rarer than the macro-shortcut list suggests... pre-mapped ≠ tradeable'). It doesn't explicitly name alternative sibling tools or state when-not to use them, 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=true, idempotentHint=true, and destructiveHint=false, which the description aligns with. Beyond that, the description adds useful behavioral context: the tool is scoped to the caller's identifier (anonymous IP, BYO key hash, or account ID) and that omitting the key lists all saved keys. This adds value over the annotations without contradicting them.

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

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

The description is three sentences, front-loaded with the action, and every sentence adds essential information: function, use case, scoping, and relationships to sibling tools. There is no filler or redundancy.

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

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

The tool is simple (one optional parameter, read-only, no output schema), and the description covers the essential behaviors: retrieval vs. listing, scoping, and pairing with remember/forget. It does not detail the return format or behavior for missing keys, but given the tool's simplicity and the annotations covering safety, it is sufficiently complete for an agent to select and 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 coverage is 100% and the key parameter is described in-schema. The description goes further by giving concrete examples of what keys may represent (target ticker, address, prior research notes) and explicitly explains the omit-key behavior, which reinforces and enriches the schema's meaning. This justifies a score above the neutral 3 baseline.

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

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

The description opens with a specific verb and resource: 'Retrieve a value previously saved via remember' and clearly distinguishes the alternate mode 'or list all saved keys (omit the key argument)'. It references sibling tools (remember, forget) to position itself, making the purpose unambiguous and differentiated from the many other tools.

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

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

The description explicitly states when to use this tool: 'Use to look up context the agent stored earlier' with concrete examples (target ticker, address, research notes). It also provides usage relationships: 'Pair with remember to save, forget to delete.' However, it does not explicitly state when NOT to use it or name a specific alternative for exclusion, 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?

The annotations claim readOnlyHint=true, but the description describes a state-changing operation via mark_read:true, which flags events as read and affects future calls. This contradicts the read-only annotation, so the transparency score is a 1 per the contradiction rule. The description itself provides good transparency, but the annotation conflict makes it untrustworthy.

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

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

The description is concise and front-loaded. In three sentences, it covers the purpose, return payload, filtering options, side-effect flag, and an external endpoint. 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?

With 5 optional parameters and no output schema, the description provides sufficient context: it names the key return fields, explains how mark_read affects subsequent polling, and mentions an alternative access method. Given the tool's complexity, this is a complete description.

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?

While the schema already covers all parameters (100%), the description enriches the meaning of key parameters: it gives a concrete example for type ('sec_8k'), clarifies the semantics of since (ISO timestamp, events fired_at >= time), and explains the mark_read side effect and its effect on subsequent calls. This goes beyond the schema descriptions.

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

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

The description begins with a clear verb phrase 'Pull fired events from your subscription feed' and elaborates on return contents and filtering. It distinguishes from sibling tools like list_subscriptions or most_read by focusing on alerts from the persisted feed.

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

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

It gives context that polling works fine and provides an explicit alternative HTTP endpoint for scripts/dashboards, which clarifies when to use this tool vs direct access. However, it does not mention sibling tools as alternatives, so it's not a perfect 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 readOnlyHint/idempotentHint annotations, the description details fallback behavior (GDELT→GNews on rate-limit/5xx), soft-fail due to USPTO API sunset, and the parallel fan-out execution model. These are behavioral facts an agent needs to set expectations, and they add significant transparency.

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

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

The description is longer than average but front-loads the core purpose and then systematically covers sources, fallback, return shape, and alternative tool. Each sentence carries substantive information, so the density is justified; however, a bit of pruning could improve scannability.

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 explicitly stating return structure (changes[] grouped by source, total_changes, citation URIs), enumerating all sources, and disclosing failure modes. This gives an agent everything needed to invoke the tool and interpret results, making it 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?

While schema coverage is 100%, the description enriches the 'since' parameter by tying it to the window applied across sources (filings since `since`, news in window) and offers practical guidance ('Use "30d" or "1m" for typical monitoring'). This adds contextual semantics beyond the raw format descriptions.

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

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

The description opens with natural-language query examples and a precise definition: 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It explicitly names the data sources (SEC EDGAR, GDELT→GNews, USPTO) and contrasts with sibling tool entity_profile, fully distinguishing it from alternatives.

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

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

It provides explicit when-to-use triggers ("What's new with X", "latest on Y") and an explicit exclusion: 'Use entity_profile instead when you want the static profile...'. This gives clear contextual guidance with a named alternative, going beyond mere implication.

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 having annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description adds valuable behavioral context: key-value pairs are scoped by identifier, authenticated users get persistent memory, and anonymous sessions retain memory for 24 hours. No contradiction exists 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 brief but comprehensive—four sentences covering purpose, usage scenarios, persistence behavior, and sibling tools. Every sentence contributes new information, and the main purpose is front-loaded.

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

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

For a simple 2-parameter tool with full schema and annotations, the description covers all essential aspects: what it saves, when to use it, how data is scoped and persisted, and how it relates to recall and forget. No gaps remain.

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

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

Schema coverage is 100%, so the description is not required to explain parameters in depth. The description reinforces the key-value model and gives examples of valid keys, but it doesn't add syntactic or format details beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Save data the agent will need to reuse later.' It explicitly differentiates from sibling tools by naming 'recall' and 'forget' as complementary operations, making its scope unambiguous.

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

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

The description provides explicit guidance on when to use the tool ('Use when you discover something worth carrying forward') and gives concrete examples (ticker, address, preference). It also names alternatives ('recall' for retrieval, 'forget' for deletion), giving the agent clear decision criteria.

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 readOnly, openWorld, idempotent, and non-destructive behavior, the description adds substantial behavioral context: internal cascading through lookup endpoints, graceful degradation when GLEIF/OpenFIGI are unavailable, ambiguous-result handling via figi_candidates, explicit unresolved identifiers, and source-labelling. This gives the agent accurate expectations beyond what annotations alone convey.

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

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

The description is dense and long, but most content earns its place by covering important edge cases and behavioral nuances. The opening examples and 'Use FIRST' directive front-load the core purpose. Some internal sentences are overflowing with parenthetical detail, but the structure is still navigable and information-rich.

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 and a non-trivial cascading lookup behavior, the description is remarkably complete. It explains supported types, identifier sources, failure modes, ambiguous outcomes, and degradation behavior. An agent has enough context to call the tool correctly and interpret its results in most realistic scenarios.

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 covers both parameters with descriptions, the tool description adds significantly more meaning: accepted input formats for company identifiers, the distinction between issuer and instrument names for bonds, the warning against including trailing security-class words, and the ISIN-to-legal-entity behavior. This materially improves how an agent would populate the value 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 states a specific verb and resource: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It enumerates supported entity types and example phrasings, and clearly distinguishes itself from sibling tools like entity_profile or compare_entities by positioning itself as the identifier-lookup step. This is far beyond a vague or tautological statement.

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

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

The description gives explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains what kinds of names and identifiers are accepted, including edge cases like non-equity instruments. It does not name alternative sibling tools to exclude, but the direct instruction to use FIRST and the detailed supported-type scoping provide strong usage context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds meaningful behavioral context beyond this: it probes each entity with ai_visibility_check, ranks by score, and returns score, confidence, and signal density per entity. This explains the tool's operation without contradicting annotations.

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

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

The description is three sentences, front-loaded with the core purpose, followed by method/return details and a concrete use case. Every sentence earns its place with no redundancy or filler.

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

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

Given 4 parameters, no output schema, and good annotations, the description discloses the return format (ranked list with score, confidence, signal density) and the underlying method. It doesn't mention edge cases like the 2-8 entity limit or API key requirements, but those are covered in the schema. It is sufficiently complete for selection and invocation.

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

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

Schema description coverage is 100%, so baseline is 3. The description reinforces that entities are 'your brand + N competitors' and mentions the ranking behavior, but it does not add new parameter-level semantics beyond what the schema already provides (e.g., models, _apiKey, context).

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

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

The description states a specific verb ('Compare') and resource ('AI visibility across multiple entities side-by-side'), and distinguishes itself from siblings by mentioning it probes with ai_visibility_check, ranks by score, and surfaces most/least recognized. This clearly separates it from single-entity tools like ai_visibility_check and generic comparison tools.

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

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

It gives clear context: 'Useful for competitive AI-marketing audits' and an example question ('does Claude know about us as well as our competitors?'). It implies this is a batch version of ai_visibility_check but does not explicitly state when not to use it or provide direct alternative guidance, so it meets 'clear context, no exclusions'.

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

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

The description adds substantial behavioral context beyond the readOnly/idempotent annotations: it explains partial failure handling ('Partial failures degrade gracefully'), specific latency behavior ('bundlephobia's first measurement on a new version can take 5-30s'), and the fact that 'sources_failed will list it if it times out'. This transparently sets expectations for response behavior and reliability.

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 yet every clause serves a purpose: purpose, usage, return fields, ecosystem scope, and failure behavior are covered in four well-structured sentences. It front-loads the primary action and avoids fluff or repetition of the tool name.

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 explicitly listing the exact fields returned ('summary block', 'per-advisory detail', 'links', 'recent alternative versions') and covering edge cases (ecosystem limitation, timeout behavior). This provides a complete mental model for an agent to invoke and interpret the tool 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 description coverage is 100% — both 'package' and 'version' have descriptions. The description adds the note that scoped packages are accepted and that version defaults to latest, but these facts are already present in the schema. Thus the description does not add significant new meaning beyond the schema, warranting the baseline score.

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: 'Composite 'should I add this npm package to my project' check in ONE call'. It clearly identifies the tool's function—scanning a dependency across two sources (deps.dev and bundlephobia)—and distinguishes it from sibling research/search tools by its focused scope.

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

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

Explicit usage context is provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also states the ecosystem limitation ('NPM ecosystem only in v1') and points to an alternative for other ecosystems ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly'), giving clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description adds substantial behavioral context beyond those: it truncates inputs longer than 200K chars (and flags them), uses BGE-base-en embeddings with cosine over 500-char overlapping windows, and returns character offsets and similarity scores. This is rich behavioral disclosure that helps the agent predict side effects (truncation) and output structure. 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 concise and front-loaded: the first sentence is a clear summary ('Semantic search INSIDE a fetched record'). The remaining sentences each add valuable information (use case, pairing, technical details) without redundancy. It is dense but appropriately sized for the tool's complexity, 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?

The description covers the tool's purpose, when to use it, key behavioral constraints (truncation, windowing, embedding model), and return value characteristics (passages with offsets and scores). Even without an output schema, it tells the agent what to expect. It also situates the tool within a workflow (pairing with ask_pipeworx_grounded), making it complete for practical use.

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

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

The schema already covers 100% of parameters with descriptions, providing a baseline of 3. The description adds value by clarifying that 'text' is the fetched record (e.g., SEC 10-K, article) and explains the output format (character offsets and similarity scores), which reinforces why 'text' and 'query' are needed. It doesn't add syntax details beyond the schema but gives practical examples of what to pass, nudging it above baseline.

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

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

The description opens with 'Semantic search INSIDE a fetched record', which clearly specifies the verb (search), the resource (a fetched record), and the scope (inside that record). It distinguishes itself from sibling tools by explicitly pairing with ask_pipeworx_grounded and emphasizing that it works on text the agent has already pulled, making it clear it's not a general fetch or Q&A tool.

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

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

The description provides explicit when-to-use guidance: 'Use when the record is too big to cram into the prompt' and explains the benefit (saves context, returns only passages that matter). It also names the alternative/paired tool 'ask_pipeworx_grounded' and describes the workflow: fetch with the gateway, then ground over relevant passages. This gives clear direction on when to choose this tool over others.

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: it requires a Pipeworx OAuth account, explains that anonymous/BYO cannot persist subscriptions, notes phone verification and a 10/day SMS cap, and describes the always-on feed. These are concrete behavioral traits not visible in 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 well-organized: purpose in the first sentence, then requirements, then type examples, then delivery channels. Every sentence adds value, and the structure aids scanning. No wasted words.

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

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

Given the complexity (multiple types, delivery channels) and absence of an output schema, the description covers the return value and key constraints. However, it omits the webhook delivery channel entirely and does not mention patent_grant/clinical_trial types, although the schema covers these. It is mostly complete but has minor gaps.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by providing concrete examples (items:["5.02"] = officer change, topic:"fed", series_id:"UNRATE") and clarifying delivery semantics (phone verification, cap). However, it omits patent_grant and clinical_trial types which are in the schema, so it doesn't fully compensate for all parameters.

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream' with a specific verb and resource, and differentiates from sibling tools like list_subscriptions and unsubscribe. It also names supported subscription types, making the purpose unambiguous.

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

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

The description provides clear context for when to use the tool (e.g., to subscribe to alerts) and prerequisites (OAuth account, verified phone for SMS). It does not explicitly name alternatives or exclusions, but the context strongly implies usage, and it even explains how to consume the feed via recent_alerts or GET endpoint.

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 non-destructive. The description adds valuable behavioral context: it returns category-bucketed questions drawn from the live catalog of thousands of tools, and calling without arguments yields a full spread while passing topic focuses results. This goes beyond annotations by describing the dynamic catalog-driven nature and input-dependent output.

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

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

The description is moderately long but front-loaded with example user queries that help with intent recognition. It then efficiently explains returns, parameter usage, and when to use it. It could be more scannable with bullets, but every clause serves a purpose without redundancy.

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

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

Given the tool's simplicity (one optional parameter) and rich annotations, the description covers the essentials: what it returns, the category buckets, the tool+argument mapping, catalog source, and usage guidance. It lacks the exact return data structure, but the absence of an output schema makes this a minor gap rather than a critical omission.

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% (the schema already documents the topic parameter's allowed values and the omit-for-spread behavior). The description merely repeats this with examples like 'finance', 'pharma', 'betting' and adds no new semantic 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 the tool's purpose: it serves as the onboarding entry point that returns category-bucketed example questions with the exact tool + argument shape to answer them. It distinguishes itself from siblings like discover_tools and ask_pipeworx by targeting the 'what can I ask?' use case and explicitly names the meta-tools it teaches you to call.

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

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

The description gives explicit usage context: '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 explains the optional topic parameter's behavior. However, it does not explicitly contrast with alternatives like ask_pipeworx or discover_tools, so it stops short of full when-not guidance.

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

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

Beyond the annotations, the description adds critical behavioral context: ownership is enforced (auth requirement), and the row is deactivated rather than deleted, preserving historical events. This aligns with destructiveHint=false and enriches the annotation data.

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

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

Two concise sentences, front-loaded with the core action. Each sentence adds value without redundancy or irrelevant detail.

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

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

With a single parameter, annotations, and clear side-effect explanation, the description fully covers ownership, deactivation behavior, and historical data preservation. Nothing critical is missing for this simple tool.

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

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

The input schema fully documents the 'id' parameter (100% coverage), so the description doesn't need to add much. The description says 'by id' but doesn't add additional constraints or format details 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 uses a specific verb ('cancel') and resource ('subscription'), clearly stating what the tool does. It distinguishes from sibling tools like subscribe and list_subscriptions by focusing on the cancellation action.

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 operation is unambiguous, and the mention of recent_alerts gives contextual insight, but there is no explicit 'when not to use' or direct comparison with alternatives. Clear enough for an agent to select 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?

Beyond annotations (read-only, idempotent, etc.), the description discloses crucial behavioral details: the tool can return could_not_verify when the check didn't happen, and that verdict carries verification_error; unsupported means no source was found. It also reveals the internal fallback from structured SEC EDGAR to grounded pipeline. This adds significant context about failure modes and interpretation.

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 roughly 200 words but is dense with necessary information. It front-loads with natural-language query examples and ends with the critical caveat about could_not_verify. While a bit long, every sentence contributes either to usage guidance, routing logic, return interpretation, or a distinction from alternatives. The structure is clear: what it does, when to use it, how it works, what it returns, and important pitfalls.

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

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

Given there is no output schema, the description compensates by listing the possible verdicts and explaining the difference between unsupported and could_not_verify, plus the citation format. It also covers the two processing paths and the tolerance behavior. This makes the description self-sufficient for an agent to know when to call the tool and how to interpret the result.

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

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

Although the schema already documents both parameters (claim and tolerance_pct), the description enriches them: it clarifies that tolerance_pct overrides the wording-implied tolerance, recommends 1–2 for hallucination detection, and notes its default cap of 5. This goes beyond the schema's basic property definitions, giving practical guidance for the tolerance 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 clearly identifies the tool as a natural-language claim verification function with a specific verb ('validate') and resource (factual claims). It provides example queries and distinguishes itself from sibling tools by focusing on truth/false checking, and notes it replaces multiple sequential calls. This makes the purpose unambiguous and differentiates it from general-purpose Q&A tools like ask_pipeworx.

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

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

The description explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct,' providing a clear trigger condition. It also outlines the two routing paths (company-financial vs other claims), showing when it applies. It does not explicitly name alternatives or when not to use it, but the instruction is strong enough to guide selection.

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