Movies

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

Beyond the annotations (readOnly, idempotent, etc.), the description adds meaningful behavioral context: default model (Workers AI Llama-3.3-70b, free), the need for a BYO Anthropic key, and the cost implication ('you pay Anthropic directly'). This clarifies auth requirements and external calls, exceeding what annotations provide.

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

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

Three tightly-written sentences, each earning its place: purpose + scoring, default model and key handling, return structure + use cases. No fluff, front-loaded with the main verb.

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

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

Despite no output schema, the description explains the per-model return fields (score, confidence, signals, raw_response) and a combined view. Combined with clear annotations, the tool is sufficiently specified for an agent to invoke and interpret results.

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

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

Schema coverage is 100%, but the description adds value by explaining the default model behavior (workers-ai is free and used if models is omitted) and clarifying that Anthropic calls require _apiKey and incur costs. This goes beyond the schema descriptions, which already document the parameters.

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

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

The description clearly states a specific action (probe LLMs) and resource (what they know about an entity), and explains the 0-100 visibility scoring. However, it does not explicitly differentiate from sibling tools like scan_competitor_ai_presence, which could overlap in use case.

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

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

Provides clear use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to pass _apiKey for Anthropic. It does not, however, mention when not to use this tool or name specific alternatives, so it lacks exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: it 'fills arguments', 'works on every tier, one fast call', and returns 'stable pipeworx:// citation URIs', which goes beyond the annotations and is useful for an agent. No contradiction exists.

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

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

The description is longer than average but is well-structured: it starts with a clear directive, then explains the mechanism, provides examples, and ends with alternatives. Every sentence adds value, though some redundancy (e.g., 'works on every tier, one fast call' could be trimmed) prevents a perfect score.

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

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

Despite no output schema, the description explains the output format ('structured answer with stable pipeworx:// citation URIs'), covers a wide range of use cases with examples, and provides explicit guidance on when to use alternatives. This is comprehensive for a default query-routing 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 all six parameters are described in the schema. The main parameter 'question' is clearly defined, and the five aliases are all documented as 'Alias for question.' The description does not add meaning beyond what the schema already provides, 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 states what the tool does: routes questions to a large set of tools and returns structured answers with citation URIs. It distinguishes itself from siblings by naming ask_pipeworx_grounded and deep_research and contrasting their use cases. The verb+resource is explicit ('ask' + 'pipeworx' with detailed behavior).

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

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

The description explicitly says 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and gives precise step-up conditions: use ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad multi-part questions. This provides clear when-to-use and when-not-to-use guidance with named alternatives.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description discloses key behavioral context: it's a beta with candidate routing improvements, currently no candidate is active, and it matches ask_pipeworx exactly right now. It also states there is no fallback – it is a full working router. This adds significant value beyond annotations and helps set expectations about its experimental nature.

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

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

The description is four sentences and front-loads the key point (beta version). It is concise, though there is some redundancy: 'identical universal router' and 'same 5,529 tools, same arguments, same response shape' are repeated in slightly different ways, and 'this currently matches ask_pipeworx exactly' re-emphasizes the same idea. Still, every sentence carries useful 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 beta tool with no output schema, the description is quite complete: it defines the tool, gives its current state (no active candidate), explains how to use it, and notes the response shape matches ask_pipeworx. It also covers the comparison/merge purpose. The only minor gap is a lack of detail on what 'routing improvements' might entail, but that is not necessary for usage.

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

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

The input schema covers 100% of parameters with detailed descriptions and aliases, so the baseline is 3. The description adds no additional parameter-specific meaning, but the schema is already comprehensive. The mention of 'same arguments' as ask_pipeworx adds minimal extra value since the schema is self-sufficient.

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 version of ask_pipeworx, a universal router with the same tools, arguments, and response shape. It distinguishes it from the stable ask_pipeworx sibling by framing it as the experimental edge. The purpose is clear, though it doesn't explicitly state 'answers natural language questions' – that is implied by 'universal router' and the reference to ask_pipeworx.

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

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

The description explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing,' providing a clear when-to-use condition. It also mentions results are compared against the stable router, implying ask_pipeworx as the alternative. It clarifies it's a full working router, so the agent knows it can be used as a drop-in. No explicit when-not-to-use, but the 'beta' framing implies caution.

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 provide read-only/idempotent/destructive hints, but the description adds rich context: refusal reasons, verbatim evidence, success/refusal return structures, and the extra LLM call tradeoff. It explains exactly what happens when data doesn't directly answer, going beyond the annotations.

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

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

The description is long but information-dense with zero filler. It front-loads the core value proposition and then systematically covers behavior, return format, use cases, and tradeoff. Could be slightly tighter, but every sentence earns its place.

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

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

Without an output schema, the description fully specifies success and refusal return shapes, error reasons, usage context, and routing behavior. It leaves no critical gap for an agent making high-stakes decisions.

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 includes aliases for the sole required question parameter. The description adds no extra parameter-specific meaning, but that's acceptable since the schema already fully documents them. Baseline 3 is appropriate.

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

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

The description clearly identifies the tool as a hallucination-resistant answer mode that routes like ask_pipeworx but extracts answers strictly from tool results. It distinguishes itself from siblings (ask_pipeworx, ask_pipeworx_beta) with a specific verb+resource and unique behavior.

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

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

Explicitly states when to use: when answers will be quoted, cited, or acted on and the agent must not invent facts. Also gives exclusion: prefer ask_pipeworx for casual lookups, citing the extra LLM cost. This is direct when/when-not guidance.

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

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

Annotations already mark the tool as read-only, open-world, idempotent, and non-destructive, but the description goes far beyond that with behavioral details: low-confidence resolution short-circuits, blocked closed-market paths, wide-spread illiquidity flags, cancellation-rule parsing, and GDELT/GNews fallback handling. No contradiction with annotations exists.

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

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

The description is front-loaded with purpose and input formats, and the later sections are clearly organized with label prefixes (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, SAFETY). It is quite long, but nearly every section carries actionable operational details that help an agent invoke the tool correctly, so it earns a strong score despite not being lean.

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

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

There is no output schema, so the description bears the full burden of explaining return values. It does so exhaustively: market fields, analysis fields, evidence keys, resolver contract, parent_event shape, news fallback fields, status routes, and cancellation-rule risk are all covered. Given the tool's high complexity, the description is essentially complete.

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

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

Schema coverage is 100%: the schema already fully documents the 'market' formats, the 'depth' enum, and 'include_raw' semantics. The description's parameter guidance mostly repeats schema content (e.g., 'Pass a market slug... or question text'), adding no meaningful new meaning beyond the schema. Baseline 3 applies because the schema does the heavy lifting.

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

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

The description opens with a specific verb-resource pair ('Research a Polymarket bet') and clearly states the tool's scope: it resolves the market, classifies it, fans out to data packs, and returns an evidence packet plus comparison. It also names explicit user intents ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'), which differentiates it 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?

It provides direct usage triggers and many concrete fan-out examples, making it easy to know when to invoke the tool. However, it does not name sibling tools as explicit alternatives or state when not to use this tool, so it stops short of the strongest possible 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 (readOnlyHint=true, destructiveHint=false) already establish safety. The description adds substantial behavioral context beyond annotations: it names data sources (SEC EDGAR/XBRL, FAERS), explains off-calendar fiscal year handling, notes results are sorted by primary metric so 'largest' reads off the top, and discloses it returns paired data with pipeworx:// citation URIs. No contradictions.

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

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

The description is front-loaded with trigger phrases and a clear directive, then tightly packs type-specific behavior, data sources, sorting, and return format. Every sentence carries meaningful information; despite being long, there is no filler or repetition.

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

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

For a tool with only 2 parameters and no output schema, the description is exceptionally complete: it covers purpose, when to use, data sources, edge cases (off-calendar fiscal years), result ordering, return format (paired data + citation URIs), and performance benefit (replaces 8–15 calls). This gives an agent everything needed 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?

Input schema covers 100% of parameters with descriptions, so baseline is 3. The description enriches parameter semantics by explaining what each type value pulls (e.g., for company: latest 10-K revenue, net income, etc.; for drug: FAERS counts, FDA approvals) and how results are ordered. This goes beyond the schema's enums and array descriptions, though it doesn't add new format details beyond the schema.

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

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

The description opens with concrete trigger phrases ('Compare X and Y', 'X vs Y') and states the tool performs 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It clearly distinguishes itself from sibling tools like entity_profile by emphasizing multi-entity comparison in a single call, and notes it replaces sequential lookups.

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

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

The description explicitly instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing clear when-to-use guidance. It also gives example query patterns and describes the two entity types (company/drug) and the data each pulls, making the usage context unmistakable.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses auth requirements (account needed, paid plan for 'thorough'), latency (15-60s, up to ~90s), and behavior traits like 'never invented', explicit gaps[], contradictions[], hop fields, citation_uri, and semantic excerpting. 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 a single dense paragraph, front-loaded with the account requirement and full of essential details. Every sentence earns its place, but the lack of structural breaks (e.g., bullets or sections) makes it harder to scan. It's appropriately sized for the tool's complexity, but not ideally 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?

With no output schema, the description fully covers the return contract: findings packet (verbatim evidence + confidence + source + fetched_at + citation), gaps[], contradictions[], hop field, citation_uri, and semantic excerpting. It also covers edge cases (breaking news returning empty gaps), auth, and latency, making the tool usable without further documentation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value for both params: for 'question' it says 'Broad/multi-part is fine — decomposition is the point'; for 'depth' it explains the iteration/hop behavior ('gap recovery', 'chases leads') and adds that multi-step questions resolve in one call. It doesn't fully add new syntax, but meaningfully enriches the schema's enum 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 names the verb and resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and explicitly differentiates from siblings: 'this is NOT open-web search' and 'For a single lookup use ask_pipeworx'. It also states the mechanism (decomposes into facets, routes to 5,529 tools) and the return type (findings packet).

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

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

Usage is explicitly scoped: 'Best for broad/multi-part questions over structured data' and when to avoid: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also names an alternative if not signed in ('use ask_pipeworx instead') and describes depth-tier tradeoffs.

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 useful context beyond annotations: it returns top-N tools with names, descriptions, full input schemas, and curated examples, and results are ready to call directly with no second schema lookup needed. It could mention more about edge cases (e.g., no results), but the disclosed behavior is sufficient.

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

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

The description is front-loaded with the core purpose and each sentence carries useful info (purpose, usage, return value, placement in workflow). The domain list is long but serves to clarify scope. Not as concise as a two-sentence description, but still well-structured and not wasteful.

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

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

With no output schema, the description adequately explains return values: top-N tools with names, descriptions, full input schemas, and curated examples, ready to call directly. It also covers usage context and the fact that it's a first-stop discovery tool. The description is complete for the tool's complexity and richness.

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

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

Schema coverage is 100% and the schema already describes query as a natural language string with aliases and examples. The description mentions 'top-N' which relates to the limit parameter, but adds minimal new meaning beyond the schema descriptions. Baseline 3 is appropriate given high schema coverage.

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

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

The description clearly states the tool 'Find tools by describing the data or task' with a specific verb and resource. It distinguishes itself from sibling tools by positioning as a meta-tool for discovery, explicitly listing many domains it covers (SEC, FDA, 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?

It explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear context and implies when not to use (if you just want one answer, go directly to a specific tool).

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

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

Annotations already indicate readOnly, idempotent, and non-destructive, and the description adds substantial behavioral context: it fans out across SEC, XBRL, USPTO, news, and GLEIF in parallel; patents soft-fail after the PatentsView sunset; news uses a GDELT→GNews fallback; and return fields are enumerated (cik, recent_filings, fundamentals, patents, news, LEI). This goes well beyond 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?

The description is a single dense paragraph but front-loaded with user intents and the key 'ALWAYS PREFER' directive. While long, it avoids filler; every clause adds detail (fallbacks, output fields, input restrictions). Structurally it could benefit from bullets, but the content earns its place.

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

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

Given the tool's complexity (multi-source fan-out) and absence of an output schema, the description is remarkably complete: it specifies input constraints, output components, API behavior (soft-fail, fallback), and relationship to resolve_entity. An agent can confidently decide to invoke this tool and anticipate its results.

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

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

Schema already provides 100% coverage with descriptive parameter docs (ticker/CIK, names not supported). The description reiterates the same input rules with examples, adding minor emphasis on zero-padded CIK but not introducing meaningfully new semantic information.

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 user-phrase examples and defines the tool as a "full cross-source profile of a US public company in ONE parallel call." It clearly differentiates from siblings by stating "ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view," and it explicitly directs name-based lookups to resolve_entity.

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

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

Usage conditions are explicit: use for holistic company research, prefer over chained single-source lookups, input must be a ticker or zero-padded CIK, and names require resolve_entity first. The description also mentions fallback behavior (GDELT→GNews) and soft-failure for patents, setting expectations for when results may be incomplete.

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, idempotentHint=true, and readOnlyHint=false, covering the safety profile. The description adds minimal extra context like 'previously stored' but does not detail what happens if the key is missing or any return behavior. With annotations present, this is adequate but not rich.

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

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

Two sentences with immediate action in the first sentence. No wasted words—the description is perfectly sized for the tool's simplicity.

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

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

For a single-parameter, destructive operation with no output schema, this description is complete. It includes purpose, usage conditions, and relationship to siblings. The idempotentHint annotation covers missing-key behavior implicitly, so no further explanation is needed.

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 the single 'key' parameter at 100% with the description 'Memory key to delete.' The tool description does not add any meaning beyond the schema, so the baseline of 3 applies.

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

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

The description clearly states 'Delete a previously stored memory by key,' using a specific verb and resource. It distinguishes itself from siblings by explicitly naming 'remember' and 'recall' as companions, making its 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 conditions: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also references companion tools, offering context for selection. Though it doesn't list exclusions, the guidance is actionable and sufficient.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so the safety profile is covered. The description adds valuable context: it fetches the page, extracts specific elements, and emits a standard markdown blob ready for placement. This goes beyond the annotations by explaining network access and output usage.

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 at three sentences, front-loads the core purpose, and uses a structured 'Useful for' list. Every sentence provides meaningful information without redundancy or filler. It is well-organized and directly aligned with the tool's function.

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

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

For a simple tool with 2 parameters and no output schema, the description is complete. It explains the input (URL), the process (fetch/extract), the output format (standard llms.txt markdown), and where to place it. It also covers use cases. There are no significant gaps given the tool's simplicity.

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

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

Schema description coverage is 100%, so the schema fully documents both parameters (url and max_links) with defaults. The description adds minimal parameter-specific detail beyond saying it 'extracts key links', which loosely maps to max_links. It does not enhance or clarify the parameters further, so baseline 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, with specific verbs and resources: 'Generate', 'llms.txt file', 'any URL'. It distinguishes from siblings by focusing on creating llms.txt, unlike ai_visibility_check or scan_competitor_ai_presence. The process (fetches, extracts, emits) and output format are explicitly described.

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 contexts: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' It doesn't explicitly mention alternatives or when not to use the tool, but it gives enough context to decide. Sibling tools are mostly unrelated, so no confusion.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds behavioral context by stating it 'Returns shows, times, and channels', which helps set expectations for output content beyond what annotations provide.

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

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

The description is a single, well-structured sentence that immediately states the primary action, includes a clarifying example, and notes the return fields. No unnecessary words or repetition.

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

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

For a simple read-only schedule tool, the description is complete. It covers purpose, key inputs, and output content. The presence of an output schema and fully documented parameters further reduces the burden on the description.

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

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

The input schema covers both parameters with descriptions and defaults (date format YYYY-MM-DD, country ISO code). The description adds little beyond confirming the use of date and country, so it does not significantly enhance parameter understanding.

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

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

The description clearly states the tool's function: 'Check what's broadcasting on a specific date and country'. It specifies the resource (TV schedule) and the key parameters (date, country), and differentiates from siblings like get_tv_show and search_tv_shows by focusing on broadcast schedule rather than show details or search.

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 (checking broadcasts by date and country) and gives examples of valid inputs. It does not explicitly name alternatives or exclusions, but the context is sufficient for a simple look-up tool in the presence of sibling tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is known. The description adds the dependency on search_tv_shows and mentions the return content, but since an output schema exists, return details are redundant. This adds modest context beyond annotations but lacks deeper behavioral disclosure (e.g., pagination, network 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 well-structured sentence that front-loads the action and result, then provides the necessary prerequisite. Every word adds value; 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?

The tool is simple with one fully documented parameter, a rich output schema, and annotations covering safety. The description supplies the only missing context—the dependency on search_tv_shows—making it complete for selecting and invoking the tool.

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

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

Schema coverage is 100% since the single 'id' parameter is fully described with type, example, and meaning. The description reinforces that the ID comes from search_tv_shows, but it does not add significant new semantics beyond the schema, so the baseline 3 is appropriate.

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

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

The description clearly states the verb ('Get') and resource ('complete TV show details'), lists specific content (episodes, air dates, ratings), and distinguishes itself from sibling tools by noting it requires a show ID from search_tv_shows. This makes its purpose clear and distinct.

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

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

The description gives clear context by specifying the prerequisite: 'Requires show ID from search_tv_shows.' This implies when to use the tool (after searching). However, it does not explicitly name alternatives or state when not to use it, so it misses the 'explicit exclusions' bar for 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 readOnly, idempotent, and non-destructive hints, so the bar is lower. The description adds meaningful behavior: it lists only active subscriptions by default (consistent with the include_inactive param) and enumerates the response fields. 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?

Two concise sentences: the first states the core function and return fields, the second gives usage guidance. No filler, front-loaded with the verb and resource.

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

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

For a simple list tool with one optional parameter and no output schema, the description fully covers purpose, scope, return fields, and usage context. It is complete and self-sufficient for an agent to decide when to call it.

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

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

The input schema has 100% coverage for the single parameter (include_inactive) with a clear description, so the baseline is 3. The tool description does not add any further parameter semantics, but since the schema fully documents it, no deduction is warranted.

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

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

The description uses a specific verb ('List') and clear resource ('the caller's active subscriptions'), and distinguishes from sibling tools like subscribe/unsubscribe by explicitly scoping to the caller's data. It also names the exact fields returned, removing ambiguity.

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

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

The description gives explicit use cases: 'review what you're monitoring before adding more' and 'find an id to cancel', which implies when to use this tool versus alternatives like subscribe/unsubscribe. It does not explicitly say when not to use it, but the context is clear and actionable.

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

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

Annotations are all false, so the description carries the full burden and meets it. It discloses rate limiting ('Rate-limited to 5 per identifier per day'), the claim_token flow for anonymous filing and later retrieval, and that it is 'Free; doesn't count against your tool-call quota.' These are behavioral details beyond any structured metadata.

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

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

Although lengthy, every sentence serves a purpose: scope, categories, exclusions, claim behavior, rate limits, and cost. The opening sentence is a clear front-loaded purpose statement, and the rest is dense with actionable detail. No filler.

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

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

With no output schema, the description must explain return behavior, and it does: the claim_token response and how to check resolution status. It also covers scope, rate limits, and roadmap impact, making the tool's full behavior clear. The nested context object is explained in the schema, so no additional burden there.

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 meaningful context beyond the schema, especially for claim_token: 'Filing without an account returns a `claim_token`; pass it back later as pipeworx_feedback({claim_token:"pwfb_…"}) to read whether it was fixed and what changed.' This clarifies usage patterns 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 opens with a clear verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly enumerates feedback categories (bug, feature/data_gap, praise), differentiating it from sibling tools like ask_pipeworx or discover_tools. The scope is 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 a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' Also gives a clear exclusion: tools from other MCP servers should be filed elsewhere. This is ideal guidance with both inclusion and exclusion criteria.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable context beyond that: it notes the data source ('derived from CF analytics-engine'), privacy guarantees ('no PII, just (pack, tool, count)'), and caching behavior ('Cached 5min-1h depending on window'). This is rich behavioral disclosure 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 three sentences with a clear front-loaded purpose, followed by enumerated use cases and a compact behavioral summary. Every sentence earns its place; 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 single-parameter tool with rich annotations and no output schema, the description is fully complete: it covers purpose, use cases, returned data, data source, privacy, and caching. The lack of an output schema does not require more detail because the return value is explicitly stated.

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

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

Schema coverage is 100% and the parameter description already explains the window enum and the trade-off ('Shorter windows surface what's hot; longer windows show steady-state demand'). The tool description repeats the window options but adds no new semantics, so the baseline score 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 states a specific verb ('Returns') and resource ('top tools, top packs, and total call volume'), and clearly differentiates from siblings like discover_tools by emphasizing it aggregates what AI agents are calling 'right now'. It also enumerates three concrete use cases, making the purpose unmistakable.

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

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

The 'Useful for' section explicitly lists three scenarios (discovering hot data sources, confirming canonical tools, seeing alignment with agent needs), providing clear context for when to use this tool. It does not mention alternatives or exclusions, stopping short of the 'when-not-to-use' guidance that would merit 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?

Even with strong annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses internal logic that annotations cannot convey: the semantic anchor threshold (Jaccard ≥0.30), the partition filter for placeholder slugs, and the fill check against live CLOB depth. It explains what realizable_edge_pp ≤ 0 means ('do not trade it'). This is rich behavioral context beyond the structured hints.

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

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

The description is long (~300 words) but densely informative and well-structured with clear section labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every sentence carries operational value, and key concepts are bolded for scanning. It is slightly verbose but appropriately so for a multi-mode tool with edge-case caveats.

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

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

Despite no output schema, the description enumerates the response fields ('opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context)', 'partition_check{...}'), describes edge cases (placeholder filtering, low similarity), and explains how to interpret fill-check results. It also cross-references polymarket_fill_risk for custom sizing, making the tool's behavior complete within its 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?

Though schema coverage is 100%, the description adds substantial meaning to the 'event' and 'topic' parameters. It specifies accepted slug formats ('fed-decision-may-2026'), notes that full URLs are accepted, and explains what the tool does with each parameter (e.g., 'walks child markets' for event, 'searches related events across the platform' for topic). This goes well beyond the schema's brief 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 opening line states the exact function: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' This is a specific verb-resource pair with a clear method, and it distinguishes this tool from siblings like polymarket_edges (which likely shows edges rather than solving arbitrage) by naming its unique detection techniques.

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

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

The description explicitly defines three invocation modes (no args for trending_scan, event for a specific market, topic for cross-event scanning) and provides clear recommendations ('event (recommended for a specific market)', 'topic (for cross-event scanning)'). It also names an alternative tool for related but different needs: 'For custom sizing use polymarket_fill_risk.' This meets the 'explicit when/when-not/alternatives' bar.

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

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

The description reveals extensive behavioral details beyond annotations: three segmented response groups, model formulas, edge/net-of-slippage, 24h-move warnings, gate relaxations, caching keyed on knobs, and diagnostics to explain empty segments. Annotations already declare read-only/idempotent so 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 very long and dense, including specific alpha values and exact gate relaxations. While organized into sections, it could be more concise; not every detail is essential for an agent to invoke the tool correctly. Still, the front-loaded purpose makes it more than just a wall of text.

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 this complexity (three model families, nine knobs, diagnostics), the description is exceptionally complete: it explains response top-level fields, when segments might be empty, how filters drop opportunities, and the caching behavior. No output schema exists, so this detail compensates.

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 all 9 parameters with 100% coverage, so baseline is 3. The description adds meaningful context on how knobs interact (e.g., min_partition_leg_kelly applies to per-leg Kelly since partition arbs return zero parent-level Kelly) and explains slippage rationale, adding value beyond the schema.

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

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

The description clearly states a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It distinguishes from sibling tools by emphasizing it's for discovering 'what should I bet on today' opportunities, not for tracking or risk analysis.

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

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

It gives context ('Built for what should I bet on today') and excludes certain bets (fed candidates unreliable) but doesn't explicitly name alternatives or when-to-not-use compared to sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, non-destructive), the description discloses important behavioral traits: snapshots are written only on cache-miss (leading to gaps), history is bounded by a 60-day TTL, and decay is computed from daily closes, not intraday data. This is substantial context that annotations alone do not provide.

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

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

The description is well-structured with clear sections (purpose, args, response, limits) and every sentence contributes unique information. While it is longer than the two-sentence ideal, the elaborate phrasing reinforces the use case without redundancy, earning a high but not perfect score.

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

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

Given the absence of an output schema, the description fully specifies the response structure: tracked[], expired[], snapshot_dates[], including field meanings and derived metrics. It also explains data freshness limitations and TTL, making the tool self-contained and complete for an agent to use correctly.

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

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

Schema description coverage is 100%, and the description's parameter notes (defaults, max/clamp) essentially mirror the input schema. It adds no new semantic information about the parameters, so it sits at the baseline 3 for high-coverage schemas.

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

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

The description clearly states that the tool provides 'edge persistence and decay telemetry' and answers a specific question: 'how long has this edge existed and is it shrinking?' This is a distinct verb+resource with clear scope, and it differentiates from sibling tools like polymarket_edges by focusing on time-series persistence rather than current edge listings.

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

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

The description establishes its use case with the question 'how long has this edge existed and is it shrinking?' and explains why edge age matters, implicitly positioning it as a companion to polymarket_edges. However, it does not explicitly name alternatives or provide exclusion criteria, so it lacks the direct 'when-not-to-use' guidance that would earn 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 and idempotentHint, but the description adds substantial behavioral context: it walks the order-book ladder, returns specific metrics (top_of_book, vwap_fill_price, slippage_pp, shares_filled), and warns about partial basket fills converting an arb into an unhedged directional position. It also discloses the default size_usd and the clamp (10–1,000,000), which is beyond the 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 long but exceptionally well-structured: it front-loads the core purpose, then separates SINGLE-MARKET and BASKET modes with clear formatting, and ends with actionable usage guidance. Every sentence carries critical information (defaults, outputs, risk warnings) with no filler, making the length justified for a tool of this complexity.

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

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

With no output schema, the description carries the full responsibility of explaining return values, and it does so thoroughly: it lists all key outputs (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, capture_ratio, profit_usd, thin_legs[], forced_directional_risk, etc.). It also covers prerequisites (requires market or event), both modes, and the risk scenario, making the tool fully understandable for selection and invocation.

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

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

The input schema already provides 100% coverage with descriptions for all 4 parameters, so the baseline is 3. The description adds value by clarifying semantics: size_usd as 'max spend on buys, target proceeds on sells' in single-market mode, and 'settlement notional' in basket mode, plus the interpretation of side defaults (auto from partition sum). This goes slightly beyond the schema's phrasing, so a 4 is warranted.

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

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

The description opens with a specific verb-resource pair: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes two modes (single-market and basket) and explicitly references sibling tools (polymarket_arbitrage, polymarket_edges) to differentiate its 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: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround is not capturable on thin books; partial fills create unhedged directional risk), which helps an agent choose this tool over alternatives.

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

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

While annotation readOnlyHint and idempotentHint already establish non-destructive read behavior, the description adds extensive behavioral details: it discloses that the tool performs leg-by-leg matching, drops incompatible pairs, returns compatibility_warning for non-equivalent bet shapes, and includes temporal_alignment to flag misleading spreads. This goes far beyond the structured fields and provides deep transparency into edge cases and failure modes.

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

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

The description is long but structured with clear labels (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded with the core purpose. Each sentence adds substantive information about mode selection, response fields, or safety warnings. It is somewhat verbose, especially the detailed explanation of skipped_cross_type/cross_subtype, but every section contributes to correct usage and interpretation.

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 comprehensively explains the response structure: leg-by-leg prices, matched spread with top_spreads_pp, compatibility_warning cases, temporal_alignment, and skipped counters. For a tool with this complexity (cross-venue matching, multiple safety validations), the description fully equips the agent to invoke it correctly and interpret results.

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

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

The input schema already documents all three parameters with descriptions (100% coverage), so the baseline is 3. The description adds meaningful interaction semantics by explaining the two modes, how explicit kalshi_event_ticker and polymarket_event_slug override topic-mapped defaults, and lists the valid topic enum values. This extra context earns a 4, though the schema alone is already strong.

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-like noun phrase 'Cross-venue spread between Kalshi and Polymarket for the same resolving question' that precisely defines the tool's purpose and scope. It further clarifies the two operation modes (topic shortcuts vs explicit ticker/slug) and differentiates itself from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison.

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

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

The description clearly explains when to choose the topic mode vs explicit mode and warns that pre-mapped shortcuts often produce compatibility warnings, implicitly advising against assuming tradeability. However, it does not explicitly mention alternative tools (e.g., polymarket_arbitrage) or provide a direct 'use this instead of X' comparison, so it stops short of full 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 destructiveHint=false, and the description adds useful context about scoping ('Scoped to your identifier') and listing behavior when the key is omitted. No contradictions with annotations; the added details enhance transparency beyond the structured data.

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

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

The description is three sentences long, with the primary action stated first and no filler. Each sentence adds meaningful information: what it retrieves, when to use it, how it is scoped, and how it relates to sibling tools.

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

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

For a tool with a single optional parameter, no output schema, and safety annotations already present, the description covers all essential aspects: operation, use cases, scoping, and complementary tools. It leaves no significant gaps for an agent to misuse the tool.

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

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

The schema already fully documents the 'key' parameter, but the description reinforces and expands on its semantics by explaining that omitting it lists all saved keys and providing example values. This enriches the parameter meaning beyond the bare type/description.

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

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

The description immediately states the core action: 'Retrieve a value previously saved via remember', with a clear alternative behavior of listing all keys when the key is omitted. It also distinguishes itself from sibling tools by referencing 'remember' and 'forget' explicitly.

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 concrete guidance on when to use this tool: 'Use to look up context the agent stored earlier', with examples like target ticker, address, and research notes. It also names the complementary tools ('Pair with remember to save, forget to delete'), making the workflow explicit.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds valuable behavioral detail: the mark_read flag mutates read state (affecting future calls), and the feed is persisted and also accessible via a public URL. This goes beyond the annotation basics 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 remarkably concise at three sentences, front-loaded with the primary action. Every sentence conveys essential information: what it returns, how to filter, the read-flag side effect, and an alternative access method. 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?

Given five optional parameters and no output schema, the description covers the tool's return structure (source, citation_uri, raw payload), filtering, and read-state behavior. It does not address pagination, error handling, or default ordering beyond 'most recent', but for a modest polling tool this is adequate and no critical gaps are evident.

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 parameters are already documented. The description adds concrete context: a 'type' example ('sec_8k'), clarifies 'since' as ISO timestamp, and explains the effect of mark_read. This enrichment provides meaning beyond the schema's field descriptions.

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

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

The description states a specific verb ('Pull') and resource ('fired events from your subscription feed'), making the tool's function immediately clear. It further specifies the return payload (source, citation_uri, raw event payload), distinguishing it from sibling tools like list_subscriptions or recent_changes which operate on different 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 clear usage context, including how filtering works and that polling is supported. It also mentions an alternative REST endpoint for scripts/dashboards, which is pertinent guidance. However, it does not explicitly contrast with sibling tools or state 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description doesn't repeat safety traits. It adds meaningful behavior beyond annotations: GDELT→GNews fallback on rate-limit/5xx, USPTO soft-fail due to PatentsView sunset, and the exact return shape (changes[] grouped by source + total_changes + pipeworx:// citation URIs).

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

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

The description is dense and front-loaded with natural-language triggers, then lists sources, fallback logic, since formats, return semantics, and a sibling alternative. Every sentence adds value and no filler exists. It is slightly long but justified by 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?

With no output schema, the description fully explains the return value: 'structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs.' It also covers `since` syntax, source fallbacks, and the USPTO soft-failure. For a tool with three sources and fallback behavior, the description 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?

Schema coverage is 100%: all three parameters have descriptions with formats and examples. The description reinforces the `since` formats and adds a usage tip ('Use 30d or 1m for typical monitoring'), but this is marginal beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description opens with natural-language triggers ('What's new with X' etc.) and explicitly defines the tool as 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It names the specific data sources and contrasts with entity_profile, making its purpose and distinctiveness clear.

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 gives an alternative: 'Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window.' It also implicitly defines when to use recent_changes based on time-window-oriented queries like 'what's new' or 'latest on Y.'

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

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

Beyond annotations (which indicate idempotent and non-destructive behavior), the description adds critical context: key-value pairing, scoping by identifier, and session-dependent persistence (24h for anonymous, permanent for authenticated). This is valuable behavioral information not present in the annotations.

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

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

The description is a compact set of four sentences, front-loaded with the core action. Each sentence adds necessary context: usage trigger, storage format, persistence behavior, and sibling tool relationships. No extraneous words 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 simple nature of a store tool, the description covers the essential aspects: what to store, when to use it, scoping, persistence, and how to retrieve/delete later. The parameters are fully documented in the schema, annotations cover safety/idempotency, and no output schema is needed for a basic save operation. The description is 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?

The input schema fully describes both parameters (key and value) with examples, achieving 100% schema description coverage. The description echoes these examples but adds no new parameter-level syntax or constraints. It does mention 'any text' for value, but that's already in the schema, so it merely reinforces rather than extends.

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

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

The description begins with a specific verb and resource: 'Save data the agent will need to reuse later,' clearly stating the tool's function. It further specifies usage with examples (resolved ticker, target address, user preference) and distinguishes itself from siblings by explicitly mentioning 'Pair with recall to retrieve later, forget to delete.'

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

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

The description provides explicit when-to-use guidance: 'Use when you discover something worth carrying forward.' It also clarifies exclusions/alternatives by naming sibling tools recall and forget, and notes the persistence difference between authenticated and anonymous sessions, giving the agent a clear decision framework.

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

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

Annotations already signal readOnly, openWorld, idempotent, and non-destructive behavior. The description adds significant behavioral context: graceful degradation when GLEIF/OpenFIGI are unavailable, explicit 'unresolved' reporting, source labelling for every identifier, and cascading internal lookups. This goes well beyond the annotations.

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

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

The description is long but well-structured and front-loaded with user-query examples. Every sentence contributes unique information (supported types, degradation, output handling). While it could be trimmed slightly, the density is appropriate for a complex multi-endpoint 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?

For a tool with no output schema, the description is remarkably complete. It covers what identifiers are returned per type, how unresolved identifiers are handled, source labelling, and fallback behavior. It also explains why the tool is useful ('replaces 2-3 manual lookups'), giving enough context for an agent to select and invoke it accurately.

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

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

Schema coverage is 100%, so the baseline is 3. The description enriches parameter meaning by explaining the consequences of choosing 'company' vs 'drug', detailing input formats (ticker, CIK, name; brand/generic) and the output categories (identifiers, unresolved). This adds value beyond the schema's basic descriptions.

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

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

The description clearly states the tool's function: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It lists specific query examples and explicitly distinguishes supported types (company, drug) with the identifiers returned, which sets it apart from sibling tools like entity_profile.

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

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

The description provides explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It also clarifies that it replaces 2-3 manual lookups. However, it does not mention when not to use it or compare it explicitly to related siblings like entity_profile, so it stops short of full alternatives/exclusions.

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

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

Annotations already declare read-only and idempotent; the description adds behavioral context by explaining the probe mechanism, ranking logic, and return fields (score, confidence, signal density). It also discloses that the first entity is treated as the subject. No contradiction with annotations.

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

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

The description is concise and well-structured: four sentences, action-first, with a useful example and return-value preview. Every sentence contributes needed context with no redundancy.

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

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

For a tool with no output schema, the description effectively pre-announces the ranked result shape and the core use case. It is complete given the rich annotations and schema, though it could slightly improve by explicitly stating when to prefer this over ai_visibility_check.

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 minimal parameter meaning beyond the schema, mostly framing entities as brand vs competitors. It does not clarify parameter formats or edge cases beyond what the schema already documents.

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

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

The description opens with a specific verb and resource: 'Compare AI visibility across multiple entities side-by-side.' It clearly distinguishes this from sibling tools by mentioning the internal call to ai_visibility_check, ranking by score, and surfacing most/least recognized entities.

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

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

The description provides a clear use case ('competitive AI-marketing audits') with a concrete example question. It implies contrast with the single-entity ai_visibility_check tool, but it does not explicitly state when not to use this tool or name alternatives beyond the implied 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?

Beyond the readOnlyHint/idempotentHint annotations, the description discloses partial failure behavior, latency expectations (5-30s for first bundlephobia measurement), and the sources_failed field. It also details what the tool returns, giving agents a clear behavioral model.

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

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

Though the description is longer than typical, every sentence contributes: purpose, use cases, output fields, ecosystem scope, and failure handling. It is front-loaded with the core question and uses dashes and structured clauses to maintain scannability.

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

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

With no output schema, the description fully enumerates the return values (summary block fields, per-advisory details, links, alternatives). It also covers ecosystem limitations, partial failure modes, and timing, making it self-sufficient for a complex composite tool.

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

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

The input schema already documents both parameters comprehensively (package name, version default behavior), so the description adds little new semantic detail. However, it does contextualize the parameters within the composite check by showing how they feed into the fan-out, which is marginal added value.

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

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

The description clearly defines the tool as a composite 'should I add this npm package to my project' check, explicitly naming the data sources (deps.dev, bundlephobia) and the specific analysis dimensions. It distinguishes itself from siblings by focusing on npm package risk, size, and adoption, with a clear verb-resource structure.

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

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

The description explicitly states when to use the tool ('Use whenever an agent asks...') and gives concrete examples like 'what does adding lodash cost me'. It also provides an explicit exclusion and alternative for non-NPM ecosystems, directing to 'deps.dev:version directly', which is excellent 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 cover read-only and idempotent behavior. The description adds no extra behavioral context beyond what annotations and schema already provide. It does not contradict the annotations, but also does not contribute meaningful new behavioral details.

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

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

The description is two sentences, front-loaded with the tool's primary action, and includes a compact list of return fields. Every sentence is informative with no fluff.

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

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

With a low-complexity tool, full schema coverage, and an output schema present, the description adequately covers the necessary context. The return fields listed are redundant with the output schema, but that does not detract from completeness.

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

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

Schema coverage is 100%, with clear descriptions for both 'query' and 'limit'. The description's phrase 'by title or keyword' merely restates the query parameter description, adding no new semantic meaning.

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

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

The description states a specific action ('Search') and resource ('movies'), and lists return fields. It clearly distinguishes from siblings like search_tv_shows by explicitly scoping to movies.

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

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

The description implies when to use the tool (when searching for movies), but it does not explicitly mention alternatives or exclusion criteria. Sibling tools like search_tv_shows are not referenced, so some inference is required.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful return-field context but does not disclose pagination, result limits, or that the query supports keywords beyond exact names. Overall, it adds some value beyond annotations but no significant behavioral traits.

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

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

The description is two sentences, front-loaded with the verb and resource ('Search for TV shows'), followed by a compact list of return fields. Every word adds value with no fluff or redundancy. Structure is ideal 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?

For a simple single-parameter tool with rich annotations and an output schema, the description is mostly complete. It tells the agent what is returned and that it's a search action. However, it misses the keyword-aware nature of the query and does not mention how results are ordered or limited, which are relevant for a search tool. Still, the gap is minor given the tool's low complexity.

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

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

Schema coverage is 100% with the 'query' parameter already described as 'TV show name or keyword to search for'. The tool description merely repeats 'by name' and does not add new meaning. The schema's example 'sci-fi drama' actually provides more semantic richness than the description, so the description does not compensate 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 states the tool searches for TV shows and lists the fields returned (name, genres, dates, rating, summary, images). It distinguishes from siblings like search_movies by focusing on TV shows, though it omits explicit comparison to get_tv_show. The phrase 'by name' is slightly narrower than the schema's 'name or keyword', creating minor ambiguity.

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

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

No guidance is given on when to use this tool versus alternatives like get_tv_show (for specific show details) or search_movies. The description implies a search use case from the verb 'search' but does not explicitly state exclusions or select the tool over its siblings. This leaves the agent without clear decision support.

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

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

Annotations already declare readOnly, idempotent, and non-destructive hints, but the description adds rich behavioral context beyond them: the embedding model (BGE-base-en), cosine similarity over 500-char overlapping windows, the 200K-char cap with truncation flagging, and the fact every passage carries an offset for verbatim verification. These details are not present in 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?

Four sentences, each earning its place: the first states the core function, the second gives usage guidance, the third provides sibling integration, and the fourth discloses technical implementation. The description is front-loaded with the main verb and resource, 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?

Given no output schema, the description still explains return values (passages with offsets and scores), covers behavioral edge cases (truncation), and situates the tool within a larger workflow (pairing with ask_pipeworx_grounded). For a moderately complex search tool, this is complete.

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

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

Schema description coverage is 100%, so a baseline of 3 applies. The description adds contextual color (e.g., 'text you already pulled') but does not introduce new parameter semantics or format details beyond what the schema already provides for text, limit, and query.

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

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

The description opens with 'Semantic search INSIDE a fetched record'—a specific verb and resource that clearly distinguishes it from sibling search tools like search_movies or ask_pipeworx_grounded. It further details the output (top-N passages with character offsets and similarity scores), leaving no ambiguity about what the tool does.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt.' It also names a complementary tool, ask_pipeworx_grounded, and describes the pairing workflow ('fetch with the gateway, ground over the relevant passages'), providing clear alternatives and context.

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

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

Annotations already indicate readOnly=false and idempotentHint=true, but the description adds substantial behavioral context: auth requirements, persistence constraint, feed always-on behavior, email/SMS verification, 10/day SMS cap, and webhook auto-disable after 10 failures. This goes well beyond the annotations and directly informs the agent about side effects and prerequisites.

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 carries unique operational detail. It front-loads the core action and return value, then methodically covers types and delivery channels. No filler or repetition of schema content—each 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?

Despite no output schema, it explicitly states 'Returns the new subscription id' and covers the webhook signing secret one-time return. It addresses auth, rate caps, channel behavior, and disabled conditions. For a subscription-creation tool with nested objects and complex delivery options, this description is fully adequate for an agent to invoke correctly.

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

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

Schema coverage is 100%, but the description enriches every parameter with concrete examples (e.g., sec_8k with items:['5.02'], polymarket_edge with topic:'fed', fred_series with series_id). It also clarifies delivery validation rules (verified phone, HTTPS-only webhooks, signing secret behavior) that are not in the schema descriptions. This significantly improves 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 opens with a specific verb+resource: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly distinguishes this from siblings like list_subscriptions, unsubscribe, and recent_alerts by emphasizing creation and ongoing monitoring. The list of supported event types further scopes the tool's purpose.

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

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

It states a clear prerequisite (Pipeworx OAuth account, not anonymous/BYO) and describes delivery channel options with constraints. It does not explicitly name alternative tools for one-time queries or when not to use this, but the context around persistent subscriptions versus one-shot retrieval is clear enough for an agent to infer appropriate usage.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral detail beyond that, such as the return format (category-bucketed example questions) and that each result includes the exact tool and argument shape. It also clarifies the live catalog source and how to narrow by topic.

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

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

Although the description is longer than typical, it is densely packed with high-value information: query examples, output structure, usage modes, and onboarding guidance. It is well-structured with a clear flow (what it is, what it returns, how to call, when to use). Every sentence contributes meaning without redundancy.

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

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

The description is complete for the tool's complexity. It explains the purpose, output content (category-bucketed questions with tool+argument shapes), parameter behavior, and explicit when-to-use guidance. There is no output schema, so the description fully compensates by describing the return format. Annotations cover safety, so no gaps remain.

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

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

The schema already provides 100% coverage for the single optional 'topic' parameter, including a list of allowed values. The description adds marginal context by restating examples ('finance', 'pharma', 'betting') and explaining the default behavior (cross-category spread), but does not fully go beyond the schema's own description. 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 uses a specific verb+resource ('suggest questions') and clearly defines the tool's scope as the onboarding entry point for discovering what Pipeworx can do. It distinguishes itself from siblings by explicitly stating it returns category-bucketed example questions with exact tool+argument shapes, and by naming meta-tools like ask_pipeworx and entity_profile.

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

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

The description provides explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It also clarifies the no-argument vs topic-argument usage and gives examples of topics, making it clear how to invoke the tool in different contexts.

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

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

Beyond annotations (which already indicate non-destructive and idempotent), the description adds critical behavior: ownership enforcement and soft-delete ('deactivated not deleted') with historical events preserved in recent_alerts. This provides meaningful side-effect disclosure without contradicting annotations.

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

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

Three sentences, front-loaded with the action, and every sentence adds value: what, ownership, and side effects. No filler or 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 one-parameter tool with annotations and no output schema, the description fully covers purpose, constraints, and behavioral consequences. It references related state (recent_alerts) and clarifies the lifecycle of the subscription.

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

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

Schema coverage is 100% for the single 'id' parameter, which is well-described as a uuid from subscribe. The description's mention of 'by id' adds no new semantics; the schema already covers it. 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 states 'Cancel a subscription by id' with a specific verb and resource, directly distinguishing it from siblings like 'subscribe' and 'list_subscriptions'. It clearly identifies the action and target.

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 (cancel a subscription) but does not explicitly list alternatives or when not to use. Ownership enforcement is mentioned but not tied to alternative tools. Basic context is clear, but no explicit when/when-not 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?

Beyond the read-only and idempotent annotations, the description discloses the two execution pathways (SEC EDGAR/XBRL vs. grounded live sources), the exact verdict set, and crucially distinguishes 'could_not_verify' (failed check, not evidence) from 'unsupported' (no source found). This is critical behavioral context that significantly exceeds 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 dense but well-organized: it starts with examples, then usage, routing, output, special notes, and replacement value in a single paragraph. It is on the longer side, but every sentence contributes needed context for this complex tool, and the critical caveats are clearly highlighted.

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

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

The description fully covers input (claim, optional tolerance), process (financial vs. grounded), output (verdict, value, citation, reasoning), and error semantics (could_not_verify vs. unsupported) without requiring an output schema. It even explains what multi-step process it replaces, giving the agent a complete mental model of the tool's behavior.

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 contains full descriptions for both parameters (100% coverage), including detailed semantics for tolerance_pct. The tool description adds no new parameter-level meaning beyond referencing tolerance in the context of results, 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 defines the tool as natural-language claim verification, provides concrete usage examples, and distinguishes its two processing paths (financial vs. grounded), making it distinct from sibling research tools. The verb 'validate' plus the resource 'claim' is specific, and the explanation of what it returns adds clarity.

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 it ('Use whenever the agent needs to check whether something a user said is factually correct') and positions it as a replacement for a 4–6 call pipeline, covering both when and how. Although no alternative tools are named, the description makes clear this is the go-to tool for any factual claim, making exclusions unnecessary.

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