crossref

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering safety. The description adds valuable context beyond annotations: the default model (Workers AI Llama-3.3-70b, free), cost implications of passing _apiKey ("BYO key — you pay Anthropic directly"), and the return structure. This is meaningful behavioral 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?

The description is four sentences, logically front-loaded: core capability, default model, optional key behavior, return format, and use cases. Every sentence contributes unique information; there is no fluff or repetition of schema/annotations.

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

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

Given the tool's moderate complexity, the description covers all key aspects: purpose, parameter behavior (defaults, optional key, cost), output shape (per-model object + combined view), and use cases. There is no output schema, so the explicit return format description fills that gap. Annotations cover safety/idempotency. The description is sufficient for an agent to select and invoke this tool correctly.

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

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

Schema description coverage is 100%, so all parameters are documented in the schema. The description adds extra meaning by explaining the default model when 'models' is omitted (not fully in schema) and the cost/fund-flow for _apiKey. This nudges it above the baseline of 3, though it doesn't deeply expand every parameter.

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

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

The description opens with a specific verb+resource: "Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model." This clearly distinguishes it from sibling tools like ask_pipeworx (which asks questions) and compare_entities (which compares entities). The scope and output are immediately 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 states when to use the tool: "Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring." It also provides invocation guidance (default model, optional _apiKey to include Anthropic). However, it does not name alternatives or explicitly say when not to use it, so it misses the high bar of 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 cover read-only, idempotent, and non-destructive behavior, so the description's added value is that it routes, fills arguments, and returns structured answers with stable citation URIs. It also indicates live news coverage and the breadth of sources, which goes beyond the annotation metadata. It does not describe failure modes or citation format details, but the core behavioral disclosure is strong.

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 most important 'PREFER OVER WEB SEARCH' signal and then covers scope, behavior, examples, and alternatives in a logical order. It is somewhat long and includes repetitive phrasing around factual/authoritative questions, but every section earns its place and the density is justified.

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

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

With no output schema, the description still explains the return shape: structured answer with stable citation URIs. It covers scope, examples, alternative tools, and live news behavior, giving an agent enough context to decide when to invoke it. Minor gaps like error handling and latency are not critical for this kind of routing tool.

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

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

The input schema already documents the 'question' parameter thoroughly and lists aliases, with 100% schema description coverage. The tool description reinforces natural-language question usage and provides examples, but it does not add substantial parameter-level meaning beyond the schema. The baseline of 3 is appropriate because the schema carries the burden.

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 routes natural-language questions to one of 5,767 tools across 1,506 verified sources and returns structured answers with citations. It distinguishes itself from web search and sibling tools by emphasizing authoritative structured data with pipeworx:// citation URIs. The examples make the resource and expected behavior concrete.

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

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

The description explicitly says to prefer this over web search for factual, current, or historical questions, and supplies trigger phrases and example queries. It also routes to alternatives: ask_pipeworx_grounded for single-answer evidence-backed questions, and deep_research for broad/multi-part fan-out research. This is clear when-to-use and when-not-to-use guidance.

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

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

Beyond the readOnly/openWorld/idempotent/non-destructive annotations, it reveals important runtime behavior: candidate improvements are active only under test, the last candidate was retired, current behavior exactly matches ask_pipeworx, and results feed comparison against the stable router. This is substantial context beyond what annotations convey.

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

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

Four compact sentences, front-loaded with the core identity ('Beta version of ask_pipeworx'). Each sentence earns its place: identity/equivalence, current state, usage direction, and no-fallback clarification.

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 gives enough context for an agent to decide whether to invoke this beta router: what it routes, current equivalence to stable, and the experimental purpose. It does not spell out the actual response shape, but it references ask_pipeworx's response shape and the stable sibling carries the details, leaving only minor ambiguity.

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

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

The input schema has 100% description coverage: q/text/input are aliases and question is described with its alias list. The description adds the high-level statement that this tool takes the same arguments as ask_pipeworx, but it does not add parameter-level meaning beyond what the schema already provides, so the baseline 3 applies.

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

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

The description clearly identifies this as the beta variant of ask_pipeworx: a universal router covering the same 5,767 tools with the same arguments and response shape. It explicitly differentiates from the stable sibling by its candidate routing improvements, so an agent can tell it apart from ask_pipeworx without inspecting schemas.

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 states when to use it ('when you want the newest routing'), says to use it exactly like ask_pipeworx, and notes that currently no candidate is active so it matches the stable router. It also clarifies that it does not fall back to another tool because it is a complete working router.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description reveals the exact success return shape with fields like evidence and confidence, and details the refusal contract with specific refusal_reason enums. It also discloses the 'EXTRACTS the answer using ONLY what the tool result contains' behavior and the extra LLM call cost, giving the agent a rich behavioral model before invocation.

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

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

The description is compact yet information-dense, with every clause earning its place: mode, routing, extraction constraint, success/refusal shapes, use cases, and cost tradeoff. The most important differentiator (grounded, refusal-capable) appears first, and the alternative tool is cited naturally rather than requiring the reader to infer it.

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 6 alias parameters, rich annotations, and no output schema, the description fully compensates by explaining the return contract, refusal scenarios, and expected usage context. It covers what an agent needs to decide whether to call this tool, what to pass, and what to expect back, including failure modes.

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

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

Schema description coverage is 100%, with each parameter labeled as an alias for 'question' and the question parameter explaining it accepts natural language with aliases. The tool description itself adds no parameter-specific meaning, but since the schema fully documents the parameters, 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 names a specific, distinctive behavior: a hallucination-resistant answer mode that extracts the answer only from the retrieved tool result. It clearly differentiates from the sibling ask_pipeworx by emphasizing grounded answers with evidence and refusals, and explicitly says it uses the same routing as ask_pipeworx while adding a strict extraction guarantee.

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

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

The description explicitly states when to use the tool: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete domains like financial verdicts, legal claims, medical lookups, and public statements. It also gives the alternative condition: 'prefer ask_pipeworx for casual lookups' and explains the cost tradeoff of one extra LLM call, making the selection decision 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?

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false), the description discloses extensive behavioral traits: resolver contract with confidence levels and alternatives, low-confidence short-circuiting, closed-market status, wide-spread illiquidity flag, cancellation rule risk, news fallback behavior, and response shapes. This far exceeds what annotations provide and gives critical safety context.

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

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

The description is long but well-structured with clear section headers (RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loaded with the core purpose. It is dense with valuable detail, though slightly oververbose in repeating fan-out examples; still, every section adds substantive operational knowledge.

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

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

Given the tool's complexity (multiple response shapes, fallback paths, error statuses) and the absence of an output schema, the description is exceptionally complete — covering market data, analysis warnings, evidence structure, resolver confidence, parent events, news fallbacks, and even settlement-rule risk. No obvious gaps that would lead 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 input schema already covers all three parameters with 100% description coverage, including examples for market and defaults for depth and include_raw. The description adds no parameter-specific detail beyond the schema, so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It further enumerates concrete use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and distinguishes itself from sibling tools by focusing on data-backed research rather than arbitrage, edges, or tracking.

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 with the 'Use for...' directive, providing clear context. However, it does not mention alternative tools or when NOT to use it, so it falls short of the highest bar that requires explicit when-not/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?

The description discloses data sources (SEC EDGAR/XBRL, FAERS), correct handling of off-calendar fiscal years, sorting by primary metric, and citation URI returns. This goes far beyond the annotation hints and gives the agent real behavioral expectations.

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

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

The description is long but every sentence carries meaningful information—query patterns, data sources, edge-case handling, output structure, and efficiency. It is front-loaded with examples and uses formatting sparingly, making it dense and well-structured.

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

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

Even without an output schema, the description covers what is returned (paired data, citation URIs), how results are sorted, and what data sources feed each entity type. This is a complete picture for a tool of this complexity.

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

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

Schema coverage is 100% with clear parameter descriptions, so baseline is 3. The description adds type-specific behavioral detail (e.g., company pulls 10-K revenue/net income, drug pulls FAERS counts), enhancing semantic understanding beyond the schema.

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

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

The description opens with concrete query patterns and states 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call'. It distinguishes the tool from sequential single-pack lookups by emphasizing parallel execution and specific entity types. This makes the tool's scope 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?

It explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear when-to-use guidance. The described query examples and the note about replacing 8–15 sequential lookups further reinforce the intended usage context.

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

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

Annotations signal read-only, open-world, idempotent, non-destructive behavior; the description adds substantial behavioral context on top: account/payment gate, structured-source limitation, explicit gaps[] for unanswered facets, resolvable citations, semantic excerpting, depth-dependent hops, timing estimates, and contradictions[] scanning. 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?

Long but information-dense; nearly every clause adds operational value (auth, scope, outputs, alternatives, timing, citation behavior). It is front-loaded with the account requirement and the ask_pipeworx fallback. The length is justified for a tool this complex, though it could be lightly restructured into clearer paragraphs.

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 specifies the findings-packet fields, gaps[], contradictions[], citation resolvability, excerpting behavior, latency, and depth semantics. An agent can select, invoke, and set user expectations for this tool without needing additional 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?

Input schema has 100% coverage of both parameters and detailed enum descriptions, so the baseline is 3. The description adds value beyond the schema by giving timing expectations per depth, clarifying the paid tier requirement, and reinforcing that broad/multi-part questions are the intended use — though it does not need to add format-level syntax.

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

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

States a specific verb and resource: grounded multi-source research across Pipeworx's structured data sources, with a clear mechanism (decompose into facets, route to tools in parallel) and outputs (findings packet). It explicitly distinguishes itself from open-web search and from ask_pipeworx, so an agent can tell siblings apart without opening their schemas.

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?

Gives explicit when-to-use guidance: best for broad/multi-part questions over structured data, use ask_pipeworx for single lookups and for unsigned-in users, and pair with ask_pipeworx for current events. This covers use, non-use, and the sibling alternative in clear terms.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the agent knows it's safe. The description adds behavioral detail: returns top-N results with full input schemas and curated examples, ready to call directly without a second schema lookup. This goes beyond the annotations to clarify the output and convenience behavior.

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

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

The description is three sentences, each adding distinct value: purpose, usage context, and return behavior. It is front-loaded with the core function and ends with a clear 'call first' directive. 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?

For a simple discovery tool, the description covers purpose, usage, output format, and provides a concrete instruction for when to invoke it. The schema covers all parameters at 100%, and annotations cover safety, so the description is sufficient for an agent to select and call it correctly.

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

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

Schema description coverage is 100%: the schema documents query and its aliases (q, task, search, description) and limit with default/max. The description only restates that you describe the data/task, adding no new parameter semantics beyond what the schema already provides. Baseline 3 applies.

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

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

The description clearly states the tool's function: 'Find tools by describing the data or task.' It further specifies the categories of data covered and describes the return format (top-N tools with schemas), distinguishing it from sibling tools like search_within or deep_research which perform direct searches/research rather than tool discovery.

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

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

The description explicitly provides usage context: 'Use when you need to browse, search, look up, or discover what tools exist' and instructs to 'Call this FIRST when you have many tools available...'. This gives clear guidance on when to use it, though it doesn't explicitly name sibling alternatives or state when not to use it, so a 4 rather than 5.

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

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

Even with readOnlyHint and idempotentHint already set, the description adds substantial behavior: parallel fan-out across sources, USPTO patent soft-fail, empty FDA section being expected, GDELT-to-GNews fallback, and resolved:false for private companies. This gives the agent accurate expectations beyond the annotations.

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

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

The description is long, but the tool is complex and there is no output schema to carry return-structure documentation. It is front-loaded with trigger phrases and the key routing rule before enumerating sources; minor redundancy with parameter schema costs it a point.

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 effectively documents the output shape, source-by-source behavior, failure semantics, and input edge cases. An agent has enough context to call it correctly and interpret results accurately.

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

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

Schema coverage is 100%, but the description meaningfully expands both parameters: type is fully interchangeable, value accepts ticker/zero-padded CIK/name, name resolution happens via SEC EDGAR, and the private-company case is clarified. It even notes future person/place support.

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

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

The description clearly identifies the action: build a full cross-source profile of a US public company, illustrated with explicit trigger phrases like 'tell me about X' and 'research Acme'. It distinguishes itself from single-source lookups by emphasizing the 'ONE parallel call' cross-source nature.

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 routing guidance is explicit: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It lacks a clear when-not-to-use clause or named sibling alternatives such as compare_entities or deep_research, so it does not fully close out alternative selection.

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

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

Annotations already declare destructiveHint: true and readOnlyHint: false, so the description carries a lower burden. It adds context about deleting previously stored memory and clearing sensitive data, but these are use-case clarifications rather than deeper behavioral disclosures (e.g., irreversibility, confirmation steps). No contradiction exists, but the added value is modest.

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

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

The description is two sentences, front-loaded with the primary action, and contains no filler. Every sentence earns its place: the first states purpose, the second provides usage context and related 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 one-parameter, non-output-schema tool with annotations covering destructive behavior, the description is sufficiently complete. It explains what the tool does, when to use it, and how it relates to siblings. No major gaps remain for an agent to invoke it correctly.

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

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

Schema description coverage is 100% — the only parameter 'key' is described as 'Memory key to delete.' The tool description adds no further semantic nuance beyond restating the key concept, so the schema adequately handles parameter explanation. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'Delete a previously stored memory by key.' This clearly distinguishes the tool from siblings like 'remember' (store) and 'recall' (retrieve), leaving no ambiguity about its function.

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 conditions for use ('when context is stale, the task is done, or you want to clear sensitive data') and names related tools ('Pair with remember and recall'). It lacks a direct 'when not to use' clause, so it doesn't fully meet the 5-level criteria, but the guidance 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 already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds useful behavioral context by stating it 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format', which clarifies the network access and output nature. It does not mention edge cases or rate limits, but given annotation coverage, this is solid.

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: it leads with the primary purpose, explains the process, states the output format, and lists use cases. Every sentence contributes value without redundancy or 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?

The tool is simple (2 params, no output schema), annotations cover safety, and the description fully explains the purpose, process, output, and use cases. It is complete enough for an agent to select and invoke the tool correctly without further clarification.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-specific details beyond the schema; it only mentions 'any URL' in passing. No additional semantic value is provided for url or max_links.

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+scope: 'Generate a production-ready llms.txt file for any URL' and explains the process and output. However, it does not explicitly distinguish itself from sibling tools like ai_visibility_check or scan_competitor_ai_presence, so it misses the top score for sibling differentiation.

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

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

The description provides clear usage contexts ('Useful for: 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 lacks explicit when-not-to-use or alternative tool references, so it earns a 4 rather than a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds behavioral context beyond this by specifying the result limit ('5 most recent works') and the fields returned (titles, authors, DOIs, publication dates), which are useful for the agent's expectations.

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

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

The description is two sentences, front-loaded with the core action and scope. Every word contributes value, with an example ISSN and a clear list of returned fields. No fluff or redundancy.

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

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

The tool is simple with one parameter, an output schema exists, and annotations provide safety profile. The description adequately covers the purpose, result set size, and returned fields, making it 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 schema provides 100% coverage for the only parameter 'issn' with a description and example. The description reinforces the ISSN-based lookup but does not add new semantic detail beyond the schema. 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's function: 'Get the 5 most recent works from a journal by ISSN'. It specifies the verb, resource type (works), and input identifier (ISSN), and the scope (5 most recent). This distinguishes it from siblings like get_work (single work) and search_works (broad 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 gives a clear context for use: obtaining recent journal works via ISSN. It does not explicitly mention alternatives or exclusionary cases, but the specificity of the use case provides sufficient guidance for when to select this tool among the siblings.

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

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

Annotations already declare the tool as read-only, idempotent, open-world, and non-destructive. The description adds a concrete DOI example and enumerates the returned fields, which gives behavioral context beyond the safety annotations. No contradiction exists.

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

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

The description is two sentences, front-loaded with the verb and resource, and contains no redundant or vague wording. It is appropriately concise and well-structured.

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

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

The tool is simple with one parameter, rich annotations, and an output schema. The description covers the purpose, the lookup key, and the type of data returned, making it 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 the single 'doi' parameter with type, description, and example. The description repeats this example and adds no new parameter-level information, so the baseline 3 applies.

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

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

The description uses a specific verb 'Get' with a clear resource 'full metadata for a publication by DOI' and lists returned fields. This distinguishes it from sibling tools like search_works (which searches without a DOI) and get_journal (which targets journals).

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

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

The description clearly indicates the use case: retrieving metadata when you have a DOI. It provides a concrete example. However, it does not explicitly mention when not to use it or compare alternatives, so it lacks exclusion 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 destructiveHint=false, establishing safety. The description adds valuable behavioral context by specifying the exact return fields and the default behavior of listing only active subscriptions, going beyond the annotations.

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

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

The description is two sentences, front-loaded with the core purpose, and every sentence adds value—return fields and usage guidance. No filler or redundancy.

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

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

For a simple list tool with one optional parameter and no output schema, the description fully covers the purpose, return structure, and practical use cases. The annotations address safety and idempotence, leaving no significant gaps.

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

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

The input schema includes a full description for the only parameter (include_inactive), so schema coverage is 100%. The description does not add additional parameter semantics beyond the schema, though it reinforces the active-only default. 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 'List the caller's active subscriptions' with a specific verb, resource, and scope. It also lists the returned fields, making the tool's function unambiguous and distinct from sibling tools like subscribe and unsubscribe.

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

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

The description provides explicit usage scenarios: 'review what you're monitoring before adding more' and 'find an id to cancel.' However, it does not name alternatives or provide when-not guidance, so it lacks the explicit exclusion criteria required for a 5.

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

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

Annotations are all false, providing no safety signals, so the description carries the full burden. It discloses crucial behavioral traits: returns a claim_token for later status checks, is rate-limited to 5 per identifier per day, is free, doesn't count against quota, and the team reads digests daily. This goes far beyond structured fields.

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

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

The description is longer than average but every sentence earns its place, covering usage criteria, exclusions, claim_token flow, rate limits, and free usage. It is front-loaded with the core purpose in the first sentence and remains organized. Slightly verbose, but justifiably so for a multi-faceted feedback tool.

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

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

With no output schema, the description adequately covers the return behavior (claim_token for anonymous filing, status/change resolution on later lookup). It explains the full feedback lifecycle, including rate limits and roadmap impact, making it complete for a complex 4-parameter tool with nested objects and optional params.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful context: explains that filing without an account returns a claim_token and how to use it later ('pass it back as pipeworx_feedback({claim_token:"pwfb_…"})'). It also advises describing issues 'in terms of Pipeworx tools/packs', which guides the message and context parameters. This is a clear improvement over raw schema.

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

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

The description clearly states the tool's purpose with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It distinguishes itself from siblings by focusing exclusively on feedback for Pipeworx tools, with no overlapping tool among the siblings.

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

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

Provides detailed 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).' It also explicitly disambiguates from other MCP servers and states what not to do ('don't paste the end-user's prompt'), offering clear 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 read-only and idempotent. The description adds meaningful context: self-aggregating signal, derived from CF analytics-engine, no PII, and caching behavior (5min-1h depending on window). This goes beyond annotations and gives the agent useful expectations about data freshness and privacy.

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 with a strong lead, a concise output summary, bulleted use cases, and a compact caveat set. Every sentence earns its place; no fluff or repeated schema 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 read-only tool with one optional parameter and no output schema, the description covers purpose, outputs, use cases, privacy, and caching. It is fully adequate for an agent to understand when and how to invoke it.

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

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

Schema coverage is 100% and the window parameter has a clear enum and default. The description adds interpretive value by explaining the trade-off between shorter and longer windows, which is not present in the schema's enum definition.

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

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

The description opens with a clear, specific purpose ('What other AI agents are calling on Pipeworx right now') and lists exact outputs ('top tools, top packs, and total call volume'). It clearly distinguishes itself from sibling tools like ask_pipeworx or discover_tools by focusing on aggregated trending signal.

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 three explicit use cases (discovering hot data sources, confirming canonical tools, aligning with agent needs) and explains how window choice affects results ('shorter windows surface what's hot right now; longer windows show steady-state demand'). It doesn't name specific alternatives for exclusion, but gives clear guidance on when to use it.

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

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

Annotations already declare read-only/idempotent behavior; the description adds substantial operational context: partition filter drops placeholder slugs and returns null above 20%, semantic anchor requires ≥0.30 Jaccard similarity and surfaces skipped_low_similarity, and fill check warns that realizable_edge_pp ≤0 means do not trade. No contradiction with annotations.

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

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

Long but front-loaded with purpose and argument modes. Every sentence contributes operational detail (filters, thresholds, response fields) and the structure uses bolded labels. Slightly verbose but no redundancy.

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

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

Despite no output schema, the description specifies response fields (opportunities[], partition_check, fill_check details) and links to fill_risk for sizing, making it self-sufficient for invocation and interpretation.

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

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

Schema covers both params with descriptions, but the description adds concrete examples (event slugs like 'fed-decision-may-2026', seed questions like 'Strait of Hormuz traffic returns to normal'), mode semantics, accepted URL format, and the relationship between event/topic, going well beyond the schema.

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

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

The description opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes three invocation modes (trending_scan, event, topic) and references polymarket_fill_risk for sizing, separating it from siblings.

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

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

Provides explicit usage guidance: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It marks event as recommended for a specific market, explains when cross-event mode is better, and directs custom sizing to polymarket_fill_risk.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint:false. The description goes well beyond these by detailing model-family mechanics (e.g., per-sport α values), per-opportunity fields (edge_pp_net, kelly_fraction_half capped at 0.25), tradeable-edge knob behavior, 24h-move warnings, and KV-level caching (1h keyed on all knobs). It also surfaces edge cases like the unreliable Fed signal at meeting-month horizons. 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 highly dense and logically structured: model families are numbered, response segments are grouped, and the top-level response layout is provided. Every sentence carries unique domain-specific information (e.g., per-sport α, placeholder-slug filtering, diagnostics funnel counters). It could be slightly more scannable with headers, but 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 the tool's complexity (9 knobs, three model families, no output schema), the description thoroughly compensates. It specifies the top-level response structure (by_segment, fed_candidates/fed_note, _diagnostics), lists exact per-opportunity fields, explains why segments can be empty, and documents filter interactions. An agent has enough information to invoke the tool and interpret its response without ambiguity.

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

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

The input schema already provides descriptions for all 9 parameters, so the baseline is 3. The description adds meaningful beyond-schema context: it explains how min_partition_leg_kelly applies to basket legs rather than the parent level, why partition_overround parent kelly_fraction_half is always 0, how slippage_pp is deducted from raw edge, and the interplay of min_liquidity/max_spread_pp as tradeability filters. This lifts it above the baseline.

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

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

The description opens with a specific verb+resource+scope: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly positions itself as an opportunity-discovery tool for daily betting, which distinguishes it from siblings like polymarket_arbitrage or polymarket_edge_tracker. The statement 'without paging hundreds of markets' adds practical value.

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 frames the use case ('what should I bet on today') and tells agents they can discover opportunities without exhausting pagination. It also explains when certain outputs appear (Fed candidates are excluded from ranking, diagnostics explain empty segments), but it does not explicitly name sibling tools or state when NOT to use this tool in favor of another.

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 readOnlyHint annotation by explaining the response shape (tracked, expired, snapshot_dates), the signed edge_pp_net semantics, snapshot write behavior (cache-miss), and historical limits (60-day TTL, start time). This provides deep behavioral context without contradicting the annotations.

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

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

The description is long but structured into Args, RESPONSE, and LIMITS sections. The Arg section repeats schema information, but the response and limits sections are essential due to the lack of an output schema. Overall, it is dense but well-organized.

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 accounts for the tool's complexity: no output schema is compensated by a detailed response breakdown, data gaps are explained via snapshot_dates, and edge cases like TTL and daily-close computation are disclosed. It leaves little ambiguity for an agent.

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

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

Schema coverage is 100% with both parameters described. The description repeats the defaults and adds 'max 30' but omits the min clamp of 2 that the schema provides. It adds minimal value beyond the schema's already-detailed parameter descriptions.

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

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

The description clearly defines the tool as 'edge persistence and decay telemetry' and answers a specific question: 'how long has this edge existed and is it shrinking?' This distinguishes it from sibling tools like polymarket_edges (which likely shows current edges) by focusing on the time-series aspect.

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

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

The description implies usage for evaluating edge age with the sentence 'a fresh wide edge and a 3-week-old wide edge are different trades', but it does not explicitly name alternatives or state when not to use it. The context is clear but lacks explicit exclusions.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description goes far beyond by detailing exact return fields (top_of_book, vwap_fill_price, slippage_pp, etc.) and explaining behavioral nuances like 'forced_directional_risk naming the legs most likely to strand you unhedged.' 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 dense—every sentence adds distinct value. It front-loads the core purpose, then methodically covers constraints, both modes, return values, and usage context. No fluff or repetition; the length is justified by the tool's complexity.

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

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

With no output schema, the description fully inventories return values for both modes (e.g., theoretical_sum, capture_ratio, thin_legs, max_clean_notional_usd). It explains the risk model and the meaning of key terms like 'settlement notional.' For a max-complexity tool (two modes, 4 params), 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?

While schema coverage is 100%, the description adds meaning beyond schema: it explains that `size_usd` is 'max spend on buys, target proceeds on sells' in single-market mode and 'settlement notional S' in basket mode, plus clarifies `side` defaults for each mode. This interpretive layer is not present in the schema.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes single-market and basket modes, and explicitly references sibling tools (polymarket_arbitrage, polymarket_edges) to differentiate when this tool is used.

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 THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Even explains the risk of partial fills converting an arb into unhedged directional positions, which justifies the tool's necessity.

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

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

The annotations already declare this read-only and idempotent, and the description adds substantial behavior beyond that: compatibility codes, gross-vs-net fee disclosure, unclassified-leg exclusion, temporal alignment semantics, and the warning that safety fields can be non-empty even when pairs are returned. No contradictions with annotations.

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

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

The description is long but densely packed with essential caveats, response-field explanations, and operational semantics. It is front-loaded with the core purpose, then modes, then safety disclosures, and ends with an honest rarity warning. Every section earns its place given there is no output schema to lean on.

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 fully explain return values, and it does: leg-by-leg prices, top_spreads_pp with per-entry flags, compatibility codes, temporal alignment, skipped counters, and the fees note. It also handles edge cases like unknown legs never being paired and null temporal alignment meaning unknown rather than aligned. This is complete enough for an agent to call 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 baseline is already solid. The description adds meaning by explaining the `topic` enum's semantic role as pre-mapped macro shortcuts, that explicit ticker/slug parameters override the mapped side, and that both modes share the same matching logic. This is useful but mostly confirms what the schema already communicates.

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 the exact resource (cross-venue spread between Kalshi and Polymarket) and the operation (computing the delta in probability for the same resolving question). It also details two input modes and the output structure, clearly distinguishing its Kalshi–Polymarket focus from sibling trading 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 clearly explains when to use `topic` shortcuts vs explicit `kalshi_event_ticker`/`polymarket_event_slug` pairing, and notes that both modes run the same matcher. It warns that pre-mapped topics are not automatically tradeable, but it never explicitly contrasts this tool with alternatives like polymarket_arbitrage or polymarket_edges, so the when-not-to-use guidance is incomplete.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering the safety profile. The description adds valuable beyond-annotation context: scoping to user identifier ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the dual retrieval/list behavior. It doesn't detail return format or missing-key behavior, so a 4 is appropriate.

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, each earning its place: core action in the first, use cases in the second, scoping and related tools in the third. Front-loaded and free of filler.

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

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

Given the tool's low complexity (one optional parameter, no output schema, strong annotations), the description is complete: it states the purpose, typical usage, scoping, and relationships to remember/forget. An agent can accurately select and invoke this tool without further clarification.

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

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

The input schema fully documents the 'key' parameter with 100% coverage, including the instruction to omit it to list all keys. The description adds illustrative examples but no additional syntactic or semantic detail beyond what the schema already provides. Baseline 3 holds.

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

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

The description clearly states the tool's function: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It names the resource (saved memories) and the action (retrieve/list), and explicitly references sibling tools (remember, forget), distinguishing it from them.

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

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

It provides explicit when-to-use guidance: 'Use to look up context the agent stored earlier' with concrete examples (target ticker, address, research notes). It also names alternatives (remember to save, forget to delete), giving a clear workflow without needing to inspect other tool descriptions.

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 enriches the read-only annotation by describing the persistent feed, the evaluator's role, and the mark_read side effect that affects subsequent calls. It also mentions polling suitability, adding operational context beyond the annotations.

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

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

The description is concise and well-structured, with each sentence covering a distinct aspect: core function, return payload, filters, mark_read behavior, and alternative endpoint. There is no redundant or vague language.

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 return values, filtering, mark_read behavior, and polling suitability, which compensates well for the lack of an output schema. Remaining parameters are documented in the schema, making the overall guidance complete.

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

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

The schema already covers all five parameters with 100% coverage, so the baseline is 3. The description adds value by explaining the effect of mark_read on the next call and highlighting the type and since filters, going beyond the schema descriptions.

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

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

The description clearly states the tool pulls fired events from the user's subscription feed and returns the most recent alerts with source, citation_uri, and raw payload. It is specific about the resource and action, but it does not explicitly distinguish itself from sibling tools like recent_changes.

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

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

The description gives clear context: it says polling works fine and notes an alternative GET endpoint for scripts/dashboards. However, it does not provide explicit exclusions or compare against sibling tools with overlapping functionality.

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/non-destructive; description adds dynamic behavior: fan-out to three sources, GDELT→GNews fallback on rate-limit/5xx, and USPTO soft-fail due to PatentsView sunset. Also explains return format (changes[] grouped by source, total_changes, citation URIs). 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?

Though single-paragraph, it's front-loaded with user-intent examples and packs essential details (federated sources, fallback behavior, input format, output shape, alternative tool) without fluff. Every sentence carries operational value.

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

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

Covers input formats, sources, fallback, output structure, and usage boundary vs entity_profile. With no output schema, it adequately describes the return value, making it self-sufficient for an agent.

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

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

Schema provides full descriptions for all three parameters (type enum, since format/examples, value ticker/CIK), so baseline 3 applies. Description adds broader context (e.g., that since drives the window across all sources) but doesn't add parameter-level syntax beyond schema.

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

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

Description opens with natural-language query examples then clearly states it's a 'change feed for a company in the last N days/weeks/months in ONE parallel call', specifying sources (SEC EDGAR, GDELT/GNews, USPTO). It explicitly distinguishes from entity_profile ('Use entity_profile instead when you want the static 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?

Provides explicit when-to-use via query examples and an explicit alternative: 'Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window.' This covers when-not and alternative in one phrase.

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 (readOnlyHint false, idempotentHint true, destructiveHint false), the description adds key behavioral context: storage is scoped by identifier, anonymous sessions retain memory for 24 hours, while authenticated users get persistent memory. This is meaningful added context 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?

Every sentence earns its place: what it does, when to use, storage format, persistence rules, and companion tools. No redundancy, and critical information is front-loaded.

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

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

For a simple 2-parameter tool with no output schema, the description fully covers purpose, usage, storage behavior, persistence, and integration with siblings. It is complete enough for an agent to decide when and how to use it.

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

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

Schema coverage is 100% with descriptive parameter names and examples. The description reinforces semantics by mentioning key-value pairs and giving example values (ticker, address, preference), adding slight extra meaning beyond the schema.

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

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

The description clearly states a specific verb ('Save data') and resource ('data the agent will need to reuse later'), distinguishing it from sibling tools like recall (retrieve) and forget (delete). It also mentions the key-value storage model, making the purpose unambiguous.

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

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

It explicitly says 'Use when you discover something worth carrying forward' and provides concrete examples. It also names companion tools ('Pair with recall to retrieve later, forget to delete'), giving direct alternative guidance.

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

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

The description discloses rich behavioral details beyond the annotations: it notes graceful degradation when GLEIF/OpenFIGI are unavailable, explains behavior on ambiguous matches by returning figi_candidates and asserting nothing, and states that unresolved identifiers are listed under `unresolved` rather than omitted. This goes well beyond readOnly/openWorld/idempotent 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 and dense, with many parentheticals and examples, but it is well-structured and front-loaded with the core purpose and usage rule. Every sentence adds functional context for a complex, multi-source tool, though some phrasing could be tightened.

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 two entity types, multiple identifier sources, and ambiguity scenarios, the description is remarkably complete: it covers supported types, input forms, behavior on ambiguity, unresolved identifiers, graceful degradation, and internal cascading. Even without an output schema, the agent has enough context to call the tool correctly.

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

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

The input schema already covers 100% of parameters, and the description adds meaningful usage context: examples like ticker, CIK, or name for company, and brand or generic name for drug. It also adds important caveats like passing the entity name only and not trailing security-class words, which materially improves correct invocation.

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

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

The description clearly states that the tool resolves user-spoken names to canonical identifiers, using a specific verb and resource: "resolve a user-spoken NAME to the canonical/official identifiers other tools require as input." It also distinguishes itself by covering multiple supported types and explicitly positioning itself as the first step before other tools.

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

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

The description gives explicit guidance: "Use FIRST whenever you have a name but need an ID." It also explains that the tool replaces 2-3 manual lookups. It does not, however, name sibling alternatives or describe when not to use this tool, leaving some exclusion criteria implicit.

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

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

The description discloses that it calls ai_visibility_check for each entity, ranks results by score, and returns a list including score, confidence, and signal density. This goes beyond the annotations (readOnly, idempotent) to explain internal behavior and output.

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

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

Three sentences, front-loaded with the main purpose, includes a concrete example and output summary, with no 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?

The description covers the tool's purpose, process, use case, and return format. It omits some operational details like external API usage for Anthropic, but those are captured in the schema parameters, so the description is sufficiently complete given the schema's 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?

The input schema already covers all four parameters with descriptions (100% coverage). The tool description repeats the first-entry-as-subject concept already present in the schema's entity parameter description, adding no new parameter semantics.

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

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

The description clearly states a specific verb, resource, and scope: 'Compare AI visibility across multiple entities side-by-side.' It distinguishes itself from sibling ai_visibility_check by emphasizing multi-entity comparison and ranking, and from compare_entities by focusing on AI visibility specifically.

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

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

It explicitly identifies a use case for competitive AI-marketing audits and provides an example query. It implies that ai_visibility_check is for single-entity probes while this tool aggregates them, though it doesn't explicitly exclude single-entity 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 indicate safe read-only, idempotent, open-world behavior. The description adds significant behavioral context: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed reports timeouts. This goes beyond the annotations and sets accurate expectations.

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

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

The description is fairly long but every sentence serves a purpose: it front-loads the core purpose, then usage context, then output fields, then limitations. It could be tightened slightly by removing some redundancy, but for a complex multi-source tool it remains well-structured.

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

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

Given no output schema, the description compensates by enumerating the summary block fields (is_latest, license, published_at, etc.) and mentioning links and alternative versions. It also covers the NPM-only scope, partial failure behavior, and timeout characteristics, making it complete for the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description reinforces that the package parameter is an npm package name and that version defaults to latest, but these are already in the schema. It adds the ecosystem limitation (NPM only), but that's more a behavioral note than parameter semantics.

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

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

The description clearly identifies the tool as a composite 'should I add this npm package' check, combining deps.dev and bundlephobia data. This specific verb+resource focus uniquely distinguishes it from all sibling tools, none of which serve a similar purpose.

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

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

Explicitly states when to use: whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'. Also gives a clear fallback for non-NPM ecosystems (PyPI/Maven/Cargo/Go), effectively providing a when-not-to-use guideline for those cases.

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

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

Beyond the readOnly/idempotent annotations, the description discloses the embedding model (BGE-base-en), chunking (500-char overlapping windows), truncation at 200K chars with a flag, and the return structure (passages with offsets and similarity scores). 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 information-dense but not bloated; it front-loads the core action, then provides use case, workflow, and implementation details. Every sentence earns its place.

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

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

For a tool without an output schema, the description adequately explains return values (top-N passages with offsets/scores), truncation behavior, and the recommended integration with ask_pipeworx_grounded. It leaves no critical gaps for a search operation.

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

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

Schema coverage is 100%, providing a baseline of 3. The description adds real-world examples for text and clarifies query as natural-language, which helps an agent understand parameter usage, but it largely reinforces schema details rather than adding entirely new semantics.

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

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

The description clearly states the tool performs semantic search inside a fetched record, with specific examples (SEC 10-K, article). It distinguishes from sibling tools by emphasizing 'INSIDE' and pairing with ask_pipeworx_grounded as a complementary workflow.

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

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

Explicitly says when to use: when the record is too big for the prompt, and explains the benefit of saving context with offsets for verification. It also names the complementary tool ask_pipeworx_grounded, indicating a recommended workflow and alternative.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is known. The description adds meaningful behavioral context beyond annotations: title-scoped ranking, sort/filter capabilities, and the return fields. No contradictions with annotations.

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

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

The description is three sentences, front-loaded with the core purpose, then expands into usage details and examples. No wasted words; each clause earns its place. The structure flows naturally from purpose to usage to returns.

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 8-parameter complexity and the presence of an output schema, the description is remarkably complete. It covers the main search behavior, sorting/filtering options, the title-scoped special case, and the return fields. It even includes concrete examples for common queries, making it easy for an agent to map natural language requests to parameters.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by connecting parameters to real-use scenarios (e.g., 'most-cited papers on transformers' for sort=citations, 'papers on LLMs since 2024' for from_date), and it clarifies the distinction between title and query. This goes beyond the schema's per-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 opens with a specific verb+resource statement: 'Search academic papers, books, and datasets via Crossref.' It also immediately distinguishes a specialized title-scoped search mode, which sets it apart from sibling tools like get_work or get_journal that retrieve specific works.

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 when-to-use guidance: 'For "search works titled X" / finding a SPECIFIC paper by its title, pass title.' It also gives concrete examples for sorting and filtering use cases. However, it does not explicitly mention alternative tools or when not to use this tool (e.g., when you already have a DOI, use get_work), so it stops short of full exclusion 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 indicate non-readonly, idempotent, and non-destructive behavior. The description adds valuable behavioral context beyond annotations: anonymous and BYO accounts cannot persist subscriptions, SMS requires phone verification and has a 10/day cap, and the feed channel is always on. These details help the agent anticipate side effects and prerequisites without contradicting the annotations.

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

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

The description is fairly long but carries dense, non-redundant information: purpose, return value, auth requirement, supported types with examples, and delivery options. It is front-loaded with the core action, though some tightening could make it easier to scan.

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

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

This is a complex tool with a nested delivery object and multiple type-specific parameter shapes. The description covers the main use cases, auth requirements, delivery channels, and return value, while leaving webhook signing and auto-disable details to the schema. Given the schema's richness, this is adequately complete, though it does not mention duplicate-subscription behavior (covered by the idempotent hint).

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% parameter coverage, with detailed descriptions for the type enum, params object, and delivery object. The description echoes much of this information (e.g., items:['5.02'], topic:'fed', series_id:'UNRATE') and adds the return of the subscription id, but it does not significantly extend 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 'Create a proactive monitoring subscription to a live-data event stream' and 'Returns the new subscription id,' which clearly specifies the action and resource. This distinguishes it from sibling tools like list_subscriptions, unsubscribe, and recent_alerts.

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

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

The description explains the required context: a Pipeworx OAuth account is required, types and parameter examples are enumerated, and delivery channels are described. It also mentions pulling alerts via recent_alerts for the always-on feed. However, it does not explicitly contrast when to use subscribe versus listing or unsubscribing, so it stops short of full alternative guidance.

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

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

Annotations already declare the tool read-only, open-world, idempotent, and non-destructive. The description adds valuable context beyond those flags, such as the return value structure (category-bucketed example questions with tool + argument shapes), the live catalog source, and the 'no arguments vs. topic' behavior, which together give 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?

The description is longer than minimal but front-loads natural language queries and the 'onboarding entry point' context. Every sentence contributes useful information—purpose, return content, argument behavior, and when to use it—so it is structured and purposeful, though slightly verbose for a single optional parameter.

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 what the tool returns (category-bucketed example questions with exact tool and argument shape), how to invoke it (with/without `topic`), and when to use it first. It also lists a wide range of covered categories, making the tool's scope unambiguous and complete for an onboarding assistant.

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

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

The schema description already covers the `topic` parameter fully, including allowed values and the omission behavior. The tool description reinforces this with examples like 'finance', 'pharma', 'betting' and adds the 'full spread' nuance, but the marginal added meaning beyond the schema is minimal, so the baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as the onboarding entry point for discovering what Pipeworx can do, with specific verbs like 'returns category-bucketed example questions' and lists concrete categories. It distinguishes itself from siblings by framing its role as the 'first' tool to use when unfamiliar with Pipeworx and explicitly references learning to call meta-tools.

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

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

The description gives explicit usage context ('Use this FIRST when you do not yet know what Pipeworx can do') and shows how to call it with or without the `topic` argument. It does not provide explicit when-not-to-use guidance or name a direct alternative, but the recommended first-use positioning makes the usage clear enough.

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

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

The description adds significant behavioral details beyond annotations: ownership enforcement ('you can only cancel your own subscriptions') and the deactivation behavior ('The row is deactivated (not deleted) so its historical events stay available via recent_alerts'). This complements the annotations (idempotentHint, destructiveHint) with concrete consequences.

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 core action, and every sentence adds value: the first states the operation, the second covers ownership and persistence behavior. No waste.

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 no output schema, the description covers the essential context: what it does, ownership restrictions, the deactivation mechanism, and the downstream effect on recent_alerts. This is complete for an agent to select and invoke it correctly.

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

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

The schema already provides 100% coverage for the single parameter 'id' with a clear description ('Subscription id (uuid) returned by subscribe'). The tool description does not add additional parameter semantics beyond restating 'by id', which is redundant and yields the baseline score.

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

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

The description clearly states the action ('Cancel a subscription by id') with a specific verb and resource. It distinguishes itself from sibling tools like subscribe and list_subscriptions by focusing on cancellation, and the mention of 'recent_alerts' contextualizes the effect.

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

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

The description clearly implies when to use the tool (to cancel a subscription) and provides context about ownership enforcement. However, it does not explicitly state alternatives or when not to use it, though the sibling list makes it easy to infer.

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

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

The description discloses detailed behavioral traits beyond the annotations: the SEC EDGAR + XBRL fast path, the grounded pipeline fallback, the full verdict set, pipeworx:// citations, and the crucial distinction between could_not_verify (verification failed) and unsupported (no source). This adds significant context beyond the read-only/idempotent annotations.

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

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

The description is dense but logically organized: trigger phrases, usage, routing behavior, return values, and critical caveats. Every sentence adds value without redundancy, making it appropriately sized for the tool's complexity.

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

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

Given no output schema, the description fully covers return values (verdict types, citation, reasoning) and explains error behavior (could_not_verify vs unsupported). It also mentions that it replaces multiple sequential calls, providing full context for agent decision-making.

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

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

Schema coverage is 100% with both parameters thoroughly described in the input schema. The description adds a small amount of behavioral context (e.g., exact percent-delta math, tolerance cap), but the schema already carries the semantic load, so this is at the acceptable baseline.

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

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

The description clearly states the tool verifies natural-language factual claims against authoritative sources, with specific trigger phrases and a clear verb+resource ('verify the claim that…'). It distinguishes itself as a consolidated alternative to multi-step lookups, making the purpose unambiguous.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and explains the two routing paths for company-financial vs. other claims. However, it does not name specific sibling tools or state explicit exclusion criteria, so it misses the highest bar for alternative guidance.

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