newton

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context beyond this: it discloses the cost implication of using Anthropic ('BYO key — you pay Anthropic directly for those calls') and the return structure. It does not mention error handling or rate limits, but the annotation safety profile lowers the burden.

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

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

The description is three sentences long, front-loaded with the core purpose, and every sentence adds value. The first sentence states the main function, the second covers model configuration and cost, the third gives return format and use cases. 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?

Given no output schema, the description compensates by explicitly describing the per-model response structure and combined view. It also covers use cases and the API key requirement. The main gap is lack of edge-case behavior (e.g., what happens when an entity is unknown or an API key is invalid), but for a non-destructive read tool with a simple schema, this is sufficient.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds a small but useful detail about the default model and the condition for using `_apiKey`, but it does not significantly enrich parameter understanding beyond the schema's own descriptions. It also mentions return format, which is not 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 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 states what the tool does and distinguishes it from siblings by focusing on probing LLM knowledge and producing visibility scores. It also adds concrete output details (per-model score, confidence, signals, raw_response) and a combined view.

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 use cases: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains when to pass the API key ('pass `_apiKey` to also probe Anthropic') and notes the default model. However, it does not explicitly name alternative tools or state when not to use this tool, so it falls short of a full 5.

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

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

The description clearly indicates that the tool answers questions about current/historical data across many domains)Skip? No, but it's transparent that it's a search/QA tool. It mentions

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 but informative. It doesn't fluff and gets straight to the 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?

Provides a broad list of domains and a preference over web search, but doesn't mention limitations or examples of when not to use it. Still fairly complete for its purpose.

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 a single required property 'question' with a clear description and multiple aliases. The examples illustrate usage.

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

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

The title 'Ask Pipeworx' is somewhat opaque, but the DESCRIPTION immediately clarifies that this tool is designated for answering questions about current or historical data across a wide range of domains (SEC, FDA, FRED, etc.). It explicitly says to prefer over web search, making its purpose unambiguous. The examples further reinforce this, showing concrete use cases.

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 guidance on when to use the tool: for questions about current or historical data in listed categories Correctq and recommends it over web search. However, it doesn't specify what types of questions are NOT appropriate for this tool, or if there are any constraints on query complexity. Still, the purpose is well-scoped.

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

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

Annotations declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true; the description does not contradict these. It adds genuinely useful context beyond annotations: that no candidate is currently active, that behavior currently matches the stable router, and that results are compared against the stable router for merge decisions. One small gap: it doesn't explicitly state that the tool may produce different routing results than ask_pipeworx when a candidate IS active, but it does convey the experimental nature.

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

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

Immediately frames the tool as 'beta version of ask_pipeworx' and clarifies it is a full working router, then explains its experimental status. The closing phrase 'this IS a full working router' is a useful redundancy that prevents misuse. Well-structured and front-loaded, though slightly verbose with the parenthetical tool count.

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?

Addresses the use case (want newest routing), the current state (no candidate active), and the evaluation context (results compared to stable router). Missing specifics: response shape or confirmation of what happens after calling, but schema annotations (readOnly, idempotent) already cover some of that. Overall sufficient for correct selection and use.

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

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

Input schema documentation coverage is 100% with all parameters (question plus five aliases) fully documented. The description reinforces that arguments are identical to ask_pipeworx, so no additional parameter explanation is needed. Could add a usage example, but for an alias-heavy schema with full documentation, this is adequate.

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?

Clearly identifies this as a variant of ask_pipeworx with a precise purpose: a universal router for candidate routing improvements under A/B test. Distinguishes itself from sibling ask_pipeworx (stable) and ask_pipeworx_grounded (explicitly different). The verb 'ask' plus the resource 'pipeworx' and the beta modifier make the scope obvious.

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

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

Explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and notes the current state (no candidate active, matches ask_pipeworx). It explains why an agent would choose this over the stable sibling. It doesn't explicitly state when NOT to use it, which keeps it from 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 substantial behavioral detail: the grounding mechanism (extracts using ONLY tool result), the explicit refusal structure with specific refusal reasons, and the return schema. This goes well beyond the annotations and clearly communicates what the agent can rely on.

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

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

The description is dense but every sentence earns its place, covering purpose, routing, grounding, output, refusal conditions, use cases, and cost trade-off. It is front-loaded with the core value proposition, then details. Slightly longer than minimal but appropriately 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 the complexity of the tool (grounded answer extraction with refusal handling) and the absence of an output schema, the description fully explains the return format, refusal reasons, and behavioral guarantees. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100% with all aliases documented as equivalent to 'question'. The description does not add parameter-level semantics beyond what the schema states (e.g., natural language question). Since the schema fully covers the parameters, baseline 3 is appropriate; the description does not need to compensate.

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 purpose: a hallucination-resistant answer mode that extracts answers grounded in tool results, returning evidence and confidence. It explicitly contrasts with ask_pipeworx, making the distinction clear. The verb is 'answer' but the resource and behavior are well defined.

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

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

The description provides explicit when-to-use criteria: 'Use whenever an answer will be quoted, cited, or acted on' and lists specific high-stakes domains. It also directly instructs to prefer ask_pipeworx for casual lookups, and notes the extra LLM call cost. This is exemplary 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. The description adds far more: the resolver contract (match confidence, alternatives, suggestions), safety short-circuits (low_confidence_match, market_closed_or_inactive), wide-spread illiquidity handling, news fallback behavior with retry details, and cancellation-rule risk (refund_50_50, resolves_no_on_cancel, etc.). This goes well beyond what annotations provide.

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

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

The description is densely packed and lengthy, with all-caps section headers helping to structure it. It contains a lot of valuable detail, but the sheer volume of text reduces scanability and conciseness. Some content, such as the note about de-indexed markets and blocking mechanisms, could be trimmed without losing core 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?

Given the tool's high complexity and the lack of an output schema, the description is exceptionally complete. It details the resolver contract, parent-event extraction, news fallback behavior, safety mechanisms, and cancellation-rule risks. Agents receive enough operational context to handle edge cases and interpret all result fields 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 provides 100% coverage, including descriptions and examples for all three parameters. The tool description reinforces the market argument forms (slug, URL, question text) and adds behavioral context about fan-out and response shapes, but it does not significantly extend parameter-level semantics beyond the schema. A 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 first sentence clearly states the tool's verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It then specifies input types (slug, URL, question text) and the classification/fan-out behavior. The stated use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') distinguish it from general research or data tools.

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

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

The description explicitly names use cases and provides extensive fan-out examples across bet categories (BTC, Fed, Hormuz, Yankees, NVDA-vs-AAPL). It also instructs agents to inspect resolver confidence before trusting the analysis and to check cancellation rules before sizing certain bets. However, it does not name alternative sibling tools or explicitly state when not to use this tool, so it lacks exclusionary 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 this as a safe, read-only, idempotent operation. The description adds substantial behavioral context: specific data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and return format with citation URIs. This goes well beyond the annotation hints and gives the agent a clear model of the tool's runtime behavior.

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

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

The description is dense but every sentence adds value. It front-loads the purpose and usage triggers, then details behavior and output. No fluff, and the structure flows logically from intent to mode-specific details.

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, no output schema, and existing annotations, the description is complete. It explains what data is pulled per entity type, how results are sorted, and what the return value includes (paired data + citation URIs). It also provides efficiency context ('Replaces 8–15 sequential lookups') that helps an agent justify its use.

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

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

The schema covers 100% of parameters, but the description adds rich semantics: it explains the behavioral difference between type='company' and type='drug', what metrics are pulled for each, and how the values array maps to tickers or drug names. This is meaningful detail beyond the basic 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's purpose: side-by-side comparison of 2–5 companies or drugs in one parallel call. It uses specific verbs and resources ('compare', 'companies or drugs') and distinguishes itself from siblings by contrasting with sequential single-pack lookups and describing its parallel, batched 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?

Explicit guidance is provided: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also gives trigger phrases (e.g., 'X vs Y', 'rank these companies') to help the agent recognize when to use it. The description clearly states when to use this tool and implies when not to (for non-comparison lookups).

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses authentication requirements, per-depth hop behavior, gap/contradiction output, stable citation_uris, semantic excerpting, and latency ranges. It clarifies that outputs are never invented and that citations are only present when genuinely fetchable. These are significant behavioral traits the annotations alone do not convey. No contradiction with annotations.

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

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

The description is long but every sentence carries operational or selection information, and the most critical fact (account requirement) is front-loaded. The flow is logical: prerequisites → core function → use cases → depth semantics → output/citation behavior → latency. A few repetitions of ask_pipeworx as the alternative appear, but each addresses a distinct condition (auth, query scope, news currency), so the length is justified.

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

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

For a tool with no output schema, the description thoroughly explains what the findings packet contains (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), the gaps[] and contradictions[] fields, hop tracking, and citation resolvability. It also covers auth/pricing, latency, and unsupported topic behavior. An agent has everything needed to invoke and interpret results correctly.

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

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

Schema already documents both parameters at 100% coverage, so the baseline is 3. The description adds behavioral context by explaining what 'quick', 'standard', and 'thorough' mean in terms of facet count, hop iteration, and paid tier, and by reassuring that broad multi-part questions are fine. This elevates the semantics meaningfully beyond the schema, but does not add new parameter syntax or format details.

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 concrete action — 'Grounded multi-source research across Pipeworx's 1463 STRUCTURED data sources…in ONE call' — and explicitly contrasts it with open-web search and sibling ask_pipeworx. It names the verb, the resource, the output type, and the boundary against siblings, so an agent can distinguish deep_research from every sibling without opening 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?

It states exactly when to use the tool ('Best for broad/multi-part questions over structured data') and gives two explicit exclusion cases: single lookups and breaking/current-news topics, both routed to ask_pipeworx. It also names the auth precondition and the fallback tool for unsigned-in users. This is explicit when/when-not/alternative guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is established. The description adds that algebraic notation is accepted and the derivative is returned, which is useful but not extensive 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 brief and front-loaded, but the final sentence 'Returns the derivative' repeats information from the first sentence, so not every sentence is strictly necessary.

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 math tool with an output schema and strong annotations, the description sufficiently specifies input form, variable, and return value. No major context is missing.

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

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

The schema already documents the single parameter with examples, providing 100% coverage. The description adds the key detail that differentiation is with respect to x, which the schema does not state.

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 'Find the derivative of an expression with respect to x,' which identifies the specific operation and resource. It naturally distinguishes itself from sibling tools like factor and simplify.

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

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

The description provides clear context: it is for differentiating an algebraic expression with respect to x. It does not explicitly mention alternatives, but the operation is unambiguous and no exclusions are needed.

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

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

While annotations already declare readOnly/idempotent/non-destructive, the description adds critical behavioral details: it returns top-N tools with names, descriptions, full input schemas, and curated examples, and states that results are 'ready to call directly, no second schema lookup needed.' This clarifies exactly what the agent can expect and reduces uncertainty about the tool's outputs.

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

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

The description is slightly long due to the enumerated domain list, but each sentence serves a purpose: it states what it does, when to use it, what it returns, and a strategic call-to-action. The key information is front-loaded, and the structure is logical, earning a high but not perfect score.

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

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

Given that there is no output schema, the description properly explains return values (top-N tools with schemas and examples) and provides clear context for when to invoke this tool. It also covers the practical detail of direct callability. There are no significant gaps for an agent to misuse the tool.

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

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

Schema description coverage is 100%, with all six parameters already described (including aliases and examples). The description reinforces that the query is a natural language description but does not add new semantic meaning beyond the schema. It mentions 'limit' implicitly through schema, so the description adds marginal value over the structured fields.

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 goes beyond a simple verb and resource by enumerating specific domains (SEC filings, FDA drugs, etc.) and explicitly differentiates from siblings by saying 'Call this FIRST when you have many tools available and want to see the option set.' This leaves no ambiguity about its role as a discovery tool.

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

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

The description provides explicit usage context: 'Use when you need to browse, search, look up, or discover what tools exist...' and instructs to call it first when many tools are available. It implies when not to use it (when you already know the specific tool) and distinguishes it from tools that directly answer a query, making the guidance 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?

The description adds rich behavioral context beyond the annotations: it fans out across SEC EDGAR, XBRL, USPTO, news, GLEIF; returns specific fields; notes that patents soft-fail due to the USPTO API sunset; and explains the GDELT→GNews fallback. This is substantial value beyond the readOnly/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 detailed, but it is front-loaded with example intents and a clear purpose, followed by structured return data. Every detail (patents sunset, fallbacks, max filings) earns its place, though it could be tightened without losing clarity.

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

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

For a complex fan-out tool with only 2 parameters and no output schema, the description thoroughly covers expected returns, edge cases (patents soft-fail, news fallback), and input constraints. It fully prepares the agent to invoke it correctly and understand its outputs.

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

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

The schema already covers both parameters with 100% coverage, describing ticker/CIK format and the rejection of names. The description's examples ("AAPL", "0000320193") mirror the schema almost exactly, adding no new semantic information. Baseline 3 is appropriate since the schema carries the weight.

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: "full cross-source profile of a US public company in ONE parallel call," with specific verbs like "tell me about," "research," and "brief me on." It distinguishes itself from sibling tools like resolve_entity by specifying that names are not supported and directing users to resolve_entity first.

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

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

Explicit guidance is provided: "ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view." It also clearly states when not to use it: "names not supported (use resolve_entity first if you only have a name)."

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, and non-destructive, so the description doesn't need to restate that. It adds the fact that output is factored form, but does not discuss edge cases like non-factorable polynomials or coefficient domains, which is a minor gap.

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

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

Two clear sentences front-load the purpose and include examples. Every word contributes, with 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?

Given the tool's simplicity, the single parameter is fully documented, safety is covered by annotations, and an output schema exists. The description covers the essential input/output contract sufficiently for an agent to use it correctly.

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

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

Schema coverage is 100% and the parameter is fully described. The description adds examples, but these are already present in the schema, so it provides no additional semantic value beyond what the schema already offers.

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

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

The description uses a specific verb 'factor' with a specific resource 'polynomial' and clarifies the output as 'irreducible factors'. This clearly distinguishes it from sibling tools like simplify and derive.

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

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

The description provides clear context by specifying the input format (polynomial expression) and output (factored form), which implies when to use it. However, it does not explicitly contrast with alternatives or provide exclusions, so it falls short of a 5.

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

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

The annotations already declare destructiveHint=true and idempotentHint=true, so the main behavioral traits are covered. The description adds the nuance that this deletes a previously stored memory and is suitable for clearing sensitive data, which is useful but does not reveal additional significant behavior 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 action, and contains zero wasted words. Every clause contributes either to the function, the use cases, or the relationship with sibling tools.

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

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

For a simple one-parameter destructive tool with no output schema and complete annotations, the description covers the what, when, and why. It also gives a practical example in the schema, making the tool fully usable without further information.

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 has 100% coverage for the single parameter 'key' with description 'Memory key to delete'. The description's phrase 'by key' merely restates schema information and provides no additional semantic enrichment, so the baseline score of 3 applies.

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

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

The description clearly states a specific action (delete) on a specific resource (previously stored memory) keyed by a unique identifier. It distinguishes the tool from siblings like remember and recall, which handle storage and retrieval respectively.

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

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

The description explicitly gives three concrete use cases: stale context, task completion, and clearing sensitive data. It also points to complementary tools (remember and recall) to orient the agent, though it does not explicitly state when not to use the tool.

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

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

Despite annotations already indicating readOnly, idempotent, and non-destructive behavior, the description adds valuable context: it fetches the page, extracts title/description/key links, emits the standard llms.txt markdown format, and outputs 'a single text blob ready to drop at site-root/llms.txt.' This goes beyond annotation hints and clarifies the tool's side effects and return format.

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 plus a concise 'Useful for' list. It is front-loaded with the core functionality, and every sentence serves a purpose—what it does, how it works, and when to use it. No fluff or repetition.

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

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

For a simple tool with two params and no output schema, the description fully covers the return value ('single text blob'), the process (fetch, extract, emit), and deployment context ('drop at site-root/llms.txt'). It is complete for an agent to invoke and understand the result.

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

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

The input schema covers 100% of the parameters with clear descriptions (url and max_links with default/max values). The description does not add extra parameter semantics beyond the schema, so the baseline of 3 for full coverage is appropriate.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Generate a production-ready llms.txt file for any URL'. It also distinguishes itself from siblings by describing its exact output and use cases, making it unique among tools like 'scan_competitor_ai_presence' or 'ai_visibility_check'.

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

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

The description provides explicit use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' It does not explicitly mention when not to use it or name alternatives, but the context is clear enough for an agent to decide when to invoke 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 indicate a safe read-only, idempotent operation, so the description's additional details are valuable. It discloses the return behavior (antiderivative with constant C) and the integration variable, adding context beyond annotations without contradicting them.

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

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

The description is two sentences, front-loaded with the primary purpose, and each sentence adds necessary information. It is concise, well-structured, and contains no redundant filler.

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

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

Given the tool's simplicity (one parameter, output schema present), the description adequately covers the operation, input expectations, and return behavior. It does not mention edge cases or error handling, but these are not critical for such a straightforward tool with rich annotations and schema.

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

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

The schema fully documents the 'expression' parameter with examples, but the description adds meaning by specifying 'algebraic notation' and 'with respect to x', which clarifies the expected input format and the role of the variable. This goes beyond the schema's basic type and examples.

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

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

The description clearly states the tool's function with a specific verb ('Find') and resource ('indefinite integral of an expression'), and specifies the variable of integration ('with respect to x'). This distinguishes it from sibling math tools like derive, factor, and simplify, making the purpose unambiguous.

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

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

The description provides clear context on how to use the tool (input algebraic notation, integration with respect to x) and what it returns. However, it does not explicitly mention when to use this tool over alternatives like derive or factor, though the clarity of purpose makes the appropriate usage strongly implied.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by clarifying the tool scopes to the caller's subscriptions and defaults to active-only (mentioning the include_inactive behavior indirectly through 'active subscriptions'). This contextualizes the annotation without contradicting it.

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

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

Two sentences, front-loaded with the tool's purpose and return fields, followed by a practical usage hint. Every word earns its place; 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?

Despite lacking an output schema, the description lists exactly what the tool returns. Combined with the simple input schema, strong annotations, and clear usage guidance, the description fully equips an agent to invoke this tool correctly.

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

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

Schema description coverage is 100% for the single parameter include_inactive, so the schema already explains its meaning. The description does not add further parameter-level detail, and per the baseline for high schema coverage, a score of 3 is appropriate.

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

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

The description uses a specific verb ('List') and resource ('the caller's active subscriptions'), clearly differentiating from siblings like subscribe and unsubscribe. It also enumerates the returned fields (id, type, params, created_at, last_fired_at, fire_count), leaving no ambiguity about what the tool does.

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

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

The description gives explicit usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This implies when to use it relative to subscribe/unsubscribe but does not explicitly name those alternatives or state when not to use it, so it falls short of a perfect score.

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

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

The description discloses rate limits (5 per identifier per day), quota-free usage, the claim_token flow for asynchronous follow-up, daily digest review cadence, and roadmap impact. This adds substantial behavioral context beyond the four false annotation 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?

Every sentence earns its place: core action, usage scenarios, exclusion rule, claim_token mechanics, rate limits, and cost. The description is well-structured and front-loaded with the primary purpose, with no redundant filler.

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

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

With no output schema, the description explains the return behavior (claim_token) and all operational constraints. Nested context and enum parameters are documented in the schema, and the description adds the missing context about follow-up workflow and constraints, making the tool fully usable.

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

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

Schema covers all four parameters at 100%, so baseline is 3. The description adds operational meaning for claim_token (how to use it to check status) and message (describe in terms of Pipeworx tools/packs), going beyond the schema without re-explaining every field.

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: telling the Pipeworx team about bugs, missing features, or praise. It distinguishes this feedback tool from the sibling research/query tools by explicitly scoping to the Pipeworx connection and enumerating feedback types.

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

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

Provides explicit 'Use when' scenarios for bug, feature/data_gap, and praise, and an explicit exclusion for tools from other MCP servers with a directive to file elsewhere. Also gives a practical heuristic for identifying Pipeworx tools, making the decision boundary unambiguous.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable context: it is derived from CF analytics-engine, contains no PII, returns three fields (pack, tool, count), and is cached for 5min-1h depending on window. This goes beyond what annotations provide.

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

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

The description is well-structured and front-loaded: it opens with a clear statement of purpose, then lists three concrete use cases, and finishes with important technical details. Every sentence adds value and there is no 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?

For a tool with one optional parameter and no output schema, the description is thorough: it explains the output contents (top tools, top packs, call volume), the window parameter, use cases, data source, and caching behavior. This is sufficient for an agent to use the tool correctly without additional documentation.

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

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

The only parameter (window) has 100% schema description coverage, including its enum values and the trade-off between short and long windows. The tool description merely mentions the window and does not add additional semantics beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states what the tool does: it shows what other AI agents are calling on Pipeworx, returning top tools, top packs, and total call volume. This is a specific verb+resource combination that distinguishes it from siblings like discover_tools or ask_pipeworx.

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

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

The description lists three explicit use cases (discovering hot data sources, confirming canonical tool choice, aligning with what most agents need), which gives clear context for when to use it. However, it does not name alternative tools or explicitly state when not to use it, so it falls short of a 5.

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

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

The description goes far beyond the readOnlyHint/idempotentHint annotations by disclosing detailed behaviors such as the partition filter's placeholder logic, the Jaccard similarity threshold, the fill check against live CLOB depth, and the explicit warning that realizable_edge_pp ≤ 0 means the overround is not tradeable. These are non-obvious behavioral traits the agent needs to know.

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 appropriately sized for a complex tool with two modes and multiple behavioral considerations. It is front-loaded with the core purpose and simplest invocation, then organized into labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) that make the dense information scannable. Every sentence serves a purpose.

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

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

With no output schema, the description fully compensates by explicitly stating the response shape: 'opportunities[] (gap_pp, suggested_trade, reasoning...)' and 'in event mode partition_check{sum_yes_prices, gap_from_1, ...}'. It also covers failure/edge conditions such as skipped_low_similarity and placeholders_filtered, making the tool self-contained 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 already 100%, but the description adds substantial meaning beyond the schema: it distinguishes the two optional parameters by usage context, provides concrete examples of event slugs and topic seeds, and clarifies what each mode does with the returned markets. This is a strong value-add over the structured 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 and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly enumerates three invocation modes (trending_scan, event, topic) and presents a distinctive mechanism that separates it from sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

The description gives explicit when-to-use guidance: 'Call with NO args for a `trending_scan`...' and explains when to prefer `event` ('recommended for a specific market') vs `topic` ('for cross-event scanning'). It also points to an alternative tool: 'For custom sizing use polymarket_fill_risk.' This is exemplary usage direction.

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 is exceptionally transparent, detailing the three model families, response segments (by_segment), diagnostics to explain empty segments, the 1-hour KV cache keyed on all knobs, per-opportunity fields, and a 24h-move warning. This goes far beyond the annotations (readOnly, idempotent, non-destructive), and it does not contradict them.

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

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

The description is a dense, well-structured block with clear section labels (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL) and front-loads the purpose. While every detail serves transparency, the sheer length and specific model-family details make it slightly less concise than strictly necessary.

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

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

Despite having no output schema, the description thoroughly covers response structure, top-level fields, diagnostics, and caching, and explains the logic behind each model family and knob. It leaves little ambiguity about what the tool returns and how to interpret empty segments, making it complete for a tool of this complexity.

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

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

The input schema already has 100% coverage with detailed descriptions for all 9 parameters, so the baseline is 3. The description adds a high-level summary of the 'TRADEABLE-EDGE KNOBS' but mostly restates schema content; for example, min_partition_leg_kelly is explained more richly in the schema itself. Thus the description adds minimal new parameter meaning.

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

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

The description clearly states the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, with an explicit use case ('what should I bet on today'). It distinguishes itself from sibling tools by emphasizing discovery without paging hundreds of markets and by naming the three model families it returns.

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 says the tool is 'Built for what should I bet on today' and that it avoids paging hundreds of markets, implying use for opportunity discovery. It also provides an explicit exclusion: Fed bets are surfaced but excluded from ranking due to an unreliable EFFR signal. However, it does not explicitly name or differentiate sibling tools like polymarket_arbitrage, so it stops short of full comparison.

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

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

The description discloses significant behavioral traits beyond the readOnly/idempotent annotations: it explains that snapshots are written on a cache-miss, resulting in date gaps, and that history is bounded by a 60-day TTL. It also clarifies that decay numbers come from daily closes of edge_pp_net, not intraday, helping the agent set expectations. 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 exceptionally well-structured and front-loaded. It opens with the core purpose, then explains arguments, response fields, and limitations. Every sentence adds critical information, from the competitive rationale to the response format and TTL constraints. 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?

Given no output schema, the description fully describes the return structure: tracked[], expired[], and snapshot_dates[] with detailed explanations of each field. It also covers data availability caveats (cache-miss gaps, 60-day TTL) and what the metric represents (net of slippage). The tool's complexity is fully addressed.

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 does restate parameter meanings ('lookback, default 14, max 30') but adds little beyond the schema's existing descriptions. It does provide context about 'snapshot family' for window, but this is already implied in the schema. Minimal added semantic value.

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

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

The description clearly states the tool's function: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question ('how long has this edge existed and is it shrinking?') and distinguishes itself from the sibling polymarket_edges by focusing on temporal analysis rather than just current edges. The verb 'track' and resource 'edge snapshots' are explicit.

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

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

The description provides clear context for when to use the tool by contrasting 'a fresh wide edge' with 'a 3-week-old wide edge,' implying it is used to assess edge age and decay before trading. However, it does not explicitly name alternatives or state 'when not to use,' which would qualify for a 5.

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

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

Annotations already declare readOnly/openWorld/idempotent, and the description adds substantial behavioral context: it walks the order-book ladder, returns verdicts (clean|degraded|cannot_fill), interprets size_usd differently between single-market and basket modes, and warns about partial basket fills creating unhedged directional positions. This goes well beyond the annotations.

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

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

The description is long but well-structured: it leads with the core purpose, then separates single-market and basket modes, and ends with actionable usage guidance. Every sentence carries necessary information, but the density of technical details makes it slightly less concise than ideal.

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?

No output schema exists, so the description carries the full burden of explaining return values. It enumerates every field returned in both modes (top_of_book, vwap_fill_price, slippage_pp, capture_ratio, thin_legs[], etc.) and covers the risk of partial fills. It is fully complete for a complex two-mode 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?

While schema coverage is 100%, the description adds critical meaning by explaining the single-market vs basket modes, the mutual exclusivity of market/event, and how size_usd is interpreted in each mode (spend vs settlement notional). It also clarifies side defaults and the auto behavior in basket mode, which enriches the schema descriptions.

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

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

The description opens with 'Realizable-vs-theoretical edge check against live CLOB order-book depth', which clearly states the tool's specific verb ('check') and resource ('edge against order-book depth'). It distinguishes itself from siblings like polymarket_arbitrage and polymarket_edges by focusing on fill risk and realizability, making the purpose unmistakable.

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

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

The description explicitly states when to use this tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains why (theoretical overround on thin books is not capturable, partial fills convert an arb into directional risk), providing clear usage context and naming 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 goes far beyond the readOnlyHint annotation by detailing response structure, compatibility_warning triggers, temporal_alignment semantics, and skipped_cross_type/subtype counters. It explains when the tool reports no arbitrage exists and when events are unrelated, providing deep behavioral transparency.

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

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

The description is long but information-dense, covering purpose, modes, response fields, and safety conditions in a structured manner (numbered modes, explicit field names). It is somewhat dense but each sentence adds value, so it earns its length.

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

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

With no output schema, the description fully compensates by detailing return fields, safety flags, and interpretation guidance. It explains exactly what the agent will receive and how to interpret compatibility warnings and temporal alignment, making it complete for invocation and result understanding.

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 descriptions for all three parameters. The tool description adds semantic context by listing exact topic shortcut values, explaining that explicit tickers override topic-mapped sides, and providing examples. This enriches the raw schema definitions.

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

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

The description clearly states the tool computes a 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It distinguishes itself from sibling tools by focusing on cross-venue comparison and explains two operational modes (topic and explicit pairings).

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

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

The description explicitly explains when to use the tool (comparing same question across venues) and provides strong caveats: 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable.' It also notes conditions where spreads are not meaningful. It doesn't explicitly name sibling alternatives but the use case is clear.

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

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

Annotations already declare read-only and idempotent behavior; the description adds valuable context about scope ('Scoped to your identifier') and the dual-mode behavior (retrieve vs. list all). It doesn't detail return format, but the core behavior is transparent.

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 with purpose: function, usage context, and scope/relations. No fluff or repetition. The front-loaded active verb makes the tool's purpose immediately clear.

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

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

For a simple tool with one optional parameter and no output schema, the description fully covers what it does, when to use it, its scope, and its relationship to neighboring tools. Return values are implied clearly enough.

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 describes the 'key' parameter with high coverage. The description enhances it by explaining the omission behavior ('omit the key argument' to list all keys) and providing examples of what key/value pairs might contain.

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 ('Retrieve') and resource ('value previously saved via remember'), then clearly distinguishes its alternative mode ('or list all saved keys'). It names companion tools (remember/forget) to position itself among 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?

Explicitly says when to use: 'Use to look up context the agent stored earlier' and gives concrete examples (target ticker, address, research notes). It also explains the alternative tools: 'Pair with remember to save, forget to delete.'

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

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

The description reveals mark_read mutates read state ('so the next call only shows newer ones'), which contradicts the readOnlyHint=true annotation. Since the annotation claims no state changes, this is a direct contradiction; the description cannot earn credit because it conflicts with structured metadata.

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

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

Five sentences, each earning its place: purpose, return shape, filtering, read-state behavior, and alternative access. Information-dense without 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?

No output schema, so the description compensates by listing return fields (source, citation_uri, raw payload). It also covers main behavior, parameters, and operational guidance (polling/alternative endpoint), making it complete for a tool of this complexity.

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

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

Schema covers all 5 params with descriptions (100% coverage), giving a baseline of 3. The description adds meaningful semantics: explains mark_read's consequence on future calls and gives a concrete type example ('sec_8k'), so it exceeds 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 'Pull fired events from your subscription feed' — a specific verb and resource. It clearly distinguishes from siblings like list_subscriptions and recent_changes by focusing on the alert feed and event payloads.

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

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

It states 'Polls work fine' to clarify polling suitability and points to an alternative HTTP endpoint for scripts/dashboards. However, it doesn't explicitly name sibling tools or exclusion conditions, so it's clear context without exhaustive alternatives.

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

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

Beyond the readOnly/idempotent/destructive annotations, the description discloses multi-source fan-out, rate-limit fallbacks, a known API sunset (PatentsView May 2025), and the return shape (structured changes[] + total_changes + citation URIs). This is substantial behavioral context not inferable from annotations alone.

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?

Even though long, every sentence contributes essential information: usage examples, source fallbacks, limitations, parameter hints, return structure, and alternative tool. The dense but well-organized single paragraph is front-loaded with query examples and wastes no words.

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

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

For a tool with multiple upstream APIs, rate-limit fallbacks, and a planned sunset, the description covers all key aspects: what changes are included, how the window is specified, what to expect back, and when to use a sibling tool. No output schema exists, so the return description is essential and provided.

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

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

Schema coverage is 100%, so baseline is 3. The description adds practical value by suggesting '30d' or '1m' for monitoring, reinforcing the ticker/CIK formats, and clarifying the `since` window semantics with examples. It goes slightly beyond a simple schema restatement.

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 realistic query examples and clearly states the tool is a 'change feed for a company in the last N days' citing specific sources (SEC EDGAR, GDELT/GNews, USPTO). It explicitly distinguishes itself from the sibling entity_profile, making its 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?

The description provides concrete usage guidance with phrase examples, explains the `since` parameter with typical values, and explicitly names an alternative tool ('Use entity_profile instead when you want the static profile'). It also notes fallback behavior (GDELT → GNews) and the USPTO soft-fail condition.

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 indicate non-readonly, non-destructive, and idempotent. The description adds key behavioral context: persistence details ('Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours') and scoping ('by your identifier'). 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?

Three sentences pack purpose, usage, storage model, persistence, and companions without repetition. Every sentence adds value and the structure is logical.

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 key-value store, the description covers the tool's full lifecycle: when to save, how it's stored, persistence rules, and how to retrieve/delete. Output schema is absent and unnecessary.

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

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

Schema coverage is 100%, and the description enriches both parameters: key examples ('subject_property', 'target_ticker') and value clarification ('any text — findings, addresses, preferences, notes').

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 'Save data the agent will need to reuse later' with a specific verb and resource. It also specifies scope ('across this conversation or across sessions') and distinguishes from siblings like recall (retrieve) and forget (delete).

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

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

Explicitly says 'Use when you discover something worth carrying forward' with concrete examples (ticker, address, preference). It also gives direct guidance on complementary tools: 'Pair with recall to retrieve later, forget to delete.'

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

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

Annotations already provide readOnlyHint, idempotentHint, and openWorldHint. The description adds significant behavioral context: 'Each call cascades through several lookup endpoints internally,' graceful degradation ('if GLEIF or OpenFIGI is unavailable, the EDGAR identifiers still return'), and explicit handling of unresolved identifiers ('stated explicitly under unresolved'). This goes well beyond the annotations and gives the agent a clear picture of tool behavior.

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

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

The description is quite long and includes many details, but it is well-structured: starting with example queries, then usage guidance, then supported types with detailed explanations. Some sentences are verbose and could be tightened (e.g., the parenthetical about identifiers being labelled with source). While every sentence adds value, the overall length could be reduced without losing clarity.

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 data sources, cascading lookups, graceful degradation, multiple input formats) and the absence of an output schema, the description covers return values well: it explains identifiers for company (CIK, ticker, LEI, FIGI, ownership) and drug (RxCUI, ingredient, brand, citation), and mentions unresolved identifiers. It lacks a sample response structure, but the description is sufficient for an agent to understand what to expect.

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

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

Schema description coverage is 100%, but the description adds substantial meaning beyond the schema. For company type, it explains the value accepts ticker, CIK, ISIN, or company name, and details the resolution depth (CIK, ticker, LEI, FIGI, ownership). For drug type, it specifies RxCUI, ingredient, brand, and citation. The description also provides concrete examples ('AAPL', '0000320193', 'ozempic'). This greatly enriches parameter understanding.

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

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

The description begins with concrete example queries ('What's the ticker for…') that immediately clarify the tool's purpose: resolving names to canonical identifiers. It explicitly states the supported types (company, drug) and distinguishes from sibling tools like entity_profile by saying 'Use FIRST whenever you have a name but need an ID.' This is a specific verb+resource with clear scope.

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

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

The description gives explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It also implies that if you already have an ID, you would use other tools. However, it does not explicitly name alternative tools for when the user already has an identifier, nor does it provide explicit 'when not to use' conditions. The guidance is strong but could be more complete.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, and the description adds behavioral context: it explains the probing process, ranking, and output fields (score, confidence, signal density). 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?

Two sentences, front-loaded with the core action and outcome. Every word earns its place; 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?

Covers inputs (entities, models, context), process (probes with ai_visibility_check), output (ranked list with specific fields), and use case. Complete for a tool without an output schema.

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

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

Schema coverage is 100% with detailed parameter descriptions, so the baseline is 3. The description reinforces the multi-entity comparison and subject/competitor roles but adds little new semantic value beyond what the schema already provides.

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

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

Description uses a specific verb ('Compare') and resource ('AI visibility across multiple entities'), clearly differentiating it from sibling tools like ai_visibility_check by stating it probes each entity and ranks them. The purpose is unmistakable and distinct.

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

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

Provides an explicit use case ('competitive AI-marketing audits') with a concrete example. Implicitly contrasts with single-entity tools by framing as 'side-by-side' comparison, but does not name alternatives or state when not to use it, so a slight gap remains.

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

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

Goes beyond annotations by disclosing the composite fan-out behavior, graceful partial failure ('sources_failed will list it if it times out, the rest still returns'), and a specific performance caveat (bundlephobia's first measurement can take 5-30s). It also enumerates the exact return fields, which is valuable context beyond the readOnly/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 front-loaded with the core purpose, then layers usage guidance, ecosystem scope, and failure handling in a logical order. Every sentence contributes unique information, and despite its length, it remains tight and scannable.

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

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

As a composite tool with two external sources, no output schema, and complex behavior, the description covers all essential aspects: the data sources, the return summary fields, per-advisory details, alternative versions, ecosystem limitation, and partial-failure handling. It even includes performance expectations, making it highly complete.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds minor practical context (e.g., 'Scoped packages are accepted' and default version behavior) but largely repeats what's in the schema, warranting the baseline score of 3.

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 composite goal: 'should I add this npm package to my project' check in ONE call, and clearly enumerates the data sources (deps.dev and bundlephobia) and the metrics returned. This clearly distinguishes it from sibling tools like verify or compare_entities, as it is uniquely focused on npm package vetting.

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 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also provides an exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', which guides when NOT to use this tool and directs to an 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?

The description adds rich behavioral detail beyond annotations: returns top-N passages with character offsets and similarity scores, uses BGE-base-en embeddings with cosine over 500-char overlapping windows, 200K char cap with truncation flagging. This goes well beyond the readOnly/idempotent hints and provides actionable 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 compact yet information-dense: purpose, usage guidance, technical details, and pairing advice in four sentences. Every sentence contributes value, with the core action 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?

Despite no output schema, the description explains the return format (passages with offsets and similarity scores), input constraints (200K cap, truncation), and relationships with sibling tools. For a 3-parameter search tool, this is fully complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining 'text' as already-pulled content with examples (SEC 10-K body) and clarifies 'query' as natural language with examples. It slightly enriches the limit parameter by implying it controls passage count, but most semantic value is already 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 clearly states the tool performs semantic search inside a fetched record, with specific verbs (search, pass) and resource (record). It distinguishes from siblings like ask_pipeworx_grounded by focusing on searching within already-pulled text rather than fetching or grounding.

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 'Use when the record is too big to cram into the prompt' and pairs with ask_pipeworx_grounded, describing when to use this tool vs alternatives. Provides concrete scenarios (SEC 10-K body, article, long tool result) and shows how it saves context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is known. The description adds that it returns a simplified result, which is consistent but not surprising. It also hints at supporting algebraic notation with implicit multiplication (e.g., '2(2)'), which is a mild behavioral detail, but overall limited added value beyond 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 primary purpose, and includes a concrete example. There is no redundant or extraneous text; every sentence earns its place.

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

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

The tool is simple with one parameter, annotations cover safety, and an output schema exists (though not shown). The description adequately conveys the tool's function and expected input format, leaving no significant gaps for the agent to misinvoke.

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

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

Schema description coverage is 100% with the parameter 'expression' fully described and an example provided. The description repeats the same example and adds 'algebraic notation' as a general term, but does not significantly expand beyond the schema's own description. 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 that the tool reduces a mathematical expression to its simplest form, using the specific verb 'reduce' and resource 'mathematical expression'. It provides an example of input notation, making the purpose clear. However, it does not explicitly differentiate from sibling tools like 'factor' or 'derive', so it lacks explicit 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 does not specify when to use this tool versus alternatives. It does not mention any exclusions, prerequisites, or compare with sibling tools such as 'factor' or 'derive'. There is no guidance on context or selection criteria.

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

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

The description adds substantial behavioral detail beyond the annotations (which only include flags like readOnlyHint=false and idempotentHint=true). It discloses account requirements, phone verification, SMS rate limits (10/day), the always-on feed behavior, and how to pull alerts. It even notes that the response returns the subscription id. This is exemplary for a mutation tool with no output schema.

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

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

The description packs a lot of information into a compact, well-organized structure. It starts with the action, then covers return value, prerequisites, supported types, and delivery channels with examples. Every sentence adds value, and the use of quotes and examples makes it scannable without being verbose.

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

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

Given the tool's complexity (nested objects, multiple subscription types, delivery options) and no output schema, the description covers essential return value, prerequisites, type examples, and feed access. The only notable omission is the webhook delivery channel—while described in the schema's 'delivery' object, it is not mentioned in the main description. This is a minor gap for completeness.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics by providing real-world context not fully in the schema, such as 'items:["5.02"] = officer change' for sec_8k and examples for each type. This deepens understanding of the 'params' object beyond the schema's syntax-only descriptions.

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

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

The description clearly states the tool's primary action: 'Create a proactive monitoring subscription to a live-data event stream.' It specifies the resource (monitoring subscription), the verb (create), and what is returned (new subscription id). It also distinguishes itself from siblings like 'unsubscribe' and 'list_subscriptions' by framing it as the creation mechanism.

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 strong contextual guidance by listing supported subscription types with concrete examples, delivery channel options, and a critical prerequisite (requires a Pipeworx OAuth account; anonymous/BYO cannot persist). It does not explicitly say when NOT to use it or name alternative tools, but the rich context makes usage conditions clear. A minor deduction for not contrasting with sibling tools like 'polymarket_edge_tracker' or 'recent_alerts'.

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, the description discloses that it returns category-bucketed examples drawn from a live catalog, each with tool and argument shape, and that omitting `topic` yields a cross-category spread. This adds meaningful behavioral context 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 a long single paragraph, but every sentence contributes functional or usage information. It is front-loaded with example queries, making it easy to parse quickly despite its length.

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

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

Even without an output schema, the description fully explains what is returned, how to control scope, and when to use it. For a simple onboarding tool, this is complete and enables correct tool selection and invocation.

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

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

Schema coverage is 100% (baseline 3), but the description adds value by providing concrete example topic values and explaining the difference between passing `topic` vs. omitting it for full spread, which is not fully captured 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 clearly identifies the tool as an onboarding entry point that returns category-bucketed example questions with exact tool+argument shapes. It includes user-facing example queries and differentiates from siblings like ask_pipeworx (which answers questions) by focusing on what to ask.

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 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains how to use the optional `topic` parameter for focus. This gives clear when-to-use guidance and distinguishes it from alternative tools.

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

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

The description adds significant behavioral context beyond annotations: it explains the row is deactivated (not deleted) and that historical events remain accessible via recent_alerts. Also, ownership enforcement is a behavioral detail not present in the annotations. This fully discloses the side effects, aligning with the non-destructive and 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 two sentences, front-loaded with the core action, followed by two critical behavioral clarifications. Every sentence adds value: the action, the ownership constraint, and the deactivation effect. No wasted words.

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

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

For a tool with a single parameter and no output schema, the description covers the essential aspects: what it does, the constraint, and the post-condition. The mention of recent_alerts links to a related tool, providing sufficient context for an AI to understand the full workflow.

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 of the single parameter 'id', describing it as 'Subscription id (uuid) returned by subscribe.' The description only repeats 'by id' without adding new semantic details, so it meets the baseline for high schema coverage but does not exceed it.

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.' It also specifies the resource (subscription) and the method (by id), distinguishing it from siblings like subscribe and list_subscriptions.

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 context is clear: cancel a subscription you own, indicated by 'Ownership is enforced — you can only cancel your own subscriptions.' This implies you should use it for your own subscriptions, but it does not explicitly mention when not to use it or suggest alternatives, hence not a full 5.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds critical behavioral nuance: the exact meaning of could_not_verify (attempt failed, not evidence) and unsupported (no source found), the two-stage processing pipeline, and the inclusion of verification_error. This goes well beyond the annotations.

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

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

The description is detailed but every sentence contributes: trigger phrases, purpose, pipeline differentiation, verdict set, caller warning, and efficiency rationale. It is well-structured with clear formatting and no redundant filler, making it appropriately sized for a complex 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 fully explains the return structure: verdicts, actual value with citation, reasoning, and error semantics. It addresses edge cases (could_not_verify, unsupported) and provides integration context (replaces 4–6 sequential calls). This is comprehensive for a claim-verification 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 covers both parameters with 100% detail, so the baseline is 3. The description adds valuable guidance on tolerance_pct: how it overrides implied tolerance, suggested settings for hallucination detection (1–2), and the default cap of 5. This helps the agent choose an appropriate value, adding 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 identifies the tool as a natural-language claim verification tool, with specific trigger phrases and a definition of its role. It distinguishes itself from siblings by focusing on fact-checking with a verdict output and stating it replaces 4–6 sequential calls, which no other sibling does.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and explains two pipeline paths for financial vs. other claims. However, it does not explicitly mention when to prefer alternative tools like ask_pipeworx_grounded or deep_research, so exclusions are implied rather than spelled out.

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