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 indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds beyond annotations: it explains that the tool routes internally, fills arguments, returns structured answers, and provides stable pipeworx:// citation URIs. It also clarifies that ask_pipeworx is retrieval, not reasoning, which is useful behavioral context. No contradiction with annotations.

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

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

The description is long but front-loaded with the most important guidance ('PREFER OVER WEB SEARCH') and then examples. Every routing clause and alternative adds real value for an agent deciding between many siblings. It is slightly dense and could benefit from more formatting, but no sentence feels wasted.

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

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

There is no output schema, so the description must carry the return-value and boundary information itself. It does: it states the answer format, citation URIs, data domains, when not to use it, alternatives for every common case, and an escalation path. This is complete for a broad routing tool with many siblings.

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 schema defines six aliases for 'question', and all are documented. The description adds meaningful context by giving example questions and clarifying that the input is a natural-language query, which helps an agent form correct invocations. It doesn't need to do more because the parameter semantics are simple and already fully covered.

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

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

The description clearly states this tool routes questions to the right one of 5,798 tools across verified sources and returns structured answers with citation URIs. It uses a specific action verb ('routes', 'returns') and explicitly differentiates itself from siblings like ask_pipeworx_grounded, deep_research, search_within, and discover_tools.

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

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

The description gives unusually detailed guidance: prefer over web search, use for factual/real-world questions, and names many sibling tools with exact conditions for when they should be used instead. It even says 'START HERE' for most questions, 'If unsure leave it to ask_pipeworx', and advises escalation to deep_research when insufficient. This is explicit 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 declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds valuable behavioral context: routing candidates can be enabled live, none is currently active as of a specific date, and this is a full working router with no fallback. This tells the agent that behavior may change over time if a candidate is under test.

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 key point is front-loaded: this is a beta, identical router with possible experimental routing. The middle sentences provide current status and usage guidance, and the final sentence clarifies that there is no fallback. There is slight redundancy between 'identical universal router' and 'currently matches ask_pipeworx exactly', but nothing is wasted.

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 points to a known reference by stating the 'same response shape' as ask_pipeworx and explains current parity and experimental behavior. It could describe the return structure directly, but referencing the sibling plus the complete schema and rich annotations is sufficient for correct invocation.

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

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

Schema description coverage is 100%, with all six parameters documented as aliases of question. The description only says 'same arguments as ask_pipeworx' and adds no parameter-level meaning beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description opens by identifying this as the beta of ask_pipeworx and explicitly says it is an 'identical universal router' with the same 5,798 tools, same arguments, and same response shape. It distinguishes it from the stable ask_pipeworx by the experimental 'candidate routing improvements' edge, making the tool's role completely 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?

It gives an explicit selection condition: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains that results are compared against the stable router, which implies the stable tool is the alternative. It does not explicitly list exclusion cases or mention grounded variants, so it falls just short of full guidance.

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

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

Beyond the annotations, it discloses refusal behavior with concrete refusal_reason values, states the output will contain verbatim evidence, and explains that the answer is extracted only from the tool result. It also reveals the cost implication. No annotation contradiction is present.

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 the differentiator stated in the first sentence. It contains several clauses, but each one earns its place: behavior, refusal format, use cases, and cost comparison. Slightly long but not padded.

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

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

With no output schema, the description fully documents both the success return shape and the refusal return shape, lists the refusal reasons, states when to prefer the cheaper sibling, and explains the grounding behavior. An agent has everything needed to call this tool and interpret its result.

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

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

Schema description coverage is 100%: every parameter is an alias of 'question' and is documented in the schema. The description does not need to add parameter detail, but it also does not go beyond the schema. Baseline 3 is appropriate.

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

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

The description names a specific mode ('hallucination-resistant answer mode') and clarifies exactly what distinguishes it: same routing as ask_pipeworx, but extraction is limited to the tool result with an explicit refusal path. This is a concrete verb+resource statement that clearly differentiates it from the sibling tools.

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

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

The description gives explicit when-to-use guidance ('Use whenever an answer will be quoted, cited, or acted on'), gives the alternative ('prefer ask_pipeworx for casual lookups'), and even discloses the trade-off (one extra LLM call). This is model ideal routing guidance.

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

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

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?

The description goes well beyond the annotations by disclosing account requirements, latency expectations, gap handling, contradictions[], citation_uri fetchability, and the fact that findings are never invented. Nothing here contradicts the readOnly, idempotent, or openWorld 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 dense, with almost every sentence carrying operational value: account gate, alternative routing, input scope, output format, latency, and citation guarantees. It is not concise in word count, but it is efficiently front-loaded with the most important usage constraints.

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

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

Even without an output schema, the description fully specifies what the agent should expect: findings with evidence, confidence, source, fetched_at, a stable citation URI, gaps[], contradictions[], and hop fields. It also covers account prerequisites, latency, and depth semantics, so an agent has nearly everything needed to invoke and interpret the tool correctly.

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

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

Schema coverage is 100%, so the schema already documents both parameters well. The description adds meaningful extra context by explaining how depth values affect hops, gap recovery, lead chasing, and contradiction scanning, and by clarifying that the question can be broad and multi-part.

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

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

The description states a specific verb and resource: it performs grounded multi-source research across 1,517 structured data sources, decomposes questions into facets, and returns a findings packet. It also explicitly distinguishes itself from open-web search and single lookups, making its identity 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?

Usage is explicitly clarified with conditions: broad/multi-part questions over structured data are the target use, single lookups should use ask_pipeworx instead, and unsigned-in users are routed to ask_pipeworx. It also explains when deeper depth variants are appropriate and that thorough requires a paid plan.

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 declare readOnlyHint, openWorldHint, idempotentHint, and no destructive behavior, and the description adds substantial context beyond that: it enumerates the many sources fanned out to, explains that empty sections mean real 'no data' via sources_used/sources_failed, documents USPTO patent data soft-failure after May 2025, and clarifies expected empty fda_products for non-biologic companies. This is rich, non-obvious behavior.

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

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

The description is long, but almost every clause carries required behavioral or edge-case information, and there is no output schema to carry that burden. It is front-loaded with trigger examples and the preference instruction. It could be more scannable with bullets, but it contains no filler or redundant restatements.

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 correctly takes on the burden of explaining the return envelope: it lists every major output section (filings, fundamentals, patents, contracts, fda_products, hiring, news, LEI), defines sources_used/sources_failed semantics, and covers edge cases like private companies, expected-empty FDA sections, and USPTO sunset. An agent has enough context to invoke and interpret this tool correctly.

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

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

Schema coverage is 100% and both parameters are already documented, so the baseline is 3. The description goes further by giving concrete examples ('AAPL', '0000320193', 'Moderna'), clarifying that type='company' and type='ticker' behave identically, and explaining name resolution plus resolved_from/resolved_to behavior, which adds real meaning beyond the schema.

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

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

The description opens with concrete trigger phrases and states a specific verb+resource: 'full cross-source profile of a US public company in ONE parallel call.' It distinguishes itself from likely alternatives like deep_research and resolve_entity by focusing on a single public company and explicitly naming the alternative pattern it replaces ('chaining single-pack SEC/XBRL/news lookups').

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

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

The description explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' giving a clear condition and alternative. It also covers input resolution behavior and private-company fallback. It does not, however, address potential overlaps with siblings like deep_research or compare_entities, so the guidance is strong but not fully comprehensive.

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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds value by specifying that the tool returns a single record (not a list) and lists the content (episodes, network, status, rating). This contextualizes the openWorldHint by giving typical fields, though it does not detail edge cases or error behaviors.

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

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

Two sentences, front-loaded with the primary purpose, and each sentence serves a distinct role: first states what the tool does, second explains when and how to use it. No filler or redundant content.

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

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

Given the low complexity (one required parameter, no enums, output schema present), the description covers all necessary aspects: purpose, input semantics, output content, usage context, and sibling differentiation. The output schema handles return structure, so no further detail 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?

Schema coverage is 100% with a good example and description for the 'id' parameter. The description adds extra meaning by clarifying that the id is an internal TVmaze number and that it must be resolved via 'search_tv_shows', which goes beyond the schema's static example.

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

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

The description clearly states it returns the full TVmaze record for one TV series by its numeric ID, including episode list, air dates, network, status, and rating. It uses specific verbs ('full record') and resources ('TV series') and distinguishes itself from sibling 'search_tv_shows' by focusing on a single existing ID.

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

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

Explicitly tells when to use this tool (when the caller has a numeric TVmaze ID) and when not (when the caller names the show, use 'search_tv_shows' instead). It also explains the prerequisite of resolving the ID via 'search_tv_shows' first, leaving no ambiguity about the workflow.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=true. The description adds substantial behavioral context beyond annotations: it discloses that the tool does NOT model Kalshi's fee schedule (spread_pp is gross), that compatibility fields can be non-empty even on returned pairs, that 'unknown' legs are never paired, that temporal_alignment null means unknown not aligned, and that pairing is keyword-based, not source-verified. These are exactly the kind of non-obvious behavioral traits an agent needs to interpret results correctly. No contradiction with annotations.

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

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

The description is long but every sentence earns its place — it is dense with safety-relevant detail and never repeats schema text verbatim. It is front-loaded with the core concept, then modes, response, safety fields, and caveats. It loses a point for being longer than necessary to convey the essentials; a more compact structure with bulleted safety codes would be easier for an agent to parse.

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 (two modes, multiple code lists, nested flags, fee disclosures, skipped-leg counters) and the absence of an output schema, the description is remarkably complete. It covers mode selection, the meaning of each safety code, the treatment of unknown legs, the temporal_alignment null semantics, the fee caveat, and the rarity of real spreads. An agent can form a strong expectation of the result shape and know what to check before acting on the spread.

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 goes well beyond the schema: it explains the relationship between the three parameters (explicit overrides override the topic-mapped side), enumerates all 10 topic values in prose, and describes how each mode affects the matching logic ('BOTH modes run the identical token-overlap matcher'). This adds meaning beyond the raw parameter definitions.

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

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

The description states a specific verb+resource: it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from siblings by naming the two venues, the two modes, and the output (top_spreads_pp). Even without comparing to every sibling, it is clear what this tool uniquely 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?

The description explicitly explains when to use each of the two modes: use `topic` for 10 pre-mapped macro shortcuts and explicit `kalshi_event_ticker` + `polymarket_event_slug` for custom pairings. It also sets expectations that most pre-mapped topics return compatibility_warning today, pre-mapped ≠ tradeable — this is direct guidance about when NOT to expect a usable spread. It repeatedly warns the user to read safety fields even when matched_pairs>0, which is practical usage 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?

Beyond the readOnly/idempotent annotations, the description discloses important non-obvious behavior: unresolved identifiers are explicitly listed under `unresolved` rather than omitted, ambiguous FIGI matches return `figi_candidates` without asserting a single answer, LEI/FIGI enrichment degrades gracefully if upstream services are unavailable, and ISINs resolve to the issuing legal entity. This gives the agent a solid model of edge-case 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 dense and somewhat long, with several parenthetical clarifiers packed into one block. However, nearly every sentence adds value, and the most important usage guidance is front-loaded with the example phrasings and 'Use FIRST' instruction. It could be more scannable with bullet structure, but it is not bloated with 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?

Despite having no output schema, the description adequately covers return semantics: identifier source labels, the `unresolved` field, `figi_candidates` for ambiguous matches, and the graceful degradation path. It also explains the internal multi-endpoint cascade and why calling this tool saves manual steps, so an agent has enough context to know what to expect when invoking it.

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

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

Although the schema already describes both parameters with 100% coverage, the description adds substantial meaning: accepted input forms for company (ticker, CIK, ISIN, name), drug name examples, and a critical nuance that bond lookups should pass the issuer name exactly as printed and never the full noun phrase. This meaningfully improves invocation correctness 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 user phrasings and states the core job: resolve a user-spoken name to the canonical/official identifiers other tools require as input. It enumerates supported entity types and specific identifier systems (CIK, LEI, FIGI, RxCUI), so an agent can immediately distinguish it from siblings like entity_profile or validate_claim.

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

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

It gives explicit guidance: 'Use FIRST whenever you have a name but need an ID,' and notes it replaces 2-3 manual lookups, which implies preference over chaining other tools. It does not explicitly name alternative tools or state when not to use it, but the intended trigger conditions are clear enough for an agent.

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

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

Annotations already 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 convey readOnlyHint, idempotentHint, and openWorldHint. The description adds behavioral context by listing the exact return fields (name, genres, dates, status, rating, network, summary, images) and the match behavior. It does not contradict annotations. While it omits potential errors or rate limits, the combination of annotations and description provides sufficient transparency for a search tool.

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 a clear entry point claim. The examples are useful for illustrating usage. It is slightly long with six examples, but each adds context. No unnecessary words. Could be trimmed slightly, but overall well-structured and scannable.

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

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

The description covers purpose, usage, input format, output fields, and distinguishes from ID-based lookups. The presence of an output schema and annotations fills in remaining details. For a single-parameter search tool, nothing critical is missing.

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

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

Schema description coverage is 100% with a single parameter 'query' described as 'TV show name or keyword to search for'. The description emphasizes using the title directly ('takes the TITLE directly'), which adds marginal emphasis but does not significantly extend beyond the schema. Baseline of 3 is appropriate since the schema already handles param meaning.

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

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

The description clearly states the tool searches TV series by name on TVmaze and returns facts. It uses specific verbs ('Look up', 'search'), identifies the resource ('TV SERIES BY NAME on TVmaze'), and distinguishes itself from siblings by claiming to be 'THE entry point for a named series' and contrasting with resolving an ID first. The examples reinforce the verb-resource purpose.

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

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

The description provides strong guidance on when to use this tool: when querying a TV series by name. It gives multiple natural language query examples and explicitly states it is the entry point for named series. However, it does not explicitly state when NOT to use it or mention alternatives like search_movies or get_tv_show for other use cases, so not a full 5.

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

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

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.