Fmi

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

Annotations already declare readOnlyHint=true, and the description adds meaningful context beyond this: it notes the default model is free, that passing `_apiKey` triggers direct calls to Anthropic with cost implications for the user, and it discloses the response structure (per-model {score, confidence, signals, raw_response}). This adds transparency about external calls and costs that annotations alone do not provide.

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

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

The description is compact—three sentences—with the main purpose front-loaded. Every sentence contributes new information: what it does, the default model and cost nuance, the return format, and use cases. There is 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?

The description is highly complete for a read-only tool with no output schema. It explains the output shape, default behavior, optional external API usage, cost implications, and real-world use cases. Given the tool's moderate complexity and annotations that cover safety, the description leaves no significant gaps.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the default model (Workers AI Llama-3.3-70b) and the conditional need for `_apiKey` only when probing Anthropic, which is not evident from the schema alone. This clarifies parameter relationships and defaults.

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

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

The description clearly states the tool's function with a specific verb ('probe') and resource ('one or more LLMs'), and explains the visibility scoring (0-100) per model. It also distinguishes from sibling tools by emphasizing per-model visibility scores and specific models like Workers AI and Anthropic, which sets it apart from general ask or research tools.

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

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

The description provides clear context for when to use the tool: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains the default model and optional Anthropic probing with a BYO key, giving practical usage guidance. However, it does not explicitly name alternatives or exclusion criteria when other tools might be more 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?

Annotations already cover read-only/idempotent safety, and the description adds valuable behavioral context: automatic routing to 5,529 tools, argument filling, structured output with stable pipeworx:// citations, and performance ('one fast call'). It also implies a distinction in hallucination-resistance versus ask_pipeworx_grounded, adding nuance without contradicting the annotations.

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

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

The description is longer than average but front-loaded with 'PREFER OVER WEB SEARCH' and every sentence delivers distinct operational value: scope, routing, triggers, examples, default-status, and escalation. Logical flow and no filler, though slightly dense; it earns a 4 rather than 5 due to its length.

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

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

Since there is no output schema, the description compensates by stating the return format ('structured answer with stable pipeworx:// citation URIs'). It covers when to use, examples, tier compatibility, performance, and alternatives comprehensively. Minor vagueness about error behavior and exact output structure, but for such a broad tool it is highly 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?

The schema already documents the sole meaningful parameter 'question' and its five aliases with 100% coverage. The description adds contextual examples and trigger phrases but does not introduce new syntactic constraints or formatting rules, so a 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 identifies the tool's core function: routing factual queries to 5,529 tools across verified sources and returning structured answers with stable citation URIs. It distinguishes itself from siblings by explicitly framing this as the default, fast entry point, while naming ask_pipeworx_grounded and deep_research as specialized 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?

Provides exhaustive usage guidance: 'PREFER OVER WEB SEARCH' for specific domains, trigger phrases like 'what is', 'look up', 'find', and examples. It explicitly says 'START HERE' and gives clear escalation paths ('Step up only when needed...') to ask_pipeworx_grounded and deep_research, even covering breaking-news behavior.

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 provides context beyond the annotations by disclosing that it is a beta with candidate routing improvements, that no candidate is currently active (so it matches ask_pipeworx exactly), and that it is a full working router with no fallback. This transparency helps the agent understand its experimental nature and current 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 slightly longer than necessary but each sentence adds valuable context: beta status, identical functionality, experimental routing, current state, and usage instruction. It is front-loaded with the key purpose and remains reasonably concise given the complexity of the tool.

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 notes that the response shape is identical to ask_pipeworx, which provides adequate context. Combined with rich annotations and full schema coverage, it is complete for a tool of this complexity. A more detailed response example would be nice but is not essential given the sibling reference.

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 covers all six parameters (question plus five aliases) with clear descriptions, so schema description coverage is 100%. The description adds no parameter-level detail, but the schema already sufficiently explains the parameter semantics, making the baseline score of 3 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 identifies the tool as a beta variant of ask_pipeworx with the same universal router functionality, same 5,529 tools, same arguments, and same response shape. It explicitly differentiates itself from the stable ask_pipeworx and ask_pipeworx_grounded siblings by focusing on experimental routing improvements.

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

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

The description gives explicit usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains that results are compared against the stable router, making it clear this is the experimental choice. This effectively distinguishes when to choose this tool over the stable sibling.

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

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

The description richly discloses behavior beyond the annotations: it states the extraction uses ONLY what the tool result contains, enumerates the exact refusal reasons on failure, and describes the success response shape ({answer, evidence, confidence, source, fetched_at, refusal_reason:null}). This goes far beyond the readOnlyHint/idempotentHint annotations, which only indicate safety and repeatability.

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: the core concept is front-loaded, the trade-off vs. the sibling is stated, the return contract is explicit, and the refusal reasons are enumerated. While long, it avoids fluff and is well-structured for an agent to parse quickly.

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

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

Despite having no output schema, the description fully specifies what the tool returns on success and failure, including evidence as a verbatim quote and a list of refusal reason values. It also covers performance/cost context and when not to use it, making it complete for an agent to decide and invoke correctly.

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

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

Schema description coverage is 100% with all six parameters being aliases for the same 'question' field, and the schema already says 'Your question in natural language' and lists aliases. The description adds no additional parameter-level meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly identifies this as a 'hallucination-resistant answer mode' with a specific verb-like purpose (extract grounded answers), and explicitly contrasts it with 'ask_pipeworx' by noting the extra extraction step and high-stakes use case. It also names the resource (Pipeworx) and the mechanism (same routing, tool selection from 5,529 sources), making it distinct from siblings like ask_pipeworx_beta 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?

The description provides explicit 'when to use' guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples (financial verdicts, legal claims, medical lookups). It also gives a direct alternative: 'prefer ask_pipeworx for casual lookups' and notes the cost trade-off (one extra LLM call).

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

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

Annotations already declare read-only, idempotent, non-destructive, but the description goes far beyond by disclosing edge-case behaviors: low-confidence short-circuit, closed-market status, wide-spread illiquidity, cancellation/void rules, and GDELT fallback handling. This adds substantial context beyond annotations without any contradiction.

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

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

The description is long but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY, etc.) and front-loads the core action in the first sentence. Every section adds critical context for a complex tool, though it is not concise in length.

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

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

Despite lacking an output schema, the description extensively enumerates response shapes (result.market, result.analysis, result.evidence), resolver contract fields, parent_event extraction, news fallback fields, and blocking statuses. It covers inputs, safety, and edge cases comprehensively, leaving little unspecified.

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 with descriptions and enums, so baseline is 3. The description adds value with examples of slug/URL/question input, explains depth and include_raw tradeoffs, and ties fan-out examples to classifier choices. This enriches parameter understanding beyond the schema alone.

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

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

The description clearly states it researches a Polymarket bet by pulling Pipeworx data in one call. It distinguishes itself with specific use cases ('should I bet on X', 'what does the data say about Y') and lists classification categories. This makes it easy to differentiate from sibling tools focused on edges or arbitrage.

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

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

Explicitly provides usage guidance with 'Use for' and three example query patterns. It also gives fan-out examples for different bet types, clarifying when certain classifiers apply. However, it does not explicitly name alternative tools or exclusion cases, which prevents 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?

Annotations already declare the tool read-only, open-world, idempotent, and non-destructive. The description adds valuable behavioral context beyond these: it uses a parallel call pattern, handles off-calendar fiscal years correctly, sorts results by primary metric, and returns paired data with citation URIs. 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 dense but well-organized: trigger phrases lead, followed by core value proposition, then type-specific details, and finally output format. Every sentence adds operational information with no filler, making it appropriately sized for the tool's complexity.

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

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

Despite no output schema, the description covers inputs (types, value formats), outputs (paired data, citation URIs, sorted by primary metric), edge cases (off-calendar fiscal years), and usage context (parallel vs sequential). For a tool with 2 parameters and two distinct modes, this is fully complete.

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

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

While the schema covers 100% of parameters, the description significantly enriches their meaning. It explains that type='company' pulls 10-K financials (revenue, net income, cash, long-term debt) from SEC EDGAR/XBRL, while type='drug' pulls FAERS adverse-event counts, FDA approval counts, and trial counts. It also clarifies value formats (tickers/CIKs vs drug names) and the sorting behavior tied to the primary metric.

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: side-by-side comparison of 2–5 companies or drugs in a single parallel call. It distinguishes itself from siblings by explicitly noting it should be preferred over sequential single-pack lookups, and includes trigger phrases ("X vs Y", "which is bigger") that make intent unmistakable.

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

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

The description provides explicit when-to-use guidance with trigger phrase examples and a direct statement to prefer this tool over sequential lookups. It also details type-specific usage (company vs drug) and data sources, giving the agent clear context for when each variant 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?

Although annotations already declare readOnly/openWorld/idempotent hints, the description adds substantial behavioral context beyond them: account and paid-plan requirements, explicit gaps[] output conventions with never-invented guarantee, citation_uri availability conditions, contradictions[] scanning for deeper depths, semantic excerpting of large records, and latency expectations. These disclosures substantially aid an agent in predicting tool 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 a single dense paragraph rather than structured text, but it is information-dense and front-loaded with the most critical operational facts (account requirement and alternative tools). While not concise, every sentence contributes meaningful detail about capabilities, limitations, output format, and performance, so the length is justified.

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

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

For a complex tool with no output schema, the description thoroughly covers prerequisites (account, paid tier), workflow, output contents (findings packet, gaps[], contradictions[], citations), edge cases (unanswerable topics, breaking news), and performance expectations. This gives an agent everything needed to correctly select and invoke the tool.

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

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

Schema coverage is 100%: both `question` and `depth` have detailed descriptions in the input schema, including the meaning and defaults for each depth level. The tool description reinforces these points but does not add significant new parameter-level semantics beyond what the schema already provides, 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 explicitly states it performs 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' by decomposing questions into facets and routing them to tools in parallel. It clearly distinguishes itself from ask_pipeworx and open-web search, making the tool's scope and resources unmistakable.

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

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

The description provides explicit usage guidance: 'Best for broad/multi-part questions over structured data', and gives clear alternatives: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', and 'If you are not signed in, use ask_pipeworx instead'. This is a model example of when-to-use vs alternative guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds valuable behavior: returns top-N tools with full schemas and curated examples, ready to call directly with no second lookup. No contradiction with annotations; this is meaningful additional 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, front-loaded with the core purpose, efficient domain list, and key return-value detail. No fluff; 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?

Despite no output schema, the description specifies exactly what is returned (names, descriptions, schemas, examples) and instructs on when to call it first. Covers return format and usage context sufficiently for a discovery tool.

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

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

Schema coverage is 100% with clear parameter descriptions. The description adds nuance by explaining the query as a natural language description ('describing the data or task'), mentioning the top-N return behavior tied to limit, and providing concrete domain examples that align with query usage.

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+resource structure ('Find tools by describing the data or task') and clearly differentiates from siblings by positioning itself as the discovery/meta-tool, with a concrete list of covered domains (SEC filings, FDA drugs, FRED, etc.).

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

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

Provides explicit when-to-use guidance ('Use when you need to browse, search, look up, or discover what tools exist') and a strong directive to 'Call this FIRST when you have many tools available.' It also implies not for single-answer tasks ('not just one answer'), though it does not name specific alternative tools.

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

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

Annotations already declare readOnly=true, idempotent=true, and destructive=false. The description adds valuable behavioral details: it fans out to multiple APIs in parallel, returns specific fields (cik, recent_filings, fundamentals, patents, news, LEI), and even discloses failure modes like "USPTO PatentsView API sunset May 2025 — soft-fails until reactivated" and the GDELT→GNews fallback chain. 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 longer than average but each sentence adds value. It is front-loaded with example invocations and the core purpose, then logically lists return components and input constraints. It could be trimmed slightly without losing key details, but the density is justified for the tool's multi-source complexity.

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

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

Despite having no output schema, the description thoroughly explains the return structure (cik+company_name, recent_filings with URIs, fundamentals sorted by period_end, patents with soft-fail note, news fallback, LEI). It also covers input constraints and alternatives. Given the tool's complexity across multiple data sources, this description provides sufficient context for an agent to invoke it correctly.

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

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

Input schema coverage is 100% — both 'type' and 'value' have descriptions and enums. The description adds little beyond the schema: it repeats the same ticker/CIK examples and the "names not supported" note. No meaningful new parameter-level detail is provided, so the baseline of 3 holds.

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 concrete example queries ("Tell me about X", "research Acme") and states the core function: "full cross-source profile of a US public company in ONE parallel call." It clearly distinguishes itself from sibling tools that do single-source lookups by stating "ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups."

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

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

Explicit guidance is provided: use this tool when a holistic view is needed, and explicitly points to an alternative for unsupported inputs: "names not supported (use resolve_entity first if you only have a name)." It also notes the tool fans out across multiple sources, making the intended use case unambiguous.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds context about the HARMONIE model and the 60-hour forecast horizon, which is useful but minimal. It does not disclose potential model update delays or output specifics, but given the annotations, this is acceptable.

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 13-word sentence that front-loads the key information (multi-hour, model, location, horizon). It contains no redundant words or filler, and every phrase earns its place.

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

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

For a straightforward read-only weather forecast tool with a rich input schema and an output schema, the description covers essential purpose and scope. It could mention units or timezone, but those are likely handled by the schema/output schema. The lack of explicit sibling contrast is a minor gap, but the tool is simple enough that the description is nearly 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?

The input schema has 100% coverage with descriptions for place, timestep, and parameters, so the description adds no new parameter-level information. It mentions 'place name in Finland' but the schema already explains the place parameter with examples. Thus, the baseline score of 3 applies as the description neither enhances nor harms 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 provides a 'Multi-hour HARMONIE forecast' for a place in Finland, specifying the model, geographic scope, and time horizon. This distinctively separates it from observational sibling tools like 'latest_observations' and 'recent_observations' by focusing on future prediction rather than current or past 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 gives a clear context for use: it is a forecast for Finland, so an agent would invoke it when future weather data is needed. It does not explicitly mention alternatives or exclusions, but the 'forecast' wording implicitly contrasts with observation tools. This satisfies 'clear context' though it lacks explicit when-not guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, covering the safety profile. The description adds context about when deletion is appropriate but does not describe edge cases like non-existent keys or irreversibility, which is acceptable given 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?

Two concise sentences front-load the primary action and follow with usage guidance. No wasted words; all sentences earn their place.

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

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

For a simple one-parameter delete tool with strong annotations and no output schema, the description covers purpose, usage, and related tools, making it fully complete for an agent to invoke correctly.

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

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

Schema description coverage is 100% with the parameter 'key' described as 'Memory key to delete'. The description repeats this concept without adding new syntax or format details, so baseline 3 is appropriate.

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

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

The description states a specific action ('Delete a previously stored memory by key') with a clear resource and method, distinguishing it from sibling tools like remember and recall.

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 conditions for use (stale context, task done, clearing sensitive data) and references complementary tools (remember, recall), but does not explicitly say when not to use it or name alternative tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds behavioral detail: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format' and notes the output is 'a single text blob'. This goes beyond the annotations by disclosing the process and return format, with no contradiction.

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

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

The description is four sentences long, all of which are informative. It front-loads the main action, then covers process, output, and use cases. There is no redundant fluff, making it appropriately concise and well-structured.

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

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

For a tool with only 2 parameters and no output schema, the description covers the essential purpose, process, output format, and use cases. It does not address edge cases (e.g., JavaScript-rendered sites), but given the simple parameters and rich annotations, it is sufficiently complete for an agent to use effectively.

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

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

Schema coverage is 100% with descriptive definitions for both 'url' and 'max_links'. The description mentions 'key links' which loosely relates to max_links, but it does not add meaningful detail beyond the schema. The baseline of 3 is appropriate since the schema already carries the parameter semantics.

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

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

The description clearly states a specific verb+resource: 'Generate a production-ready llms.txt file for any URL'. It also outlines the transformation process (fetch, extract, emit). However, it does not explicitly differentiate from sibling tools like scan_competitor_ai_presence, so it falls short of a 5.

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

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

The description gives concrete use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'. This provides clear context on when to use the tool, but it does not explicitly state when not to use it or mention alternative tools, preventing 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, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds context that the data comes from a real-time feed, which implies values are dynamic and may change between calls. It consistently describes a read-only operation, with no contradictions.

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

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

The description is a single sentence that front-loads the core action and value ('Returns the single most-recent observed value'), then adds essential context (location, source). No redundant or filler words; every clause 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 an output schema present, return values need not be explained. The description covers purpose, place scope, parameter examples, and data source. It omits details like unit conventions or exact parameter string formatting, but the schema examples partially address this. Overall complete for a simple read tool.

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

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

Schema description coverage is 0%, so the description must compensate. It provides meaning for 'place' (a named place in Finland) and gives examples of parameter values ('temperature, humidity, wind speed'). However, it does not explain the exact format of the 'parameters' string (e.g., comma-separated) or behavior when omitted, leaving some ambiguity.

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 ('Returns'), a clear resource ('single most-recent observed value per weather parameter'), and a specific scope ('for a named place in Finland'). It also names the data source (FMI WFS real-time observation feed), which distinguishes it from siblings like 'forecast' or 'recent_observations'.

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 the use case: retrieve the latest real-time observation for a place. However, it does not explicitly contrast with alternatives (e.g., 'recent_observations' for historical recent data, or 'forecast' for predicted values). No explicit when-not-to-use guidance is provided.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds useful behavioral context: it returns specific fields, only includes active subscriptions by default (with an option to include inactive ones), and is scoped to the caller. This goes beyond what annotations provide.

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

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

The description is two concise sentences: the first states the primary purpose, the second lists return fields and gives two clear use cases. Every sentence earns its place, with no fluff 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?

This is a simple tool with one optional boolean parameter and no output schema. The description covers the purpose, return fields, and typical usage scenarios. Annotations handle safety. The description is complete for the tool's complexity.

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

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

Schema description coverage is 100%, so the schema fully documents 'include_inactive'. The description doesn't add additional parameter semantics beyond the schema, but the baseline of 3 is appropriate since the schema handles it completely.

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

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

The description clearly states the action ('List the caller's active subscriptions') with a specific verb and resource, and lists the exact fields returned. It distinguishes itself from sibling tools like subscribe/unsubscribe by focusing on review and retrieval.

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

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

The description explicitly tells the agent when to use this tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This provides clear context and practical guidance, effectively differentiating it from subscribe/unsubscribe.

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 the claim_token flow, daily digest read cycle, rate limit, and that feedback is free. These are meaningful behavioral traits beyond the annotations (which are all false) and 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?

It's a fairly long description, but each sentence carries operational value: purpose, use cases, exclusions, token mechanics, rate limits, and cost. The structure is logical and front-loaded with the core purpose.

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

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

For a feedback-submission tool with no output schema, the description explains the return token, how to check resolution, and the cadence of processing. There's no ambiguous behavior left unaddressed.

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

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

Schema covers all 4 params at 100%, so baseline is 3. The description adds practical guidance like 'don't paste the end-user's prompt' and clarifies how to use claim_token to retrieve resolution status, elevating it slightly.

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

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

The description opens with a clear verb ('Tell') and resource ('Pipeworx team'), and explicitly lists the four feedback categories (bug, feature/data_gap, praise). This distinguishes it from sibling research/visibility 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 provides explicit when-to-use scenarios (wrong/stale data, missing tool, praise) and an explicit when-not-to-use rule (feedback about other MCP servers). It even names the alternative action ('file it with that server instead').

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

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

Annotations already mark this read-only, idempotent, open-world, and non-destructive. Description adds valuable behavioral context: it is self-aggregating, sourced from CF analytics-engine, excludes PII, contains only (pack, tool, count), and is cached 5min-1h by window. This far exceeds the annotation baseline.

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

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

Three tightly packed sentences front-load the core purpose, then the colon-list of use cases and a final data-privacy note. Every sentence adds distinct value with no filler, making it easy to scan.

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 one optional parameter, rich annotations, and a description that states the exact returned shape (top tools, top packs, total call volume, (pack, tool, count)), the agent has sufficient information to invoke and interpret results. No output schema exists but return semantics are already described, and caching behavior covers freshness expectations.

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?

Input schema covers 100% of the single optional parameter with enum values and a description of hot vs steady-state windows, so baseline is 3. Tool description only reinforces the same window choices and adds a vague cache duration dependency, providing little additional parameter meaning beyond the schema.

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

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

Description opens with 'What other AI agents are calling on Pipeworx right now' and states exact outputs (top tools, top packs, total call volume). This clearly distinguishes from sibling discovery tools by focusing on aggregated cross-agent usage trends rather than individual recommendations. Specific verb 'Returns' plus resource scope merits 5.

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

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

Lists three concrete use cases: finding hot data sources, confirming canonical tool choices, and checking alignment with other agents' needs. This gives clear context for when to call, but does not explicitly name alternatives or exclusion criteria, so 4 rather than 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 declare readOnly/openWorld/idempotent/non-destructive, and the description adds substantial behavioral detail beyond that: Jaccard similarity threshold (≥0.30), placeholder filter (>20% returns null), deviation >3pp for signal emission, and the fill-check against live CLOB depth. 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 well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded purpose. Every sentence carries useful information, though slightly verbose; a light trim could improve readability 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?

This is a complex tool with no output schema, and the description compensates by outlining response fields (opportunities[], partition_check), fill-check semantics, and edge cases like skipped_low_similarity and placeholders_filtered. It gives an agent everything needed to select and invoke correctly.

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

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

Schema already has 100% coverage, but the description enriches both parameters with concrete examples ('fed-decision-may-2026'), mode semantics, and cross-event behavior. It clarifies that calling with no args triggers the trending scan, which is not in the schema.

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

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

The description opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes from siblings by naming the methodology and explicitly pointing to polymarket_fill_risk for custom sizing, leaving no ambiguity about its unique role.

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 across three modes: no args for trending_scan, `event` for per-event partition checks, and `topic` for cross-event scans. It also names the alternative tool for custom sizing and warns against trading when realizable_edge_pp ≤ 0.

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 though annotations already declare readOnlyHint=true and destructiveHint=false, the description adds substantial behavioral context: the cache behavior ('Cached 1h at the KV level keyed on all knobs'), response diagnostics (_diagnostics so callers can see WHY a segment is empty), per-model details (placeholder-slug filter, per-sport bias correction α), and valuation cautions (the 24h-move warning, Fed note about unreliable signal). It also explains the 'rare-by-design' nature of concentrated longshots. 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 well-structured, using capital-label sections (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL) that aid navigation. It is front-loaded with the core purpose. While every sentence carries substantive information, the length is high; however, given the tool's complexity (9 optional parameters, 4 model variants, nested response structure), the detail is justified rather than padded.

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

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

With no output schema, the description carries the full burden of explaining the return structure, and it does so thoroughly: top-level keys (by_segment, fed_candidates/fed_note, _diagnostics), per-opportunity fields (edge_pp_net, kelly_fraction, market.liquidity, market.spread_pp), and even the funnel counters in diagnostics for empty segments. It covers model logic, filters, knobs, and caching, making it fully adequate for an agent to understand what it will receive and why.

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, but the description significantly enriches parameter meaning. It labels min_liquidity and max_spread_pp as 'tradeable-edge filters', explains that min_partition_leg_kelly applies to per-leg Kelly inside top_legs because 'partition arbs always return kelly_fraction_half=0 at the parent level by design', and gives practical tuning advice (e.g., 'Bump for very thin partitions; drop to 0 if you have a smarter fill model'). These details go far beyond generic schema descriptions, clarifying parameter intent and interactions.

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

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

The description opens with a clear, specific verb-resource pair: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It names the exact resource (Polymarket markets), the action (scan and return opportunities), and the core purpose (finding mispricings against Pipeworx data). It also explicitly frames the use case ('what should I bet on today'), distinguishing it from siblings like polymarket_arbitrage or polymarket_edge_tracker.

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

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

The description provides clear usage context: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It explains the intended scenario and the value proposition. However, it does not explicitly name alternative tools for exclusion (e.g., 'for tracking edge over time use polymarket_edge_tracker') or mention when not to use this tool, 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 description adds substantial behavioral context beyond the annotations: it explains the 60-day snapshot TTL, that decay numbers are from daily closes not intraday, that snapshot gaps mean no scan occurred, and details how 'expired' opportunities are defined. This goes far beyond the readOnlyHint and other annotations, which only say it is safe and idempotent.

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

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

The description is front-loaded with the purpose and uses structured labels (Args, RESPONSE, LIMITS) to organize dense information. Every sentence contributes necessary detail for a tool with no output schema. Despite length, there is no fluff 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?

With no output schema, the description fully explains the return structure: tracked[], expired[], snapshot_dates[], and their semantics. It also covers edge cases like TTL limits, cache-miss gaps, and signed edge values. For a tool of this complexity, this is complete and self-sufficient.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds the concept of 'snapshot family' and restates defaults, but does not meaningfully enrich the parameter semantics beyond what the schema already provides. It mentions 'max 30' while schema says 'clamp 2-30', which is equivalent.

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

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

The description clearly states this tool provides 'edge persistence and decay telemetry' and answers whether an edge is 'shrinking'. This distinguishes it from the sibling polymarket_edges, which likely provides current edge data. The verb 'tracker' and resource 'polymarket_edges snapshots' are explicit and specific.

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 this tool by contrasting a 'fresh wide edge' vs a '3-week-old wide edge', implying it is for historical persistence analysis. It references polymarket_edges snapshots, indicating that tool is the source for current edges. However, it does not explicitly name alternatives or state 'when not to use', so a 4 rather than 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 provide readOnlyHint, idempotentHint, non-destructive. The description adds significant behavioral context beyond that: it walks the order-book ladder, returns specific metrics (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict), and highlights the risk of partial basket fills creating unhedged directional positions. No contradictions with annotations.

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

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

The description is long but structured with clear sections for single-market vs basket mode, each with input/output details. It front-loads the purpose and then provides essential usage context. Every sentence carries useful information, and the length is justified by the tool's complexity.

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

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

With 4 params (100% schema coverage), no output schema, and no nested objects, the description is remarkably complete. It covers all modes, input requirements, output fields, interpretation of size_usd, risk factors, and direct usage guidance. It is sufficient for an agent to invoke the tool correctly without further clarification.

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

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

Schema coverage is 100%, so baseline is 3. However, the description enriches parameter meaning substantially: it explains the market vs event mode distinction, how size_usd is interpreted differently in single-market vs basket mode (max spend/target proceeds vs settlement notional), and default side behavior. This goes well beyond the schema descriptions.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes this tool from siblings by explicitly stating it should be used before acting on polymarket_arbitrage or polymarket_edges signals, naming the exact alternative tools.

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

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

The description provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why alternative tools are insufficient and why this check is necessary, covering both context and 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 provides extensive behavioral context beyond the readOnlyHint and other annotations. It details the response structure, safety fields (compatibility_warning, temporal_alignment), skipped_cross_type/subtype counters, and edge cases like non-equivalent bet shapes or mismatched months. The caveat that 'pre-mapped ≠ tradeable' adds valuable real-world behavioral insight. 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 well-structured with clear section markers (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence adds value, covering functionality, safety, and limitations. It is front-loaded with the core purpose and then dives into details. Slightly verbose but appropriate for the tool's complexity.

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

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

The description is comprehensive for a tool with no output schema. It explains the response fields (leg-by-leg prices, spread[], compatibility_warning, temporal_alignment) and covers edge cases. It also addresses the tool's limitations, making it complete for an agent to understand what the tool returns and when to trust 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?

While the schema already describes each parameter, the description enriches their semantics by explaining the two modes: how `topic` maps to predefined shortcuts, and how `kalshi_event_ticker` and `polymarket_event_slug` override the mapped sides. It provides concrete examples for each parameter and clarifies the interplay between them, which is not evident from the schema alone.

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

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

The description clearly states the tool's purpose: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It uses a specific verb and resource, and distinguishes itself from siblings by focusing on cross-venue comparison. The two modes (topic and explicit) are clearly outlined, making the tool's scope unambiguous.

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

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

The description explains when to use the tool (for cross-venue spread analysis) and warns about pitfalls: 'Real cross-venue spreads are rarer than the macro-shortcut list suggests' and the safety fields indicate when the output is not meaningful. It does not explicitly name alternative tools, but it implicitly differentiates by describing the specific scenario. The guidance is strong but lacks direct sibling comparison.

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 safety (readOnly, idempotent, non-destructive). The description adds valuable behavioral context: memory is scoped to an identifier (anonymous IP, BYO key hash, or account ID) and that omitting the key lists all saved keys. This goes beyond the structured annotations, though it doesn't describe edge cases like key-not-found 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 three sentences, front-loaded with the core action. Each sentence contributes: function, use case, and scoping/companion tools. No fluff 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 tool with one optional parameter, strong annotations, and no output schema, the description provides complete contextual information: purpose, usage, scoping, and relationships to save/delete tools. Nothing critical 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% for the single 'key' parameter, so the baseline is 3. The description adds meaning by explaining the dual behavior: retrieving a specific key vs. listing all keys when omitted, which enriches the schema's brief 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 states a specific verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys.' This clearly distinguishes it from sibling tools like remember and forget, and the context of looking up stored agent information is explicit.

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

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

The description provides explicit usage context: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also names alternatives and companions: 'Pair with remember to save, forget to delete,' which clarifies when to use this tool versus related memory operations.

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 valuable context by disclosing the mark_read side effect that affects subsequent calls, the return payload shape, and the availability of the same feed via a separate endpoint. 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 (three sentences) yet covers purpose, return contents, filtering, mark_read behavior, and alternative access. It is front-loaded with the core purpose and every sentence carries information, with no wasted words.

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

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

For a tool with 5 parameters and no output schema, the description adequately explains what the tool returns, how to filter, the read-tracking behavior, and alternative access. The schema covers the remaining parameter details, making the description sufficiently complete for an agent.

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

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

Schema coverage is 100%, so each parameter is already described. The description augments this by providing a concrete type example ('sec_8k'), clarifying 'since' as an ISO timestamp, and explaining the practical effect of mark_read on future calls. This adds meaning beyond the schema.

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

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

The description clearly states the tool's function with a specific verb ('Pull fired events from your subscription feed') and identifies the unique resource (alerts in the persisted feed). It distinguishes from siblings by specifying 'alerts' and detailing the return payload (source, citation_uri, raw event payload).

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 (to retrieve fired alerts from the subscription feed) and notes that polling works fine. It mentions an alternative access method via a GET URL for scripts/dashboards, which is helpful, but it does not explicitly compare to sibling tools or state 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?

Despite having rich annotations (readOnlyHint, openWorldHint, idempotentHint), the description goes further by disclosing the multi-source fan-out (SEC, GDELT→GNews fallback, USPTO), the specific fallback trigger (rate-limited or 5xx), and the soft-failure due to PatentsView API sunset. It also details the return structure, which is not in an output schema.

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 despite covering many details. It is front-loaded with natural language query examples, then a concise one-sentence summary, followed by source breakdown and parameter/return details. Every sentence adds value, 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?

For a complex tool with no output schema, the description fully covers input formats, data sources, fallback behavior, return shape (changes[] grouped by source, total_changes, citation URIs), and an explicit alternative. It is complete for the AI agent to decide when and how to invoke 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?

Schema coverage is 100% with each parameter already described. The description reiterates the same formats for 'since' and examples for 'value' without adding new semantic meaning. It provides no additional parameter-specific context beyond what the schema already offers.

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

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

The description clearly defines the tool as a 'change feed for a company in the last N days/weeks/months' with a specific verb and resource. It is explicitly distinguished from sibling entity_profile, and the accompanying query examples make its purpose unambiguous.

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

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

The description explicitly states when to use this tool (for 'what's new', 'latest', 'updates' queries) and provides a direct alternative: 'Use entity_profile instead when you want the static profile...'. It also gives practical guidance like using '30d' or '1m' for typical monitoring.

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 read-only, non-destructive, idempotent, and open-world. The description adds behavioral details beyond the annotations: the exact time range, default value, and the row-level structure of the response (including lat/lon, parameter, and value). It stops short of discussing rate limits or pagination, but the added context is valuable.

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, information-dense sentence that is front-loaded with the core action and resource. Every clause adds meaningful detail (time window, default, output format, geographic scope), 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 the tool's simplicity, the output schema, and the annotations, the description covers the essential information needed for selection and invocation: what it returns, for what place, over what time range, and the response structure. It could be slightly more complete by explicitly describing the 'parameters' argument format or noting an alternative like 'latest_observations', but the existing description is sufficient for most use cases.

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

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

Schema description coverage is low (33%—only 'hours' is described). The description compensates by clarifying that 'place' refers to a named place in Finland and by mentioning parameter names in the output, which implies the 'parameters' argument filters which parameters to include. However, it does not explicitly state the format for 'parameters' (e.g., comma-separated), leaving that to be inferred from examples.

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

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

The description uses the specific verb 'Returns', identifies the resource as 'time-series weather observations', and scopes it to 'a named place in Finland' with a time window (1–48 hours, default 6h) and output format (one row per parameter per timestamp, including lat/lon, parameter name, and value). This clearly differentiates it from siblings like 'latest_observations' and 'forecast'.

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 establishes the intended use case: retrieving recent weather observations over a configurable historical window for a Finnish place. It does not explicitly mention alternatives or exclusions, but the context is clear enough for an agent to select it over a single-observation tool or forecast tool.

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

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

The description adds valuable behavioral context beyond annotations: key-value pair scoped by identifier, persistent memory for authenticated users, and 24-hour retention for anonymous sessions. This complements the annotations (readOnlyHint=false, idempotentHint=true) and does not contradict 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, with three sentences that front-load the main action, then add usage examples, behavioral details, and lifecycle guidance. Every sentence earns its place with no redundant information.

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

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

For a simple two-parameter tool with annotations and no output schema, the description is complete. It covers purpose, when to use, persistence behavior, scoping, and relationship to sibling tools. No critical gaps remain for the agent to invoke it correctly.

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

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

The input schema already provides 100% coverage with detailed descriptions for both key and value, including examples. The description only mentions 'key-value pair' without adding further parameter-specific meaning, 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 states a specific verb and resource: 'Save data the agent will need to reuse later.' It clearly defines the tool's scope across conversation and sessions, and distinguishes it from siblings by explicitly naming recall and forget as companion 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?

Provides explicit 'Use when' guidance with concrete examples (resolved ticker, target address, user preference, research subject). It also tells the agent to pair with recall for retrieval and forget for deletion, offering clear context on when to use this tool versus alternatives.

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

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

Annotations already convey read-only, idempotent, non-destructive safety. The description adds rich behavioral details beyond that: unresolved identifiers are explicitly listed under 'unresolved' rather than omitted, identifiers are source-labeled, and LEI/FIGI enrichment degrades gracefully if GLEIF or OpenFIGI is unavailable. 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 longer than typical but every sentence carries useful information—examples, supported types, fallback behavior, and source labeling. It is front-loaded with query examples and usage guidance. Slightly verbose but not bloated.

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

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

Given the tool's complexity (multiple entity types, multiple identifier sources, no output schema), the description thoroughly covers what will be returned for each type, how sources are labeled, what happens when resolution fails, and graceful degradation. This is complete enough for an agent to use the tool correctly.

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

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

Even though schema description coverage is 100%, the description adds significant meaning via concrete examples (ticker AAPL, CIK 0000320193, drug names like 'ozempic') and explains the semantics of each type, including what identifiers will be returned for each. This goes well beyond the schema's basic parameter descriptions.

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

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

The description clearly states the tool's purpose: resolving user-spoken names to canonical IDs required by other tools. It lists supported types (company, drug) and specific identifier outputs (CIK, LEI, FIGI, RxCUI), and distinguishes itself from siblings by emphasizing 'identifiers other tools require as input' and 'Use FIRST whenever you have a name but need an ID.'

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: 'Use FIRST whenever you have a name but need an ID' and 'using resolve_entity replaces 2-3 manual lookups.' This tells the agent exactly when to invoke this tool and highlights its efficiency compared to doing multiple 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?

The description adds operational detail beyond the annotations: it states it probes each entity with ai_visibility_check, ranks results, and treats the first entity as the 'subject' for narrative. The annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the added behavior around how the tool orchestrates sub-probes is valuable.

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

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

Three sentences, front-loaded with the core purpose, then a use-case, then a return-value summary. No filler or redundant restatement of the schema; 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?

Despite no output schema, the description specifies the return: 'ranked list with score, confidence, signal density per entity'. It also explains the internal call to ai_visibility_check, which clarifies behavior and dependencies. Given the tool's moderate complexity, this is complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds nuance by clarifying the first entity is treated as the 'subject' and the rest are competitors—this is beyond the schema, which only states 'First entry treated as the "subject" for narrative; rest are competitors' (actually appears in both, but the description additionally gives the default for 'models' via 'Omit for just workers-ai'). That enriches 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 it 'Compare AI visibility across multiple entities side-by-side', with specific actions: probes each entity with ai_visibility_check, ranks by score, and surfaces most/least recognized. This distinguishes it from the sibling ai_visibility_check (which likely handles single entities) and compare_entities by focusing on AI visibility specifically.

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 identifies the use case: 'Useful for competitive AI-marketing audits' with an example query. It does not explicitly mention exclusions or alternatives, but the context is clear enough that an agent would know when to reach for it over simpler single-entity tools.

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

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

Annotations already declare the operation as read-only, idempotent, and non-destructive. The description adds valuable behavioral context beyond this: partial failures degrade gracefully, the first bundlephobia measurement can take 5-30s, and sources_failed will list timeouts while still returning other data. This is exactly the kind of disclosure that helps an agent anticipate real-world 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 longer than minimal, but every sentence adds meaningful information: purpose, use case, return payload, ecosystem scope, and failure handling. It is front-loaded with the main purpose and organized logically, though slightly verbose.

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

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

Without an output schema, the description must convey return values and runtime behavior, and it does. It enumerates the summary block fields, per-advisory details, links, and alternative version list. It also covers latency, partial failure, and scope limitations, making it complete for a tool of this complexity.

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

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

The schema covers both parameters with descriptions (package name, scoped packages accepted; version defaults to latest), providing 100% coverage. The description adds no new parameter-level semantics beyond restating the package concept and the version default, so it does not elevate beyond the baseline.

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

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

The description clearly identifies the tool as a composite 'should I add this npm package' check that fans out across deps.dev and bundlephobia. It specifies a concrete purpose (evaluating package safety, size, and cost) and distinguishes it from sibling tools by its npm-specific scope and aggregated multi-source output.

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: whenever an agent asks if a package is safe, popular, or small, or what adding it costs. It also provides an exclusion criterion, noting that non-npm ecosystems (PyPI, Maven, etc.) should use deps.dev:version directly, which effectively names the alternative.

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?

Goes well beyond annotations by disclosing return format (top-N passages with character offsets and similarity scores), technical implementation (BGE-base-en embeddings, cosine, 500-char overlapping windows), and input limits (200K chars with truncation and flagging). This rich behavioral detail helps agents anticipate edge cases and interpret results, without contradicting the readOnly/idempotent annotations.

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

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

The description is front-loaded with the core action in the first sentence, then each subsequent sentence adds a distinct piece of information: use case, output details, workflow pairing, and technical limits. No filler or repetition; 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?

Despite having no output schema, the description explains what the tool returns (passages with offsets and scores). Combined with thorough annotations (read-only, idempotent, non-destructive) and a fully documented schema, it covers the tool's complexity, limitations, and typical use context comprehensively. The description alone would be sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% with detailed parameter descriptions, so the baseline is 3. The description adds helpful examples for the text parameter (SEC 10-K, article, long tool result) and re-emphasizes that the query is natural-language, but it does not introduce significant new semantic meaning beyond the schema. The truncation note is a behavioral trait rather than parameter semantics.

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

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

Description opens with a specific verb-resource pairing: 'Semantic search INSIDE a fetched record', clearly distinguishing it from general search tools. It explicitly contrasts with ask_pipeworx_grounded by explaining that search_within operates on already-fetched text and returns passages, making the tool's role unambiguous.

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

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

Provides explicit when-to-use guidance: 'Use when the record is too big to cram into the prompt — search_within saves context'. It also names a sibling tool (ask_pipeworx_grounded) and describes a complementary workflow, giving agents clear direction on how this tool fits into a larger process.

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 non-read-only and idempotent behavior. The description adds meaningful context beyond annotations: OAuth persistence requirement, always-on feed with pull methods, phone verification, SMS cap, and type-specific semantics. 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 front-loaded with the primary action and return value, then moves through auth, types, and delivery. It is dense but every sentence carries useful information; no fluff or repetition. The long run-on structure is a minor organizational weakness.

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 core behavior, auth, return id, and delivery options, but its 'Supported types' list omits patent_grant and clinical_trial, and the main description does not mention webhook delivery (schema covers it). Since there is no output schema, the brief return-value note is acceptable but could be richer. These gaps make it incomplete despite strong overall clarity.

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 description goes beyond the schema by providing concrete parameter examples: items:['5.02'] = officer change, topic:'fed', series_id:'UNRATE', and delivery channel examples. Even though schema coverage is 100%, these examples add real-world meaning and constraints (e.g., phone verification, 10/day cap).

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

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

The description opens with a specific action: 'Create a proactive monitoring subscription to a live-data event stream' and states the return value ('Returns the new subscription id'). This clearly distinguishes subscribe from sibling tools like list_subscriptions and unsubscribe.

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

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

It provides clear usage context: requires a Pipeworx OAuth account, lists supported subscription types with concrete examples, and explains delivery channels including the always-on feed and optional email/SMS. It does not explicitly call out when to use alternatives, but the context is specific enough for tool selection.

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

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

Annotations already provide safety traits (readOnly, non-destructive, idempotent). The description adds valuable behavioral context: it returns category-bucketed example questions, each with the exact tool and argument shape, drawn from the live catalog of thousands of tools. This goes beyond annotations by describing the output structure and dynamic nature, without contradicting the annotations.

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

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

The description is appropriately detailed and front-loaded, starting with example queries and then the core purpose. It's a bit long but every sentence adds value, including the return format and customization options. The list of categories mirrors the schema but is still useful for quick scanning.

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 values, and it does: category-bucketed example questions with tool and argument shapes. It also covers use cases, the topic parameter, and the dynamic nature of the catalog. It is complete enough for an agent to understand when and how to invoke 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 schema already provides 100% coverage for the single 'topic' parameter, listing all valid values. The description merely repeats examples ('finance', 'pharma', 'betting') without adding new information. The baseline is 3 for high schema coverage, and the description does not 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 identifies the tool as an onboarding entry point that returns category-bucketed example questions with the exact tool and argument shape to answer them. This specific verb+resource structure distinguishes it from sibling tools like ask_pipeworx or discover_tools, and it explicitly states what it does and how it's different.

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

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

The description explicitly tells the agent to use this tool FIRST when it doesn't know what Pipeworx can do, and it names meta-tools to learn about. It also explains how to customize with the topic parameter. However, it doesn't explicitly state when NOT to use it or directly contrast it with alternatives, 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 description discloses that the row is deactivated rather than deleted, and explains the consequence (historical events remain available). This adds meaningful behavioral context beyond the annotations, which only state destructiveHint=false. Idempotency is not mentioned but is covered by the idempotentHint 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 long, front-loaded with the action, and every sentence adds value. No superfluous 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 one-parameter tool with no output schema, the description provides sufficient context: purpose, ownership constraint, and side effects. It could mention the return value, but this is not critical given the tool's simplicity and the sibling context.

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

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

Schema description coverage is 100%, and the schema already explains that 'id' is a subscription uuid returned by subscribe. The description adds no new parameter details beyond this, so a baseline score of 3 is appropriate.

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

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

The description clearly states the action ('Cancel a subscription by id') and the resource (subscription). It distinguishes itself from siblings like 'subscribe' and 'list_subscriptions' by specifying the cancellation operation, making its purpose unambiguous.

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

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

The ownership enforcement ('you can only cancel your own subscriptions') provides a clear constraint on when this tool can be used. It also hints at the workflow by referencing 'recent_alerts' for historical events, but does not explicitly name alternatives like 'list_subscriptions' for finding the id.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description adds crucial behavioral nuance: the difference between could_not_verify and unsupported, the presence of verification_error, and the fast-path vs grounded pipeline. 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?

Despite being long, the description is front-loaded with trigger phrases and each sentence earns its place: usage, routing logic, output details, and critical caveats. 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?

Since there is no output schema, the description must explain return semantics, and it does thoroughly: all verdict values, evidence format, and the could_not_verify vs unsupported distinction. It covers error handling and pipeline routing, making it complete for a complex tool.

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

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

Schema coverage is 100%, and both claim and tolerance_pct are well-described in the schema. The description adds some context (e.g., when to override tolerance), but mostly reinforces what the schema already states, so baseline 3 is appropriate.

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

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

The description uses a specific verb ('verify') and resource ('natural-language factual claims against authoritative sources'), and opens with explicit trigger phrases. It also distinguishes itself from siblings by emphasizing verdict-based output rather than just grounded answers.

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

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

It explicitly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also describes the financial-vs-other routing and notes it replaces sequential calls, but does not explicitly name sibling tools to avoid.

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, open-world, idempotent, and non-destructive behavior. The description adds specific behavioral details: only active warnings, output attributes, and the implication that expired warnings are excluded (default false). 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?

A single, front-loaded sentence efficiently communicates the tool's purpose and output details without redundancy. The list of warning types and field names is compact and informative.

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 simplicity of the tool, full schema coverage, and the presence of an output schema, the description is complete. It covers the domain, scope, data source, and output attributes, while the schema and annotations handle the remaining operational details.

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 fully described. The description adds no new parameter-level information beyond what the schema already provides, though it reinforces the 'active' default through the word 'Active'. 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 states the tool provides 'Active FMI weather warnings for Finland' and enumerates specific warning types and output fields (headline, severity, colour, validity, regions). This verb-like noun phrase with detailed scope clearly differentiates it from sibling tools like forecast or observations.

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 for retrieving current warning status but does not explicitly name alternatives or provide when-not-to-use guidance. The 'Active' qualifier gives clear context, but there is no direct comparison to siblings.

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