onthisday

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 these: the default model is free, and passing `_apiKey` means 'you pay Anthropic directly,' disclosing cost implications. It also clarifies the return payload. This goes beyond the annotations without contradicting them.

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

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

The description is three sentences, front-loaded with the core function and output, followed by pricing/alternative details and use cases. Every sentence provides necessary information without wordiness. It's an exemplary compact description.

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 there is no output schema, the description appropriately includes return format: 'per-model {score, confidence, signals, raw_response} + a combined view.' It also covers default behavior, optional key, and typical use cases. Minor gaps like error handling or scoring methodology prevent a 5, but it is quite complete for a read-only probe tool with strong annotations.

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

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

Schema description coverage is 100%, so all four parameters have clear documentation. The description adds extra meaning by explaining the default model and the conditional need for `_apiKey` only when 'anthropic' is in models, which the schema's per-parameter description doesn't fully convey. This elevates it above the baseline 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 verb+resource: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' This clearly distinguishes it from sibling tools like ask_pipeworx or scan_competitor_ai_presence by emphasizing per-model visibility scoring. It also provides concrete output structure (score, confidence, signals) and 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 states 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring,' giving clear contexts for when to use it. It also explains the default vs. optional Anthropic probe, which helps decide whether to bring an API key. However, it does not explicitly name alternatives or when not to use, so it falls slightly short of a 5.

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

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

Annotations already cover read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable behavioral context such as automatic argument filling, routing across sources, and returning stable pipeworx:// citation URIs, going beyond annotation-only knowledge.

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

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

The description is long but front-loaded with purpose and usage, and the redundant emphasis on 'PREFER OVER WEB SEARCH' and 'START HERE' reinforces the intended default role. Every sentence contributes either guidance, examples, or comparisons with sibling tools, making the length 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?

Even though there is no output schema, the description explains what the tool returns: a structured answer with stable citation URIs. It also covers alternative tools and special cases like breaking news, making the description complete for an agent to decide when and how to invoke it.

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

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

The schema coverage is 100% and every parameter is clearly described as an alias for 'question'. The description does not need to add parameter-level semantics because the schema already fully explains the accepted inputs and their natural-language usage.

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

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

The description clearly states that the tool answers factual questions by routing to 5,801 tools across 1,517 verified sources and returning structured answers with citations. It explicitly differentiates itself from ask_pipeworx_grounded and deep_research, so an agent can select it appropriately.

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 on when to prefer this tool over web search, when to use ask_pipeworx_grounded instead, and when to escalate to deep_research. It also addresses breaking-news scenarios and provides concrete examples, leaving little room for misuse.

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

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

Beyond the readOnly/idempotent annotations, the description discloses that it is a live beta with candidate routing improvements, that no candidate is currently active, and that it falls back to nothing (fully functional). This adds behavioral context not covered by annotations.

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

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

The description is concise and well-structured. Each sentence serves a purpose: identifying the beta nature, clarifying current status, giving usage instruction, and dispelling fallback ambiguity. No redundant or extraneous content.

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

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

The description provides sufficient context for a beta router tool: it references the stable counterpart, explains the comparison mechanism, and confirms full functionality. For an agent familiar with ask_pipeworx, this is complete, and the question parameter description covers usage.

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

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

Schema coverage is 100% with all six parameters being aliases for 'question'. The description merely references 'same arguments' without adding detail beyond the schema, so it does not enhance parameter understanding.

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

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

Clearly states it is a beta version of ask_pipeworx, an identical universal router with candidate routing improvements. Distinguishes itself from the stable ask_pipeworx and explains its role as a router for natural language questions.

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 instructs to use it exactly like ask_pipeworx when wanting the newest routing, and explains that results are compared against the stable router. This provides clear when-to-use guidance relative to its sibling ask_pipeworx.

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 beyond the readOnly/idempotent annotations by detailing exact refusal reasons, the grounded extraction contract, and the explicit refusal behavior when data does not directly answer. It also notes the additional LLM cost, which is a relevant behavioral side effect.

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

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

The description is dense but well-structured, front-loading the core purpose and then providing routing, return contract, usage guidance, and cost tradeoff. Every sentence carries useful information without fluff or redundancy.

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

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

The description is complete enough for the tool's complexity: it explains what it does, how it differs from the sibling, when to use it, what it returns, what refusal reasons exist, and the cost tradeoff. The lack of an output schema is compensated by the explicit return contract description.

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

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

The input schema already covers 100% of parameters, including six aliases for the question field. The description does not add significant new parameter-level semantics beyond what the schema provides, so it stays at the baseline for high schema coverage.

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

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

The description clearly states that this is a hallucination-resistant, grounded answer mode that routes like ask_pipeworx but extracts answers only from tool results. It explicitly differentiates itself from ask_pipeworx by emphasizing grounded extraction and refusal behavior.

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

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

It explicitly tells when to use this tool — for high-stakes reads where answers will be quoted, cited, or acted on — and when to prefer ask_pipeworx for casual lookups. It also mentions the extra LLM call cost, giving clear selection guidance.

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

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

The description extensively discloses behaviors beyond annotations: resolver contract (market_match_confidence, suggestions), safety short-circuits for low-confidence matches, closed-market handling, wide-spread tradeability, cancellation-rule parsing, and news fallback fields. This goes far beyond the read-only/idempotent annotations.

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

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

The description is long but well-structured with capitalized section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). It front-loads the core purpose in the first sentence and every subsequent section adds operational detail an agent needs. While verbose, the density of unique value justifies the 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?

For a complex tool with no output schema, the description covers all critical facets: input formats, classification taxonomy, parallel fan-out, response shape with key fields, resolver confidence contract, parent-event extraction, news fallback handling, safety short-circuits, liquidity warnings, and resolution-rule risk. An agent has sufficient context to select and invoke the tool correctly.

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

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

The schema descriptions already cover all three parameters at 100% coverage. The description adds concrete examples for the market parameter (slug, URL, question text), explains default depth behavior, and clarifies include_raw's impact on response size. This adds meaningful context without being redundant.

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 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call,' clearly stating the verb, resource, and one-call scope. It distinguishes from sibling tools like deep_research or polymarket_arbitrage by specifying the Polymarket bet research niche and the fan-out to category-specific data packs.

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-case phrases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also gives fan-out examples per category (BTC bet, Fed bet, etc.), clarifying when each classifier applies. However, it does not name alternatives or exclusions, so it is clear but not fully explicit about when not to use.

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

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

Beyond the readOnlyHint and idempotent annotations, the description reveals key behaviors: it pulls specific metrics (10-K revenue, net income, cash, long-term debt for companies; FAERS, FDA approval, trial counts for drugs), handles off-calendar fiscal years correctly, sorts results by primary metric, and returns paired data with citation URIs. This is rich, non-obvious behavioral detail.

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

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

The description is longer than average, but every sentence adds operational value—trigger phrases, data-source details, fiscal-year handling, sorting, and output specifics. It is front-loaded with the most actionable guidance ('ALWAYS PREFER...'), though slightly dense; a bit of trimming could improve scannability without losing info.

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 there is no output schema, the description compensates by explaining what the response contains (paired data + citation URIs) and how results are ordered. It also covers edge cases (fiscal-year differences) and explicitly contrasts with the sequential-lookup alternative, making the tool fully self-contained for an agent to use correctly.

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

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

Although the schema already documents both parameters with 100% coverage, the description adds substantial meaning: it maps 'type' values to distinct data sources and metrics, and elaborates on the 'values' format with examples (tickers vs drug names) and constraints (2–5 items). This goes well beyond the schema's basic descriptions.

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

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

The description uses a specific verb ('compare') and names the exact resources ('2–5 companies or drugs') in a side-by-side parallel call. It clearly distinguishes itself from the sibling tool 'entity_profile' by emphasizing multi-entity comparison in a single call, 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?

It explicitly states when to use this tool: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also provides concrete trigger phrases ('X vs Y', 'rank these companies') and clarifies the distinction between company and drug types, giving clear context for selection versus alternatives.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description details what the tool does and does not do: it never invents answers, returns explicit gaps[], provides fetchable citation_uris only when resolvable, and includes contradictions[] for standard/thorough. It also discloses auth/account requirements and the paid thorough tier, making side effects and constraints clear.

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

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

The description is long and dense, but nearly every sentence adds a distinct operational fact: use-case boundaries, depth behavior, citation semantics, gap handling, excerpting, and latency. It is not padded with filler, though some repetition of the ask_pipeworx comparison and pipeworx:// details could be tightened without losing meaning.

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, the description covers the full decision surface: when to use it, when not to, how each depth tier behaves, what the response packet contains, how citations are resolved, how missing data is handled, and expected timing. It also addresses limitations like current-news coverage and paid thorough tier, so an agent has enough context to call it correctly.

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

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

The schema already covers question and depth with 100% coverage, so the description is not the only source of parameter meaning. However, it adds valuable semantics by explaining that questions may be broad/multi-part, that quick=3 facets, standard adds gap recovery and contradictions, and thorough adds iterative lead-chasing—making depth behavior far more actionable than the enum alone.

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

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

The description clearly states that deep_research decomposes broad/multi-part questions, routes facets to many tools in parallel, and returns a grounded findings packet with citations, gaps, and contradictions. It explicitly distinguishes itself from ask_pipeworx for single lookups and news topics, so an agent can pick the right tool without opening the schema.

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

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

It gives explicit when-to-use guidance: best for broad/multi-part structured-data questions, while single lookups and breaking/current-news topics should go to ask_pipeworx. It also explains the depth tiers, gap-recovery behavior, and expected latency, leaving little ambiguity about how 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?

Beyond the readOnly/idempotent annotations, the description adds valuable behavioral context: it returns top-N tools with names, descriptions, and full input schemas including curated examples, and that results are ready to call directly without a second lookup. This explains the tool's meta behavior and output richness clearly.

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 reasonably concise and front-loaded with the core purpose. The long list of domains in the second sentence adds some bulk but serves as concrete examples of use cases. Overall, it is well-structured without unnecessary fluff.

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

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

With no output schema, the description sufficiently explains what the tool returns (names, descriptions, full schemas, examples) and when to use it first among many tools. It addresses the key aspects an agent needs to understand the tool's role and output, making it complete for its complexity.

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

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

Schema description coverage is 100%, so the schema fully documents all parameters including query aliases and limit. The description adds a brief mention of free-form task descriptions but doesn't materially enhance parameter semantics beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states 'Find tools by describing the data or task' with a specific verb and resource (tools). It distinguishes itself from siblings by emphasizing discovery/browsing of available tools, as opposed to tools that perform analysis or access specific data.

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

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

The description provides explicit usage context: 'Use when you need to browse...' and 'Call this FIRST when you have many tools available and want to see the option set.' It does not explicitly name exclusions or alternatives, but the guidance is clear enough for an agent to decide when this tool is appropriate.

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

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

Annotations already mark it read-only, idempotent, and non-destructive, and the description adds substantial behavioral details: it fans out in parallel, soft-fails on the USPTO source, returns `sources_used`/`sources_failed`, treats empty sections as real 'no data', and returns `resolved:false` with notes for private companies. These are meaningful disclosures beyond the structured 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 nearly every sentence carries a distinctive fact: source list, return sections, soft-fail behavior, empty-section semantics, resolver behavior. It is front-loaded with the core purpose and example queries. It could be tightened with clearer structure, but it is not padded.

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

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

With no output schema, the description carries the burden of explaining return shape, and it does so thoroughly: it enumerates each returned section, explains `sources_used`/`sources_failed`, covers edge cases like private companies, empty FDA sections, and source sunsetting, and documents accepted input shapes. Nothing critical for invoking or interpreting the tool is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds useful nuance beyond the schema: `value` can be a zero-padded CIK, ticker, or company name; names resolve via SEC EDGAR; `type` accepts 'company' or 'ticker' interchangeably; and `resolved_from`/`resolved_to` appear when a name was resolved. This is modest but real added semantic guidance.

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 'full cross-source profile of a US public company in ONE parallel call' and provides concrete query examples ('Tell me about X', 'research Acme'). It clearly distinguishes itself from single-pack SEC/XBRL/news lookups, so an agent can tell what resource it targets and how it differs from alternatives.

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

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

The description explicitly states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' This gives a direct when-to-use rule and names the alternative approach it should supersede, leaving little to inference.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, covering the safety profile. The description adds context about clearing sensitive data but does not elaborate on return behavior, missing-key handling, or irreversibility, which is acceptable given the annotations.

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

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

Three short sentences: purpose, usage conditions, and related tools. Every sentence earns its place, with the action front-loaded. No redundant phrasing.

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

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

For a simple one-parameter tool with destructive and idempotent annotations, the description covers purpose, usage, and related tools. No output schema exists, but the description sufficiently frames the operation.

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

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

Schema coverage is 100% for the single 'key' parameter, which is already documented as 'Memory key to delete'. The description adds no new parameter-level meaning beyond what the schema provides, so baseline 3 applies.

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

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

The description begins with a specific verb ('Delete') and resource ('previously stored memory') plus method ('by key'), making the purpose unmistakable. It clearly distinguishes from siblings like remember (store) and recall (retrieve).

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 conditions ('context is stale, the task is done, or you want to clear sensitive data') and suggests pairing with remember/recall. It lacks when-not-to-use or alternative tools, but clear context is given.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds behavioral detail: fetches the page, extracts title/description/key links, and outputs a single text blob ready for site-root. No contradictions with annotations.

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

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

The description is three sentences with a clear action first, process second, and use cases third. It is well-structured and each sentence adds value, though the use-case list could be seen as slightly expansive.

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

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

For a simple tool with 2 parameters, the description adequately covers purpose, process, output format, and use cases. Since no output schema exists, the description's mention of a text blob fills that gap effectively.

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

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

Schema description coverage is 100%, so parameters are fully documented in the schema. The description does not add extra parameter context beyond what the schema provides, matching the baseline 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 explicitly states the tool generates a production-ready llms.txt file for any URL, with a clear verb+resource. It also describes the process (fetches, extracts, emits markdown) and distinguishes from sibling tools by focusing on file generation rather than just auditing.

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

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

Provides clear usage context with 'Useful for' scenarios including client indexing, personal projects, and competitor auditing. However, it does not explicitly mention when not to use it or alternative tools like scan_competitor_ai_presence.

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

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

Annotations already declare the tool read-only, open-world, idempotent, and non-destructive, so the bar is lower. The description adds behavioral context by specifying the output includes names, birth years, and biographical details, which goes beyond the annotations and helps the agent understand what to expect.

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 only two sentences, front-loaded with the purpose and then the required inputs. Every sentence adds information, and there is no redundant or extraneous text.

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

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

For a simple two-parameter tool with a rich output schema and strong annotations, the description is adequately complete. It covers what the tool does, what inputs are needed, and what users can expect in the output, making it sufficient for a straightforward query tool.

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

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

Schema coverage is 100% with descriptive property definitions for month and day. The description restates the same ranges (1-12, 1-31) without adding new semantic value beyond the schema, so the baseline 3 is appropriate.

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

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

The description clearly states the tool finds notable people born on a specific date, using the verb 'Find' with a specific resource. It distinguishes from sibling tools like get_deaths and get_events by focusing on births and listing the specific return data (names, birth years, biological details).

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

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

The description provides clear usage context: the tool is for finding births on a specific date, requiring month and day. It does not explicitly compare to alternatives or state exclusions, but the context is sufficiently clear to guide appropriate use.

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 readOnlyHint, idempotentHint, and non-destructive behavior. The description adds the scope 'notable people' and mentions return content, but with an output schema present, this adds minimal behavioral context beyond what annotations and schema provide.

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

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

The description is two concise sentences, front-loaded with the core purpose, with no wasted words.

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

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

For a simple two-parameter lookup with comprehensive annotations and an output schema, the description adequately covers the tool's purpose and input expectations. No additional context is necessary.

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

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

Schema coverage is 100% with both day and month described in the input schema. The description reinforces the format (1-12, 1-31) but does not add 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 uses the specific verb 'Find' and clearly identifies the resource as 'notable people who died on a specific date.' This distinguishes it from sibling tools like get_births and get_events by focusing on death and date.

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 use (providing a month and day to get deaths), but does not explicitly mention alternatives or when not to use this tool. It implies usage by stating the required inputs.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds value by disclosing the return content ('event descriptions, years, and details'), which goes beyond the annotations and gives the agent a clearer picture of the tool's output 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 two short sentences, front-loaded with the core action and then detailing parameters and returns. Every word earns its place with no redundancy or filler.

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

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

For a simple two-parameter tool with a well-defined input schema and an output schema present, the description provides enough context: what it does, what parameters are needed, and what it returns. It does not mention potential limitations (e.g., pagination, date range boundaries), but given the tool's simplicity and annotation coverage, this is not a significant gap.

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

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

The input schema already provides 100% coverage with descriptions for both 'month' and 'day', including their ranges. The description's mention of 'month (1-12) and day (1-31)' largely repeats the schema, adding no new semantic depth, 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 a specific verb ('Search') and resource ('historical events') with a date qualifier, making the tool's purpose unambiguous. It does not explicitly differentiate from sibling tools like get_births or get_deaths, but the term 'historical events' implies a broader scope, earning a 4 rather than a 5.

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

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

The description implies when to use the tool: for searching historical events on a specific date, with required month and day parameters. However, it provides no explicit guidance on when not to use it or how it relates to alternative sibling tools such as get_births or get_deaths, so the context is clear but exclusions/alternatives are missing.

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

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

The description discloses the return fields (id, type, params, created_at, last_fired_at, fire_count) and the scope ('caller's active subscriptions'). With annotations already indicating readOnly, idempotent, and non-destructive behavior, the description adds useful context about the response and scope 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?

Two sentences, front-loaded with the primary action and return value list. Every sentence earns its place: the first defines the operation and output, the second gives practical usage context. 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?

The description is complete for this simple tool: it states the return shape, clarifies the default scope, and provides usage guidance. The sibling tools include subscribe/unsubscribe, making the described use case meaningful. No output schema is needed since the description enumerates fields.

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

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

The input schema has 100% coverage for the single parameter, including its own description. The tool description adds minimal extra meaning beyond the schema, but it does imply that 'active' is the default and that include_inactive changes that, which is helpful context.

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

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

The description clearly states it lists the caller's active subscriptions, naming the resource and action. It also distinguishes itself by specifying the return fields and mentioning use cases relative to subscribe/unsubscribe ('before adding more', 'find an id to cancel').

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 given: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This defines clear contexts for use, though it does not explicitly state when not to use it or mention alternatives beyond the implied subscribe/unsubscribe siblings.

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

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

Annotations only say readOnlyHint=false, destructiveHint=false, adding no nuance. The description compensates richly by disclosing rate limits (5 per identifier per day), free/quota-free status, the claim_token workflow, and that 'the team reads digests daily and signal directly affects roadmap.' This is actionable behavioral context beyond the structured 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?

Though longer than average, every sentence carries a distinct, necessary piece of information: purpose, use cases, exclusions, token mechanics, and rate limits. The structure is logical and front-loaded; no filler or repetition of schema text.

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

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

For a 4-parameter tool with no output schema, the description covers everything an agent needs: what to report, when to use it, how to scope feedback, how to follow up with a claim_token, and operational constraints (rate limit, quota). It also anticipates the likely confusion about which server's tools are eligible.

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 descriptions for all parameters. The description adds value for claim_token ('Filing without an account returns a claim_token; pass it back later...') and reiterates the feedback-type categories, but largely reinforces rather than extends the schema. It crosses the baseline 3 by adding a concrete usage pattern for claim_token.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly differentiates this feedback tool from sibling research/retrieval tools by enumerating the exact categories it handles (bug, feature, data_gap, praise) and explicitly states what it is not for (other servers' tools).

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

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

Provides explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear exclusion and alternative: files for non-Pipeworx tools should go to that server instead, and tells users how to identify Pipeworx tools.

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

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

Annotations already establish read-only, idempotent, open-world behavior. The description adds non-obvious traits: derived from CF analytics-engine, no PII, cached 5min-1h, and aggregate format (pack, tool, count). This goes well beyond the structured 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 tightly formatted with a lead sentence, a bulleted 'Useful for' list, and a closing technical note. Each segment conveys distinct value with no filler or redundant restatement.

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 explicitly states what is returned (top tools, top packs, total call volume, aggregated as (pack, tool, count)) and notes the caching behavior. For a one-parameter read-only tool, this fully covers what an agent needs to know.

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 sole parameter (window) is fully described in the schema with enum values, and the description augments it with semantics: shorter windows surface current trends while longer windows show steady-state demand. This adds meaningful interpretive guidance over the raw schema.

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

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

The description opens with a clear statement of what the tool reports ('What other AI agents are calling on Pipeworx right now'), then enumerates the outputs (top tools, top packs, total call volume). This clearly distinguishes it from sibling discovery tools like discover_tools by focusing on live cross-agent usage trends.

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 three explicit use cases, giving concrete contexts for when to consult this tool (hot data sources, canonical tool confirmation, alignment check). It doesn't name alternative tools or state when not to use it, but the 'Useful for' list effectively communicates when it applies.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description discloses many behavioral details: the >3pp threshold for signal emission, the ≥0.30 Jaccard similarity anchor for cross-event pairs, the placeholder filter (>20% returns null), and the fill check logic (realizable_edge_pp ≤ 0 means do not trade). It also explicitly warns about false positives from last-trade only overrounds. This is exemplary transparency; nothing contradicts 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 every sentence carries meaningful information. It is front-loaded with the core purpose, then logically structured into mode explanations, semantic anchor, partition filter, response format, and fill check. Use of labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) makes it easy to parse. No redundant or filler content.

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

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

With no output schema, the description fully explains the return structure (opportunities[] with fields, partition_check in event mode) and notes edge cases (null arb signal for excessive placeholders). It also explains the meaning of key output fields (gap_pp, realizable_edge_pp) and provides a safety check. It even directs to a related tool for custom sizing, rounding out the operational context.

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

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

Even though the schema already describes both parameters (event and topic), the description adds substantial semantics: examples of valid slugs ('fed-decision-may-2026'), full URL acceptance, the distinction between single-event vs cross-event scanning, and the kind of seed question expected for topic mode. This far exceeds the schema's basic descriptions and helps the agent construct correct inputs.

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 distinguishes the tool's function from siblings like polymarket_edges or polymarket_fill_risk by focusing on arbitrage detection through specific mathematical checks. The three invocation modes (trending_scan, event, topic) further specify the scope and are named explicitly.

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

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

The description provides explicit when-to-use guidance: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It also offers mode-specific recommendations ('event (recommended for a specific market)') and points to an alternative tool for a related need: 'For custom sizing use polymarket_fill_risk.' This goes beyond basic usage and helps the agent select the right invocation.

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 readOnly/idempotent annotations, disclosing computation details (model families, slippage adjustments, Kelly caps), response structure (by_segment, diagnostics), limitations (Fed bets unreliable, rare-by-design, gate relaxations), and caching behavior. It also warns about 24h market moves that may negate the edge.

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 wall of text without section breaks, including implementation-specific details like per-sport α values and 'Run 8' gate relaxations that are unlikely to help an agent select or invoke the tool. While information-rich, it is not appropriately structured for quick scanning.

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

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

Despite no output schema, the description fully accounts for all 9 parameters, response top-level structure, diagnostics, and caching. It even explains why Fed bets are excluded and how to interpret empty segments, making it complete for a complex tool.

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

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

Schema coverage is 100%, but the description adds substantial meaning: it explains the rationale for slippage_pp default (zero fees but 20-50bp bid/ask), clarifies that min_partition_leg_kelly applies per-leg inside partitions, and describes how tradeable-edge knobs (max_spread_pp, min_liquidity) drop opportunities where edge isn't realizable.

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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also defines the intended use ('what should I bet on today') and distinguishes itself from sibling tools by focusing on Pipeworx-derived edge detection rather than arbitrage, tracking, or fill-risk tools.

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

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

The description gives clear usage context: 'Built for what should I bet on today' and notes that agents discover opportunities without paging hundreds of markets. However, it does not explicitly name alternative tools or state when not to use this tool, so it falls short of a 5.

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

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

Annotations already mark readOnly/openWorld/idempotent/non-destructive; description adds meaningful behavior: snapshot gaps, TTL limits, signed edge values, decay computed on absolute value, and no intraday data. No contradictions.

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

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

The description is dense but well-structured: purpose, args, response fields, limitations. All-caps field names aid scanning; every sentence contributes necessary operational detail.

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, but description fully explains the tracked/expired/snapshot_dates response fields, including edge cases like gaps and lifespan meaning. Complete enough to invoke correctly.

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

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

Schema already covers both parameters with descriptions, defaults, and clamps (100% coverage). The description restates defaults and introduces 'snapshot family' but does not add substantive semantics beyond schema.

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

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

Description states a specific purpose: edge persistence/decay telemetry answering 'how long has this edge existed and is it shrinking?'. This clearly distinguishes it from a current-edges tool like sibling polymarket_edges.

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 implies usage for historical edge analysis with examples (fresh vs 3-week-old edge) and describes data source. It does not explicitly name alternatives or say when not to use, but context is sufficient.

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

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

Beyond annotations (read-only, idempotent, non-destructive), the description discloses rich behavioral detail: it 'walks the ladder', returns specific computed outputs, and highlights risk like 'thin_legs[]' and 'forced_directional_risk naming the legs most likely to strand you unhedged.' No contradiction with annotations.

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

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

The description is lengthy but well-structured with mode labels and a clear progression from purpose to outputs to usage warning. Every sentence earns its place, though it could be tightened with bullet points for readability.

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 thoroughly enumerates return values for both modes, including edge cases like thin_legs and max_clean_notional_usd. It covers prerequisites, defaults, and risk implications, 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?

While schema coverage is 100%, the description adds substantial meaning: it explains mode-specific semantics (market vs event), side auto-detection in basket mode, size_usd interpreted as settlement notional with shares paying $1, and clamping (10–1,000,000). This goes well beyond schema descriptions.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly differentiates from sibling tools by explicitly naming polymarket_arbitrage and polymarket_edges as signals to precede, making the tool's unique role 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?

Explicit usage guidance is provided: '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 not capturable on thin books, partial fills create unhedged directional risk), and distinguishes single-market vs basket modes with clear conditions.

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 readOnlyHint/idempotentHint annotations, description adds crucial behavior: the token-overlap matching is not a shared resolution source, compatibility_codes are set even when matched_pairs>0, unknown legs are never paired, temporal_alignment null means 'could not compute' not 'aligned', and spreads are gross because Kalshi fees aren't modeled. This is rich disclosure 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 with labeled sections (RESPONSE, SAFETY FIELDS, codes, skipped counters) and front-loads the core purpose. Each sentence provides a safety or interpretation caveat essential for correct use, though some agents may find the density heavy.

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 and a complex response, the description must explain the return structure — it does so thoroughly: raw prices, top_spreads_pp with per-item flags, skipped_unclassified, low_confidence_pairs, temporal_alignment, fees_note, and skipped counters. It also gives interpretation guidance for every field and flag, making it effectively self-contained.

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 describes the three params (100% coverage), so baseline is 3. Description adds value by enumerating the valid topic values and explaining that explicit ticker/slug 'Override the topic-mapped' side, clarifying interactions between the params.

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?

Describes the tool as a 'Cross-venue spread between Kalshi and Polymarket for the same resolving question' — a specific verb, resource, and scope. It also distinguishes itself from related tools like polymarket_arbitrage by focusing on cross-venue spread and explicitly describing the two modes and output.

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

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

Explains two operating modes (topic shortcuts vs explicit ticker/slug) and clarifies that both run the same matcher, so agents know which params to set for which use case. Warns that 'pre-mapped ≠ tradeable' and most topics return compatibility warnings, setting expectations. However, it does not name alternative sibling tools, so it lacks explicit when-not-to-use guidance relative to other 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?

Adds valuable context beyond annotations: scoping ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and list behavior when key omitted. Annotations already declare readOnly/idempotent, so description complements them without 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, front-loaded: purpose first, then usage context, then scoping and relations. Every sentence earns its place without redundancy.

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

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

Simple tool with one optional param and no output schema. Description covers purpose, usage, scoping, and sibling relations. Return behavior is implied from 'Retrieve a value' and 'list all saved keys', so no significant gaps.

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

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

Schema coverage is 100% with key description 'Memory key to retrieve (omit to list all keys)'. Description reiterates this omit behavior but adds no new parameter-specific detail, so baseline 3 applies.

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

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

Description uses specific verbs 'Retrieve' and 'list' with clear resource ('value previously saved via remember', 'all saved keys'). It distinguishes from siblings by naming remember and forget.

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

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

Explicitly states when to use ('Use to look up context the agent stored earlier...') and provides alternatives ('Pair with remember to save, forget to delete'), giving clear usage guidance.

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

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

The description explicitly describes a state-changing operation ('Set mark_read:true to flag returned events read') while annotations declare readOnlyHint=true. This direct contradiction warrants a score of 1 per the rubric. The description otherwise adds useful context about the return payload and HTTP alternative.

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 the purpose, return payload, filtering, mutation caveat, and alternative access without redundancy. The core action is front-loaded.

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

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

For a read tool with 100% schema coverage and no output schema, the description covers the return payload, filtering, mutation behavior, and polling. It lacks explicit pagination details but is otherwise 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 baseline is 3. The description mentions filtering by type and since and mark_read, but provides no additional meaning beyond the schema's descriptions. The 'sec_8k' example is a minor addition.

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

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

The description clearly states the tool pulls fired events from the user's subscription feed and returns the most recent alerts with source, citation_uri, and raw payload. It distinguishes from sibling tools by focusing on fired events and the persisted feed, and even provides an alternative HTTP endpoint.

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

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

The description implies a polling use case ('Polls work fine') and explains how mark_read affects subsequent calls. It offers an alternative for scripts/dashboards via an HTTP endpoint but does not explicitly name sibling tools or state when not to use this tool.

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

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

The description goes well beyond the annotations by disclosing the fan-out to SEC EDGAR, GDELT→GNews fallback, USPTO's soft-fail due to PatentsView sunset, and the exact meaning of the 'since' parameter. It also describes the return structure, which is essential since no output schema is provided. No contradiction with annotations.

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

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

The description is front-loaded with use-case phrases, then systematically covers data sources, fallback behavior, date formats, output shape, and alternative tools. Every sentence adds information; there is no fluff or redundancy despite the 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?

For a tool with no output schema, the description fully explains what the tool returns (changes[] grouped by source, total_changes, citation URIs) and covers edge behavior (rate limits, API sunset, soft-fail). It also names the primary alternative, making the tool's scope complete for an agent to use correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description repeats the parameter semantics (ISO date vs. relative shorthand, ticker or CIK) already present in the schema, but adds no genuinely new param-level meaning beyond reinforcing examples 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 this is a 'change feed for a company in the last N days/weeks/months' and enumerates the natural language triggers it serves. It also explicitly distinguishes itself from entity_profile, making its purpose unambiguous and differentiating it from a key sibling.

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

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

It provides explicit usage cues ('What's new with X', 'latest on Y') and states when to use entity_profile instead ('when you want the static profile ... regardless of window'). It also explains the tool's parallel fan-out and fallback behavior, giving clear context for choosing it over alternatives.

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

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

Adds important behavioral details beyond annotations: stored as a key-value pair scoped by agent identifier, persistent for authenticated users, 24-hour retention for anonymous sessions. These details are not in the annotations and enhance the agent's understanding of the tool's behavior. 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?

Four sentences, front-loaded with the primary action. Each sentence contributes meaningful information (what, when, persistence, pairing with recalls/forget). No filler or redundancy.

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

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

For a simple 2-parameter memory tool with no output schema, the description covers all essential aspects: purpose, usage triggers, persistence semantics, and relationship to recall/forget. Nothing critical is missing.

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

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

Schema covers 100% of parameters with descriptions. The tool description repeats the key-value concept but adds no significant new parameter 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?

Description opens with 'Save data the agent will need to reuse later', clearly stating the action and resource. It distinguishes from siblings by explicitly pairing with recall and forget, and provides concrete examples of what to store (ticker, address, preference).

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 instructs 'Use when you discover something worth carrying forward' with examples. It also clarifies the relationship to sibling tools 'recall' and 'forget', giving clear context for when to use this tool versus alternatives.

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

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

Beyond the annotations (readOnly/openWorld/idempotent, non-destructive), the description discloses rich behavior: internal cascading across lookup endpoints, graceful degradation when GLEIF/OpenFIGI are unavailable, explicit `unresolved` reporting, labeling identifiers by source, ISIN-to-LEI mapping for non-US issuers, and the `figi_candidates` ambiguity behavior. It contradicts none of 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 front-loaded with the core purpose and 'Use FIRST' directive before diving into details. It is dense and at times long with nested parentheticals, but the length is used for high-value edge-case precision rather than filler. Structured labels like 'SUPPORTED TYPES' and 'LEI/FIGI enrichment' help navigate it.

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

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

With no output schema, the description carries the burden of explaining return behavior, and it does: identifiers are source-labelled, unresolved IDs appear under `unresolved`, ambiguous instruments return `figi_candidates`, and drug lookups yield RxCUI/ingredient/brand plus a citation. It covers accepted input formats, failure modes, and coverage limits (e.g., non-US issuers via ISIN-to-LEI), leaving no critical gap for an agent deciding whether and how to call it.

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

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

Although schema coverage is 100%, the description adds significant value: it reveals that company input also accepts ISIN (absent from the schema's value description), clarifies the exact naming requirement for bonds ('Pass the ENTITY NAME ONLY... never the question's full noun phrase'), and explains why trailing security-class words fail. It also documents the drug parameter's RxNorm citation. This exceeds the baseline for full-schema coverage.

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

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

The description opens with concrete query examples and states the core action: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It distinguishes itself from siblings by positioning it as the first stop when a name needs an ID ('Use FIRST whenever you have a name but need an ID') and enumerates supported types. This is a specific verb+resource statement with no ambiguity.

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

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

It gives an explicit trigger: 'Use FIRST whenever you have a name but need an ID' and illustrates with common phrasings (ticker/CIK/LEI/RxCUI lookups). It also tells when the ambiguous-result behavior is correct and that it replaces 2-3 manual lookups. However, it never names an alternative tool to prefer in other situations (e.g., entity_profile for richer entity details), so it lacks explicit when-not/alternatives guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds meaningful context by revealing that the tool probes each entity via ai_visibility_check, ranks results, and returns per-entity metrics (score, confidence, signal density), giving agents a clear behavioral model 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 three tight sentences that front-load the main action, then add behavioral detail, a use case, and output format. Every sentence earns its place with no redundancy.

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

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

With no output schema present, the description compensates by explicitly listing return fields (ranked list with score, confidence, signal density). It also explains the probe-and-rank workflow and the number of entities involved, making the tool's behavior fully understandable for decision-making.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minimal parameter-specific meaning beyond the schema, mostly restating the 'your brand + competitors' relationship already explained in the entities parameter description.

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

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

The description opens with a specific verb+resource: 'Compare AI visibility across multiple entities side-by-side.' It explicitly differentiates from sibling ai_visibility_check by emphasizing multi-entity comparison, ranking, and 'most/least recognized' output.

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

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

The description provides a concrete use case: 'competitive AI-marketing audits' with an illustrative question. It clearly implies this is for comparing multiple entities rather than a single check, but does not explicitly state when not to use it or name alternatives beyond referencing ai_visibility_check.

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 hints, so the description adds substantial behavioral context: it fans out to two services, returns a specific summary block, degrades gracefully on partial failures, and warns about a 5-30s possible delay for bundlephobia's first measurement. 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?

Every sentence earns its place: purpose, usage triggers, return fields, ecosystem scope, and failure behavior are all covered without redundancy. The description is front-loaded with the core use case and keeps the remaining info tightly packed.

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 listing the exact summary block fields, per-advisory detail, links, and alternative versions. It also covers timing, partial failure behavior, and ecosystem scope, making it complete for a complex composite tool.

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

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

Input schema covers both `package` and `version` with descriptions (100% coverage). The description adds no new parameter-level semantics beyond the schema; it only restates npm scope in prose. Per rubric, baseline 3 is appropriate when schema covers fully.

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 ('scan') and resource ('npm package'), and explicitly labels itself as a 'Composite check' aggregating deps.dev and bundlephobia. It clearly distinguishes itself from sibling tools by naming its cross-service scope and NPM-only ecosystem.

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

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

Provides explicit usage triggers ('Use whenever an agent asks "is X safe / popular / small"...') and an explicit exclusion for non-NPM ecosystems, directing users to 'deps.dev:version directly'. This covers both when and 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?

Beyond the readOnlyHint/destructiveHint annotations, the description discloses significant behavioral details: truncation at 200K chars with a flag, the embedding model and windowing strategy, and the return of offsets/scores. This exceeds what annotations provide and fully informs the agent of the tool's limits and output characteristics.

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

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

The description is dense but well-organized: purpose, usage scenario, complementary tool, implementation details, and limits. Every sentence carries useful information with no filler, and it front-loads the core 'semantic search inside a fetched record' concept immediately.

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 compensates by explaining the return format (passages with character offsets and similarity scores), the 200K char cap and truncation flag, and how it fits into a larger workflow. This is complete for a complex search tool.

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

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

Schema coverage is 100%, so baseline is 3. However, the description adds practical semantics by explaining what kind of text to pass (e.g., SEC 10-K body, article, long tool result), clarifies the 'query' is natural-language, and describes the result format (top-N passages with offsets/scores). This enhances the schema's basic descriptions without duplicating them.

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

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

The description states a specific verb+resource: 'Semantic search INSIDE a fetched record.' It clearly differentiates from siblings by emphasizing it operates on already-fetched text and explicitly mentions pairing with ask_pipeworx_grounded, making its unique niche 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?

Explicit usage guidance is provided: 'Use when the record is too big to cram into the prompt' and 'saves context, returns only the passages that matter.' It also names an alternative/companion tool (ask_pipeworx_grounded) and explains how they combine, giving clear when-to-use and when-not-to-use 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?

The description adds extensive context beyond annotations: auth requirements, inability for anonymous/BYO accounts to persist, phone verification and daily caps, webhook auto-disable after failures, and one-time signing secret. These are valuable behavioral traits not captured by 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 dense but well-structured, starting with purpose, then return value, prerequisites, types, and delivery options. Each sentence contributes useful information, though it reads as a long paragraph that could benefit from formatting.

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 and lack of output schema, the description covers the essential return (subscription id), delivery channels, and how to pull from the feed. It also mentions the webhook signing secret once, making it reasonably complete, though it doesn't detail full response structure.

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 goes beyond the schema by explaining the meaning of specific item codes (e.g., items:['5.02'] = officer change) and provides concrete examples for each subscription type, adding 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 'Create a proactive monitoring subscription to a live-data event stream' with a specific verb and resource. It distinguishes itself from siblings like list_subscriptions and unsubscribe by focusing on creation, and details supported 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?

The description explains when to use the tool (to subscribe to live data events) and includes prerequisites like requiring a Pipeworx OAuth account. It doesn't explicitly name alternatives but implies how it relates to recent_alerts and list_subscriptions via the persistent feed, giving clear 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 this as read-only, open-world, and non-destructive. The description adds valuable behavioral context: it returns category-bucketed example questions, includes exact tool + argument shapes, and explains the behavior for no-arguments vs. topic-passing. It also notes that the catalog is live and contains thousands of tools, which is useful 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 verbose but information-dense, front-loaded with example user intents. Every sentence contributes purpose, usage guidance, or parameter explanation. It could be tightened slightly, but the length is justified for an onboarding 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?

Given there is no output schema, the description adequately explains what the tool returns (category-bucketed example questions with exact tool + argument shapes). It covers both invocation modes (no args and with topic) and contextualizes the tool as the first step for a newly connected agent. The complexity is well served by this description.

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

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

Schema description coverage is 100%, so the baseline is 3. The description repeats the topic options and adds an example ('e.g. "finance", "pharma", "betting"'), but this is marginal beyond the schema. It does not add syntax or format details 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?

The description clearly identifies the tool as the onboarding entry point for discovering what questions to ask Pipeworx. It specifies the verb ('returns category-bucketed example questions'), the resource (the live catalog of tools), and distinguishes it from siblings like discover_tools by focusing on example questions with exact tool + argument shapes.

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 FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It does not explicitly mention alternatives or exclusions, but the 'FIRST' guidance and onboarding context make the intended usage 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?

The description adds important behavioral details beyond annotations: ownership enforcement (only your own subscriptions) and the soft-delete semantics (deactivated, not deleted, historical events remain via recent_alerts). 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 action. No wasted words; each sentence contributes meaningful information.

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

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

Given the simple signature (1 param, no output schema) and rich annotations, the description fully covers the essential context: how to use it, ownership constraints, and the non-destructive nature. It connects to recent_alerts for historical visibility.

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

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

Schema coverage is 100%, and the schema already documents 'id' as a UUID returned by subscribe. The description merely says 'by id' without adding new meaning, so the baseline 3 applies.

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

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

The description uses a specific verb ('Cancel') and resource ('subscription') with the method ('by id'). It clearly distinguishes from siblings like subscribe and list_subscriptions, and adds ownership enforcement for precision.

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 intended use is clear: cancel a subscription by id. While it doesn't explicitly name alternatives or exclusions, the ownership constraint and soft-delete behavior provide useful context. It could further mention checking list_subscriptions for valid ids, but this is not a major gap.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description adds crucial behavioral context: the meaning of 'could_not_verify' (check did not happen, not evidence), the distinction with 'unsupported', the routing to structured vs. grounded pipelines, and the verdict list. This is significant additional transparency 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 dense but well-structured: it opens with trigger examples, states the purpose, outlines the two processing paths, describes output, and highlights important caller caveats. Every sentence adds value, and the front-loading with example phrasings aids quick comprehension.

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

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

With no output schema, the description must explain what the tool returns, which it does thoroughly (verdicts, citations, reasoning, error semantics). It also covers edge cases (could_not_verify vs. unsupported), source flexibility, and performance context (replacing sequential calls). For a complex tool, this is complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description includes examples of the 'claim' parameter but adds no new semantics for 'tolerance_pct' beyond what the schema already explains (max deviation, defaults, overrides). No extra guidance is provided that isn't 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 opens with natural-language trigger phrases and states 'natural-language claim verification against authoritative sources,' giving a specific verb and resource. It clearly distinguishes this from siblings by describing the structured SEC EDGAR path for financial claims and the grounded pipeline for everything else, and notes it replaces 4–6 sequential calls.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' providing clear usage context. It does not name explicit alternatives or exclusions, but it does describe internal routing (financial vs. other claims), which guides usage.

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