Fyyd

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true and destructiveHint false. The description adds value by detailing per-model return structure ({score, confidence, signals, raw_response} + combined view) and cost implications of using the API key. 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?

Two sentences, no wasted words. Purpose, inputs, and output structure are front-loaded. Every sentence adds value.

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

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

With no output schema, the description explains the return format (per-model scores, combined view). It covers key use cases and parameter behavior. Could mention potential errors or model limits, but overall sufficient.

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

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

Schema coverage is 100% (all parameters described). The description adds context beyond schema, such as default model, API key usage, and the purpose of the 'context' parameter for disambiguation.

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 ('probe') and resource ('one or more LLMs') and clearly states the tool scores visibility (0-100). It distinguishes from sibling tools like deep_research or ask_pipeworx by focusing on AI brand awareness measurement.

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 context for use: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains default model and when to pass an API key for Anthropic. However, it does not explicitly mention when not to use this tool versus siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, so the description doesn't need to repeat those. It adds valuable behavioral context: the tool internally routes to 5,801 tools, fills arguments, returns structured answers with stable pipeworx:// citation URIs, and works on every tier with one fast call. This goes beyond the annotations without contradicting them, though it doesn't describe error handling or response format details, which is acceptable given the read-only, idempotent nature.

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

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

The description is long but every sentence earns its place. It front-loads the critical directive ('PREFER OVER WEB SEARCH'), then lists supported domains, provides examples, and finishes with explicit routing guidance to sibling tools. The structure is logical and scannable, with no filler or repetition.

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

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

For a tool of this complexity (routing to thousands of sources), the description covers all necessary aspects: what it does, when to use it, how it differs from alternatives, and what kind of input is expected. It mentions the return format (structured answers with citations) even without an output schema. An agent can confidently decide to invoke this tool and formulate a valid query based solely on 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?

The input schema has 100% coverage: each of the six parameters is an alias for the same 'question' field, and the schema already describes it as 'Your question or request in natural language'. The description reinforces this with multiple examples of valid questions, but it doesn't add new semantic meaning beyond the schema. Given the high coverage, a baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as a general-purpose question-answering service that routes queries to authoritative sources, returning structured answers with citations. It distinguishes itself from siblings by naming ask_pipeworx_grounded and deep_research as alternatives for different use cases. The verb 'ask' plus the resource 'Pipeworx' is specific, and the list of domains (SEC filings, FDA, FRED, etc.) leaves no doubt about its scope.

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

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

The description explicitly tells agents when to prefer this tool over web search and when to step up to alternatives: 'PREFER OVER WEB SEARCH' for factual questions, and 'Step up only when needed: for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research'. It also notes that breaking-news questions are handled internally. This is exemplary usage guidance with clear conditions and named alternatives.

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

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

The description clearly discloses that this is a full working router with no fallback, that candidate routing improvements are live only when under test, and that no candidate is currently active. It adds meaningful behavioral context beyond the readOnly/idempotent annotations, including the retire date and exact current parity with the stable version.

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

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

The description is information-dense and front-loads the most important fact: this is the beta version of ask_pipeworx. Each sentence contributes meaningful context about identity, behavior, status, and usage. There is minor redundancy between 'identical', 'same 5,801 tools...', and 'use it exactly like ask_pipeworx', but it does not hurt clarity.

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

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

The description covers the tool's identity, experimental status, current parity, usage, fallback behavior, and evaluation purpose. It adequately compensates for the lack of an output schema by stating that the response shape matches ask_pipeworx. It does not fully define what ask_pipeworx itself does, but the sibling context makes that gap acceptable.

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

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

The schema already documents the q, text, and input parameters as aliases for question, giving it full schema coverage. The description adds no further parameter semantics beyond noting that arguments are identical to ask_pipeworx. This matches 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 identifies this as a beta variant of ask_pipeworx, an identical universal router with the same 5,801 tools, arguments, and response shape. It distinguishes the tool from its stable sibling by emphasizing the experimental routing improvements. However, it relies on knowledge of ask_pipeworx to fully understand the core purpose.

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

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

The description says to use it exactly like ask_pipeworx when the agent wants the newest routing, which is a clear usage condition. It also explains that this is the experimental edge and that results are compared against the stable router. It does not explicitly say when not to use it or mention alternatives like ask_pipeworx_grounded.

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, non-destructive properties, so the bar is lower. The description adds substantial context beyond annotations: successful return shape, explicit refusal reasons, grounding-only behavior, and the extra LLM call cost. 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: core purpose, routing behavior, return/refusal contract, usage guidance, and cost tradeoff. The description is dense but well-structured and front-loaded with the most important distinguishing feature.

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?

Complete for a question-answering tool of this complexity: the description covers what it does, how it differs from the sibling, when to use it, what it returns on success and failure, and when to prefer the alternative. No important operational gap remains.

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

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

Schema description coverage is 100%, and the description adds no parameter-specific detail beyond what the schema already documents. The schema fully describes the question parameter and its aliases, 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?

States a specific verb and concept ('hallucination-resistant answer mode'), describes the extraction mechanism, and explicitly distinguishes itself from ask_pipeworx by the grounded extraction behavior. The agent can tell exactly what this tool is for and how it differs from its 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?

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts', with concrete examples. It also names the preferred alternative for casual lookups and states the cost tradeoff, making the selection decision fully specified.

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 details behavioral traits: market resolution, classification, fan-out to data packs, response shapes, resolver contract, parent event extraction, news fallbacks, safety short-circuits, wide spread handling, and resolution rules. Annotations only provide read-only, open-world, idempotent hints; the description adds critical context beyond annotations.

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

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

The description is long but well-structured with clear sections (classifiers, fan-out examples, response shapes, etc.). It is front-loaded with the main purpose. While detailed, every sentence adds value for understanding this complex tool.

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

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

Given the tool's complexity (multiple parameters, classification, fan-out, response fields, edge cases), the description is remarkably complete. It explains return values, safety mechanisms, resolution rules, and error states. No output schema exists, but the description compensates fully.

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

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

The input schema already has 100% coverage with descriptions, but the description adds significant value: it explains that market accepts slug, URL, or question text; depth defaults to thorough; include_raw default false and its implications. Examples clarify parameter 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 the tool researches a Polymarket bet by pulling relevant Pipeworx data in one call. It specifies input types (slug, URL, question text) and use cases ('should I bet on X', etc.). It distinguishes from sibling tools like polymarket_edges by being a broader research tool.

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

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

The description provides explicit use case examples and warns about when the tool short-circuits (low confidence, closed markets). However, it does not explicitly state when not to use the tool or compare to alternatives, leaving some ambiguity.

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

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

Annotations (readOnlyHint, idempotentHint, destructiveHint, openWorldHint) already convey safety and idempotency. The description adds no behavioral context beyond these annotations, such as what the category tree contains or how it is structured.

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 extremely terse (two words), but it is under-specified. Conciseness should not sacrifice completeness; this description lacks necessary action and context.

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

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

Despite having no parameters and rich annotations, the description fails to explain what the tool returns or how the category tree is represented. An output schema exists but is not described in text, leaving the agent uncertain about the response format.

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?

There are zero parameters, so schema coverage is 100%. No parameter description is needed. The rule for 0 parameters sets a baseline of 4, and the description does not detract from that.

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 'Category tree.' identifies a resource but lacks a verb (e.g., list, get, retrieve) to specify the action. It is ambiguous whether the tool returns, modifies, or traverses the tree, and it does not differentiate from sibling tools.

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

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

There is no guidance on when to use this tool versus alternatives. No context about prerequisites, typical use cases, or exclusions is provided.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds significant behavioral context: for companies it pulls specific financial metrics from SEC EDGAR/XBRL with correct fiscal year handling; for drugs it pulls adverse-event counts, FDA approvals, and trial counts; results are sorted by primary metric; returns paired data with citation URIs. This goes well beyond the annotations.

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

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

The description is moderately long but well-structured. It front-loads example queries and the key usage guideline. Every sentence adds value, though minor redundancy exists (e.g., 'side-by-side comparison' and 'in ONE parallel call'). Overall efficient.

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 explains return values: paired data + citation URIs. It covers both entity types and notes sorting behavior. It does not detail pagination or per-entity limits, but for a comparative tool this is sufficient.

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

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

Schema coverage is 100% with clear descriptions. The description adds value by explaining what each entity type returns (specific financials for company, counts for drug) and that values are tickers/CIKs for company and names for drug. It also notes the max of 5 entities per call.

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

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

The description clearly defines the tool as performing side-by-side comparison of 2-5 companies or drugs in a single call, using specific verbs like 'compare' and 'rank'. It distinguishes itself from sibling tools like 'entity_profile', which is likely a single-entity lookup, by explicitly stating it replaces sequential lookups.

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

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

The description explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides example queries indicating when to use (comparing, ranking, head-to-head). It lacks explicit exclusion cases, but the guidance is strong and clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and no destructive behavior. The description adds substantial context beyond annotations: account/sign-in requirements, latency expectations (15-60s, up to ~90s for thorough), explicit gaps[] for unanswered facets, contradictions[] for standard/thorough, stable pipeworx:// citations, and semantic excerpting of large records. It also clarifies this is NOT open-web search, a behavioral trait not visible in annotations.

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

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

The description is long but dense, with the account requirement front-loaded and the core purpose stated early. Nearly every sentence adds operational or selection value, though there is a minor structural typo around 'Thorough depth: standard and thorough also return contradictions[]' and some redundancy about the one-call nature. It earns a 4, not 5, due to slight clutter.

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 compensates fully: it explains the findings packet structure, verbatim evidence, confidence, source, fetched_at, stable citations, gaps[], contradictions[], excerpting behavior, latency, and account constraints. An agent has nearly everything needed to invoke and interpret the result correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the schema already documents both 'question' and 'depth' in detail. The description adds important selection-relevant meaning beyond the schema: 'thorough' requires a paid plan, the expected latency differs by depth, and the decomposition behavior is described. This lifts it above baseline.

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

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

The description states a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources... in ONE call.' It explicitly distinguishes itself from open-web search and from ask_pipeworx, naming the sibling it is not, so an agent can separate it from the sibling set.

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

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

The description gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and 'For a single lookup use ask_pipeworx instead.' It also covers the account prerequisite, the paid-tier requirement for 'thorough' depth, and the fallback to ask_pipeworx when not signed in. This is unusually complete routing guidance.

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

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

Annotations already provide readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds value by explaining that results include 'full input schemas (with curated examples)' and are 'ready to call directly,' which helps the agent understand the output format and usability.

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 achieve high density of information. First sentence states purpose and lists domains, second explains return format and usage guidance. No fluff, every word serves a role.

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 discovery tool without an output schema, the description adequately explains what is returned (tool names, descriptions, schemas) and how to use the results (ready to call directly). Lacks mention of pagination or error handling, but the core functionality is well-covered.

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

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

Schema coverage is 100% with clear descriptions for each parameter. The description adds context by listing all aliases (query, q, task, search, description) and providing examples that demonstrate usage. This goes beyond the schema's individual 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?

Clearly states the tool's purpose: 'Find tools by describing the data or task.' Provides specific examples (SEC filings, FDA drugs, etc.) and distinguishes from sibling tools by emphasizing discovery/browsing rather than specific domains.

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

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

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This guides the agent to use it for exploration before invoking specific tools, establishing clear when-to-use guidance.

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

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

Although annotations already mark the tool as read-only, idempotent, and non-destructive, the description adds crucial behavior: fan-out across many sources, `sources_used`/`sources_failed` semantics, empty sections meaning real absence of data, name resolution via EDGAR, and private companies returning `resolved:false` with a `notes` line. This goes well 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 dense and long, but nearly every part carries operational value: trigger phrases, usage preference, source list, return fields, failure semantics, input forms, and edge-case behavior. It is front-loaded with purpose and usage before the detailed return inventory, though some repetition of schema content adds minor noise.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: key fields, source coverage, fallback behavior, up-to-5 filings, and explicit handling of missing data. An agent can confidently invoke this tool and interpret its results without further lookups.

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, but the description adds useful value semantics: ticker, zero-padded CIK, or company name all work, and `type` is effectively interchangeable between 'company' and 'ticker'. It also explains resolution behavior and the private-company edge case, which are not fully captured in the schema's parameter descriptions.

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

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

The description specifies a clear action and resource: returning a full cross-source profile of a US public company in one call, with multiple trigger examples. It also contrasts with single-pack SEC/XBRL/news lookups, helping an agent distinguish it from narrower sibling tools.

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

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

It explicitly says to prefer this tool over chaining single-pack SEC/XBRL/news lookups when the user wants a holistic company view. It also clarifies behavior for private companies and the accepted input forms, leaving little ambiguity about when to select 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?

The description confirms the destructive nature ('delete', 'clear'), aligning with annotations (destructiveHint=true). It adds context about why deletion is appropriate (stale data, security) beyond what annotations provide, though it could mention reversibility or scope.

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

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

The description is two sentences: first sentence states the core action, second provides usage guidance and companions. It is efficient, front-loaded, and contains no unnecessary 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?

Given the simple nature of the tool (1 param, no output schema), the description sufficiently covers purpose and usage. It could be improved by noting behavior for missing keys or idempotency, but overall is adequate.

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?

With 100% schema coverage and a single parameter, the description does not add new semantics beyond the schema's 'Memory key to delete'. Baseline of 3 is appropriate as schema already documents the parameter adequately.

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

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

The description clearly states the action ('Delete') and the resource ('a previously stored memory by key'), directly matching the tool's name and title. It distinguishes from siblings by referencing 'remember' and 'recall', implying complementary roles.

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 specifies when to use the tool ('context is stale, task is done, clear sensitive data') and suggests pairing with related tools ('remember', 'recall'), providing clear context and alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive. Description adds behavioral details: fetches the page, extracts title/description/key links, emits markdown format. No contradictions. It does not mention rate limits or auth, but annotations cover safety.

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

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

Two concise sentences plus bulleted use cases. Front-loaded with main action and outcome. Every sentence adds value; no redundancies.

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

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

No output schema, so description should clarify return format. It says 'single text blob ready to drop at site-root/llms.txt' and mentions 'standard llms.txt markdown format', but does not specify if it returns the entire file content or provides examples. For a simple generation tool, this is adequate but could be more explicit.

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%; both parameters (url, max_links) have clear descriptions. The description rephrases 'url' as 'Full URL' and 'max_links' with default/max value but adds no new semantic value beyond the schema. Baseline score of 3 is appropriate.

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

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

Description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb (generate), resource (llms.txt file), and purpose (AI crawlers can index the site). It distinguishes from sibling tools like scan_competitor_ai_presence by focusing on file generation rather than 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?

Description explicitly lists use cases: indexing a client's site, drafting for own project, auditing competitor. However, it does not mention when not to use or contrast with alternative tools (e.g., scan_competitor_ai_presence), so it lacks exclusion guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds that the tool returns metadata and recent episodes, which is a minimal behavioral disclosure. 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 concise (5 words) and front-loaded with the key output. It could be improved by adding structure, such as listing what metadata is included, but it is not verbose.

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

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

Given the simple tool (1 param) and presence of an output schema, the description is adequate but incomplete. It does not mention that a podcast_id is required or that the result is specific to a given podcast. The agent must infer this from the name and schema.

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

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

Schema description coverage is 0%, and the description does not explain the podcast_id parameter. The tool name and description imply it's needed, but no details about format or constraints are provided. The description fails to compensate for the missing schema descriptions.

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

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

The description clearly states that the tool returns podcast metadata and recent episodes. It distinguishes from siblings like get_podcast_by_url (different input) and search_podcasts (search). However, it lacks an explicit verb (e.g., 'Get') and could be more specific about the resource scope.

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

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

No guidance is provided on when to use this tool versus alternatives like get_podcast_by_url or search_podcasts. The description does not mention that a podcast_id is required or that it should be used when the ID is known.

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

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

Annotations already declare readOnlyHint and idempotentHint, indicating safe, non-destructive behavior. The description adds that it resolves a URL to an ID, which is consistent. No extra behavioral traits (e.g., error handling, caching) are disclosed, but the safety profile is well 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 a single concise sentence with no unnecessary words. It efficiently conveys the core function 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?

Given the tool's simplicity (one parameter, annotations present, output schema exists), the description adequately covers the purpose. It could be slightly more explicit about the return value or error handling, but overall it is sufficiently informative for an agent to understand the tool's function.

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 0% with no descriptions for the single required parameter 'feed_url'. The description adds meaning by specifying it is an 'RSS feed URL', which clarifies the expected input beyond the parameter name 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 the tool resolves an RSS feed URL to its fyyd id. The verb 'resolve' and the specific resource (feed URL to ID) differentiate it from siblings like get_podcast which likely retrieves by ID.

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

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

No guidance is provided on when to use this tool versus alternatives (e.g., search_podcasts or get_podcast). The description does not mention any prerequisites, context, or exclusions.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds no new behavioral context (e.g., pagination, ordering, error handling), so the value beyond annotations is minimal. A 3 is appropriate as annotations handle the safety profile.

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 extremely concise (5 words) but under-specified. It lacks necessary detail while being front-loaded. It could be longer to add value without being verbose.

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

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

Given the tool has 3 parameters, an output schema, and annotations, the description is too sparse. It does not explain pagination, return format (though output schema exists), or the meaning of the podcast_id. The tool is inadequately documented 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?

The input schema has 0% description coverage, and the description makes no mention of the three parameters (podcast_id, page, count) or their roles. The schema only provides types and required status, leaving the agent without semantic understanding of the parameters.

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

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

The description states the resource (episodes) and qualification (latest, for a podcast), making the purpose mostly clear. However, it does not differentiate from sibling tools like search_episodes that could also return episodes.

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

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

No guidance is provided on when to use this tool versus alternatives such as search_episodes or get_podcast. There is no mention of prerequisites or when not to use it.

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

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

Annotations already indicate safe read-only behavior. The description adds context on default active-only filtering and return fields, which is helpful beyond annotations.

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

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

Two sentences, front-loaded with main action, 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?

Comprehensive given tool simplicity: lists action, return fields, usage context, and one optional parameter is documented. No output schema needed.

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

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

Single parameter is fully described in schema (100% coverage). Description does not add beyond schema, so 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 lists the caller's active subscriptions and specifies the returned fields. It distinguishes from sibling tools like subscribe/unsubscribe by stating its purpose for review before adding or canceling.

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 this to review what you're monitoring before adding more or to find an id to cancel.' This guides the agent on appropriate 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?

Since annotations are all false hints, the description bears full burden. It discloses the rate limit (5 per identifier per day), the asynchronous nature (daily digests), the claim_token behavior for tracking status, and that it's free. This gives the agent realistic expectations about side effects and return values.

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 not bloated; every sentence adds operational intelligence (scope, exclusions, token handling, rate limits). It's front-loaded with the core purpose and then details, making it scannable despite 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 feedback tool with no output schema, the description thoroughly covers what to submit, how to follow up, limitations, and expectations. It leaves no major gaps for an agent deciding whether and how to invoke this 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. Description adds value by explaining the claim_token's round-trip use case and coaching message content ('describe in terms of Pipeworx tools/packs — don't paste the end-user's prompt'), which goes beyond raw schema definitions.

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

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

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' which clearly states its purpose as a feedback channel. It distinguishes itself from sibling research/query tools by framing itself as reporting issues rather than retrieving information, and explicitly maps use cases to bug/feature/data_gap/praise.

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

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

It provides explicit when-to-use guidance: bug for wrong/stale data, feature/data_gap for missing tools, praise for positive experiences. It also gives a clear exclusionary rule: only for Pipeworx-served tools, not other MCP servers, and directs to file with the correct server instead.

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds meaningful context: data source (CF analytics-engine), privacy (no PII), caching behavior (5min-1h), and self-aggregating nature. 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?

Description is concise with bullet-pointed use cases, front-loaded with key output, and every sentence adds value. 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?

All necessary context provided: one optional param, source, caching, privacy, and three use cases. No output schema needed as return values are qualitatively described. Sufficient for agent to select and invoke correctly.

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

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

Schema coverage is 100% with full enum descriptions. The description does not add additional parameter info beyond the schema, which is acceptable since schema already explains window options and their trade-offs (hot vs steady-state). 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?

Description clearly states it returns top tools, top packs, and total call volume over configurable windows. Verb 'calling' combined with resource 'Pipeworx trending' and explicit output fields make purpose unambiguous. Distinguishes from sibling tools by focusing on trend aggregation rather than search or individual queries.

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

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

Provides three explicit use cases (discovering hot data sources, confirming canonical tool choice, checking alignment) with practical examples. Lacks explicit when-not-to-use or alternatives, but context is clear enough for decision-making.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and non-destructive nature. The description adds extensive behavioral context: monotonicity checks, partition-sum logic, Jaccard similarity threshold (0.30), placeholder filter (>20% placeholder fraction returns null), fill check against live CLOB depth, and response structure. 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 thorough but somewhat lengthy; however, it is well-structured with clear sections and front-loaded with the primary function. Every sentence adds value, though could be slightly more concise. 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?

Given the tool's complexity and absence of an output schema, the description provides near-complete context: it explains internal logic (Jaccard similarity, placeholder filter, fill check), response structure (opportunities[], partition_check with specific fields), and trade recommendations. References sibling tool for custom sizing, covering edge cases.

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 parameters with descriptions (100% coverage). The description significantly enhances understanding by explaining the difference between event and topic modes, providing concrete examples of valid values, and outlining the internal processes for each mode. This adds meaning beyond the schema alone.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes three modes: trending scan (no args), event mode (specific slug), and topic mode (cross-event scan). Each mode is explained with examples and recommendations, making the purpose highly specific and distinguishable from siblings.

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

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

Explicit guidance is given on when to use each mode: 'Call with NO args for a trending_scan', event mode recommended for specific markets, topic mode for cross-event scanning. It also warns against trading when realizable edge is non-positive via fill check. References sibling tool polymarket_fill_risk for custom sizing, providing clear when-to-use vs alternatives.

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

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

The description extensively discloses behavioral traits beyond annotations, including caching (1h at KV level), detailed segment logic, edge computation, diagnostic information, and knobs, with no contradictions to 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 extremely verbose (over 500 words) and includes detailed technical explanations that could be shortened. While structured, it lacks conciseness.

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 compensates for the lack of output schema by explaining response structure, segments, and diagnostics. It covers all aspects given the tool's complexity and provides sufficient context for an agent to use it correctly.

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

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

Schema coverage is 100%, so description adds limited extra meaning. It provides context on how knobs interact but does not significantly deepen understanding of individual parameters beyond the schema.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, distinguishing it from siblings like polymarket_arbitrage by specifying the data source and opportunity 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 indicates the tool is built for 'what should I bet on today' and mentions that Fed bets surface but are excluded, but it lacks explicit guidance on when to use this tool versus alternatives or when not to use it.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds behavioral context: data from daily snapshots, potential gaps, decay from daily closes (not intraday), and TTL limitations, which enriches understanding beyond annotations.

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

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

The description is front-loaded with the core question and provides dense information in each sentence. While lengthy, every part adds value, including response structure and limitations. Slightly verbose but well-organized.

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

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

Given no output schema, the description fully explains the response (tracked, expired, snapshot_dates) and covers limitations (TTL, decay calculation). It is complete for an agent to understand what to expect and when to use the tool.

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

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

Schema coverage is 100%. Description adds meaning by explaining the lookback (days) and snapshot family (window) with examples and defaults. It also details the response structure, helping agents understand how parameters affect output, though schema already defines constraints.

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

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

The description clearly defines the tool as providing edge persistence and decay telemetry from daily snapshots, answering how long an edge has existed and whether it's shrinking. It distinguishes from the sibling polymarket_edges by explaining it tracks history over time, not just current 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?

The description implies when to use (when edge age matters) through the contrast of fresh vs. 3-week-old edges. It does not explicitly exclude alternatives but contextually guides usage. However, it lacks direct mention of when not to use or explicit 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 annotations (readOnly, openWorld, idempotent), description details that partial basket fills convert arb into unhedged directional position and explains the dominant loss mode.

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?

Packed with essential info, front-loaded, but could be more structured (e.g., bullet points). Every sentence earns its place, though a bit lengthy.

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, yet description comprehensively explains return fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, verdict, etc.) for both modes, plus covers thin legs and forced directional risk.

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?

With 100% schema coverage, baseline is 3. Description adds meaning: clarifies size_usd in basket as settlement notional S, shares per leg paying $1; explains side default as auto from partition sum; and describes how each parameter affects behavior.

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 checks realizable-vs-theoretical edge against live CLOB order-book depth, distinguishes single-market and basket modes, and lists specific return fields. It distinguishes from sibling tools like polymarket_arbitrage.

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

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

Explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains why partial fills convert arb into directional risk.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, but the description adds substantial context beyond that: compatibility_warning/codes can be non-empty even when matched_pairs>0, temporal_alignment null means 'could not compute,' unknown legs are never paired, and skipped_cross_type/subtype counters expose dropped comparisons. The closing warning that most pre-mapped topics are not tradeable is honest behavioral disclosure. No contradiction with annotations.

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

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

The description is long but densely organized with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loads the core purpose in the first sentence. There is some redundancy—the temporal_alignment_unknown code and the temporal_alignment field are explained twice—so it is not maximally concise, but every major paragraph earns its place for a complex cross-venue tool.

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

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

With no output schema, the description compensates thoroughly by enumerating response fields, flags, compatibility codes, fees_note, and skipped counters, covering almost everything an agent needs to interpret results. The main gap is that with zero required parameters, the behavior when no arguments are supplied is never stated, and the explicit mode's dependency between kalshi_event_ticker and polymarket_event_slug is only implied by the '+' notation. This keeps it from a 5.

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

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

Schema coverage is 100%, so the baseline is already 3. The description adds meaningful semantics on top: topic auto-fetches a pre-mapped event, explicit ticker/slug overrides the mapped side, and both modes run the identical token-overlap matcher. It does not add much per-parameter syntax detail, but the override and mode-selection semantics are genuine additions 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 first sentence states a specific scope: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It distinguishes itself from sibling tools by emphasizing cross-venue comparison and by warning that pre-mapped topics are often not tradeable, which helps an agent separate this from tools like polymarket_arbitrage or polymarket_edges. This is far beyond a restatement of the name.

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 when-to-use guidance via TWO MODES: pre-mapped topic shortcuts or explicit ticker/slug pairs. It also steers agents away from treating the output as a net tradeable edge by noting that Kalshi fees are not modeled and spread_pp is gross. However, it never explicitly names a sibling tool as the alternative for net-of-fee analysis, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds scoping detail and behavior when key is omitted, providing context beyond annotations.

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

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

Description is front-loaded with primary action and usage context. A bit long but every sentence adds value; 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?

No output schema, but description explains return behavior for both keyed and keyless calls. Sufficient for a simple retrieval tool with one optional parameter.

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 3. Description adds meaning by explaining that omitting key lists all keys, and provides examples of what the key represents (ticker, address, etc.), going beyond the schema.

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

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

The description clearly states the tool retrieves a saved value via 'remember' or lists all keys when key is omitted. It distinguishes from siblings 'remember' and 'forget' by specifying the pairing.

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

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

Explicitly says to use for looking up stored context without re-deriving, and implies not to use for saving or deleting by mentioning 'pair with remember to save, forget to delete'.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. The description adds useful behavioral details: returned fields, mark_read flag behavior, and polling safety. 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 four sentences, each serving a distinct purpose (purpose, return fields, filter options, behavior note). No fluff, well 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?

Given no output schema, the description explains return fields (source, citation_uri, payload). Parameters are well covered with examples. Could mention pagination but not essential with a limit parameter. Overall complete for a low-complexity feed retrieval 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 all parameters are documented. The description adds context beyond schema: examples of type values ('sec_8k'), ISO timestamp for since, and the effect of mark_read. This adds meaning beyond what the schema 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 states the tool pulls fired events from the subscription feed, listing specific return fields (source, citation_uri, payload) and filter options. The verb 'Pull' and resource are specific, and the purpose distinguishes it from sibling tools like 'search_within' or 'recall'.

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 mentions polling suitability and an alternative GET endpoint for scripts/dashboards, implying when to use the tool (regular polling). It does not explicitly exclude alternatives or specify when not to use, but the context is clear enough for its niche.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds substantial context: parallel fan-out to multiple sources, fallback mechanism, soft-fail for USPTO, and return structure (changes grouped by source, total_changes, citation URIs). This goes beyond annotations.

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

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

The description is a single dense paragraph that front-loads the purpose. Every sentence adds value, but it could benefit from slightly more structure (e.g., bullets for sources). Still, it is appropriately sized and not verbose.

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

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

Despite no output schema, the description explains the return structure (changes grouped by source, total_changes, citation URIs). It covers all major aspects: sources, fallback, parameter formats, and distinction from entity_profile. Context is complete for the tool's complexity.

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

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

Schema coverage is 100%, but the description adds value: explains since accepts ISO or relative shorthand, recommends defaults (30d/1m), clarifies type is limited to 'company', and value can be ticker or CIK. This enriches parameter understanding.

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

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

The description explicitly states the tool provides a 'change feed for a company in the last N days/weeks/months' and lists example queries. It details the sources (SEC EDGAR, GDELT→GNews, USPTO) and distinguishes from entity_profile, making the purpose very clear.

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

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

It gives explicit guidance on when to use ('what's new' queries) and when to use entity_profile instead for static profiles. It also explains fallback behavior (GDELT preferred, GNews on rate limit), which helps the agent decide.

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

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

Annotations provide idempotentHint and destructiveHint; description adds value by explaining scoping by identifier, persistence for authenticated vs anonymous sessions, and pairing with recall/forget. No contradiction.

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

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

Well-structured, front-loaded with purpose, then usage, then details. No extraneous text; every sentence adds value.

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

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

Complete for a simple write tool. No output schema needed; description covers purpose, usage, and persistence. Sufficient context given 2 parameters.

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

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

Schema covers 100% with descriptions for both key and value. Description adds examples and clarifies value as any text, enhancing meaning 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?

The description clearly states the tool saves data for later reuse across conversations or sessions, using specific verbs and resource (key-value memory). It distinguishes itself from siblings like recall 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 instructs when to use (discover something worth carrying forward) and references alternatives (recall, forget). Provides clear context for usage.

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

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

Annotations already mark this as read-only, idempotent, open-world, and non-destructive, so the bar is lower, but the description goes far beyond that: it discloses graceful degradation when GLEIF/OpenFIGI are unavailable, explicit `unresolved` reporting instead of omission, `figi_candidates` when matches are ambiguous, and per-identifier source labeling. This is rich behavioral detail that annotations alone could not convey.

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

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

The description is an extremely long, single-paragraph wall of text with em-dash asides, parentheticals, and nested clauses. It lacks scannable structure, and the core purpose is buried after a long list of example queries. While every sentence carries information, the lack of brevity and organization makes it hard for an agent to quickly extract the key facts.

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

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

There is no output schema, so the description shoulders the burden of explaining return behavior — and it does: source-labeled identifiers, `figi_candidates`, `unresolved`, degradation, and even the internal cascade that replaces 2–3 manual lookups. Given the tool's complexity (two entity types, multiple identifier systems), the description is essentially complete for correct invocation and interpretation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds substantial value beyond the schema: for `value` it specifies passing the ENTITY NAME ONLY, warns that trailing security-class words break the FIGI lookup, and distinguishes issuer names from bond names. It also enriches the `type` enum by explaining the resolution paths for 'company' and 'drug'.

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 example queries (ticker, CIK, LEI, RxCUI) and states a specific verb+resource: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It also enumerates supported entity types and the exact identifiers each type yields, making the tool's function unmistakable even among many siblings.

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

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

It gives an explicit routing directive: 'Use FIRST whenever you have a name but need an ID.' It also clarifies accepted input forms (ticker, CIK, ISIN, name) and the distinction between company and drug lookups. It does not name alternative tools or provide 'do not use when…' conditions, so it stops short of full exclusion guidance.

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

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

Annotations already cover safety (readOnly, openWorld, idempotent). Description adds probe process, ranked list structure (score, confidence, signal density), complementing annotations 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?

Two concise sentences, front-loaded with core action, followed by example and return details. No superfluous 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?

Despite no output schema, description explains return fields and process. Parameters are fully covered by schema with description adding usage context. Sufficient for agent to select and 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 has 100% coverage. Description adds value by clarifying that first entity in 'entities' is treated as subject versus competitors, which is not in 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 clearly states the tool compares AI visibility across multiple entities, uses specific verb 'compare', resource 'AI visibility', and distinguishes from sibling 'ai_visibility_check' by referencing side-by-side comparison.

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

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

Provides specific use case example ('competitive AI-marketing audits') and example question, but lacks explicit when-not-to-use or alternatives beyond implied contrast with single-entity probes.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds value beyond: fans out across multiple sources, partial failures degrade gracefully, bundlephobia first measurement can take 5-30s. No contradiction.

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

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

The description is front-loaded with the main purpose and returns details. Every sentence adds value, though the paragraph is somewhat dense. Could be slightly more structured but remains clear.

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

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

With no output schema, the description thoroughly explains return values: summary block, per-advisory detail, links, alternative versions. Covers edge cases (partial failures, timing). Complete for a 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?

Schema coverage is 100%, so baseline is 3. The description adds the detail that version defaults to latest when omitted, which is helpful but not extensive. No additional meaning 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?

The description clearly states the tool is a composite check for adding an npm package, covering license, advisories, version history, and bundle size. It uses a specific verb and resource, and distinguishes itself from unrelated siblings.

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

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

Explicitly tells when to use: 'whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also notes ecosystem limitations (NPM only in v1) and directs other ecosystems elsewhere. Mentions partial failure handling.

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

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

Annotations already declare readOnlyHint and idempotentHint, covering safety. The description adds valuable behavioral context: matching against titles and descriptions, optional language filter, and the specific return fields. No contradictions with annotations.

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

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

Three sentences: first states purpose and scope, second lists return fields, third provides the use case. Front-loaded and free of 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 annotations and an output schema, the description covers search semantics, scope, and purpose well. It does not mention pagination, but that is not essential for a search tool of this simplicity.

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

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

Schema description coverage is 0%, so the description must compensate. It explains 'lang' as an optional language filter and implies 'term' as the search term, but 'page' and 'count' are not described at all, leaving a gap.

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 specifies the tool's function: search individual podcast episodes against terms in titles and show-note descriptions. It distinguishes itself from sibling tools like search_podcasts by focusing on episodes, and lists the exact output fields.

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

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

The description provides a clear use case: 'Answers which podcast episode covered a subject and where to listen to it.' This implies when to use the tool, though it does not explicitly mention alternatives or exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds meaningful behavioral context beyond annotations: pagination limit ('up to 30 per page'), return field set, and the specific 'fyyd podcast id' and 'RSS feed URL'. No contradictions found.

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

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

The description is two sentences, front-loaded with the primary purpose. Every sentence provides value: the first states input and pagination, the second states output fields and the core question answered. 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?

Given the rich annotations, output schema, and clear input schema examples, the description covers the essential operational details: input term, optional language, pagination, and return fields. It does not explain page semantics, but the schema example covers this, so the description is largely complete for this 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 50%, with term and page lacking descriptions. The description adds semantics for 'term' ('title term') and 'count' ('up to 30 per page'), and 'lang' is implicitly 'language code', but 'page' is not explained. It partially compensates for schema gaps but not completely.

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 ('podcast shows by title term'), and explicitly answers what the tool returns ('fyyd podcast id, title, author, description, RSS feed URL, artwork and episode count'). It distinguishes itself from likely sibling tools by focusing on discovering shows, not episodes.

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

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

The description implies usage ('search podcast shows by title term') and notes optional language restriction and pagination, but it does not explicitly state when to prefer this tool over alternatives like search_episodes, nor does it mention any exclusions or prerequisites. The context is clear but not fully explicit.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description adds critical behavioral details: truncation at 200K chars, embedding model (BGE-base-en), cosine similarity, 500-char overlapping windows, and character offsets. 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 three sentences, front-loaded with purpose, followed by use-case and technical details. Every sentence adds value 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?

Given the tool complexity (semantic search with windows/offsets/truncation), the description covers all aspects: usage, parameters, behavior, and output format. The lack of an output schema is compensated by describing return values (top-N passages with offsets and scores).

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

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

Schema coverage is 100%, and the description enriches each parameter: 'text' specifies max 200K chars, 'limit' default 5, 'query' includes examples. It also adds context like truncation and flagging, which goes beyond schema definitions.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' and specifies the exact use case (when a record is too large). It also distinguishes it from sibling tools like ask_pipeworx_grounded, making the purpose unmistakable.

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

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

The description explicitly says 'Use when the record is too big to cram into the prompt' and explains how it pairs with ask_pipeworx_grounded, providing clear guidance on when and 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?

The description discloses behavioral traits beyond annotations: it requires OAuth authentication, creates a persistent subscription, returns an id, and specifies delivery channel details (phone verification, SMS cap, webhook signature). 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 somewhat long but well-structured: purpose first, then types, then delivery channels. Each sentence adds value. Minor redundancy (e.g., repeating 'always-on persistent feed') could be trimmed, but overall efficient.

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 has 3 parameters, no output schema, and high schema coverage, the description fully covers required auth, type-specific filtering, delivery options, and constraints (e.g., SMS cap). It leaves no critical gaps for an agent to select and invoke correctly.

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

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

The schema coverage is 100%, and the description adds significant meaning: it explains each subscription type with examples, breaks down the params object per type, and details every delivery subfield (email pattern, SMS verification, webhook signing). This goes well beyond the schema's brief descriptions.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the new subscription id. It distinguishes from sibling tools like list_subscriptions and unsubscribe by defining its unique function.

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

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

The description provides when to use (for creating subscriptions) and specific prerequisites (Pipeworx OAuth account, supported types, delivery constraints). It implicitly suggests alternatives (e.g., list_subscriptions, unsubscribe) but does not explicitly state when not to use it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context about returning structured example questions and tool shapes, which is valuable beyond annotations. No contradiction.

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

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

Description is front-loaded with common queries, well-structured, and concise for the amount of information conveyed. Could be slightly trimmed but no waste.

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

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

Given the tool's role as an onboarding guide with a simple input schema and no output schema, the description is complete. Explains what is returned (category-bucketed examples with tool shapes) 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?

Schema coverage is 100% with a single optional parameter. Description adds meaning by listing example topic values (finance, pharma, etc.) and explaining behavior when omitted (full cross-category spread). This enriches the schema's 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 clearly states the tool's purpose: an onboarding entry point that returns category-bucketed example questions with exact tool+argument shapes. It distinguishes itself from sibling tools by being the first call when unsure about Pipeworx's capabilities.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and provides guidance on when to use with/without the topic parameter. Lists example focus areas and alternative meta-tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds value by specifying the 30-result limit and optional filters, which are behavioral details beyond annotations.

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

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

The description is a single sentence that is front-loaded with the core purpose and includes all essential information without any unnecessary 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?

Given the tool's simplicity (3 optional params, output schema exists), the description covers key aspects: what it does, filters, and result limit. It could mention sorting or ordering, 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 coverage is only 33% (only category has a description). The description adds meaning by stating that lang and category are filters and that count controls the number of results. This compensates for the missing schema descriptions, though it does not provide format details for lang.

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 'Return' and resource 'most popular podcasts on fyyd', clearly distinguishing it from sibling tools like search_podcasts, get_podcast, and latest_episodes.

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 mentions optional filtering by category and language, but does not explicitly state when to use this tool versus alternatives like search_podcasts or latest_episodes. Usage context is implied, not explicit.

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

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

The description adds significant behavioral context beyond annotations: ownership enforcement, deactivation instead of deletion, and impact on historical events. Annotations already indicate non-destructive and idempotent, and the description aligns and elaborates.

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 well-structured sentences with no redundancy. The action is front-loaded, and every sentence adds essential information.

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

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

For a tool with a single parameter, no output schema, and a simple action, the description provides enough context including side effects and data retention. It leverages the sibling tool 'recent_alerts' to complete the picture.

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

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

Schema coverage is 100% and the schema already describes the 'id' parameter as 'Subscription id (uuid) returned by subscribe.' The description only repeats 'by id' without adding new semantic details.

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

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

The description clearly states the verb 'Cancel' and the resource 'subscription by id'. It distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions' by specifying the action and ownership enforcement.

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 context on ownership enforcement and that the row is deactivated not deleted, hinting at when to use. Mentions 'recent_alerts' as an alternative for historical data, but does not explicitly state when not to use the tool.

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

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

Despite annotations already indicating read-only, open-world, and idempotent behavior, the description adds significant context: the distinct processing paths, the full verdict enum, the critical distinction between 'could_not_verify' (check did not happen) and 'unsupported' (no source exists), and the callers note that 'could_not_verify' must not be shown as evidence. No contradiction with annotations; rather, it enriches 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 long but every sentence carries unique information: trigger phrases, usage scope, dual-path routing, return values, and an explicit caller warning. It is front-loaded with the most important usage cues and logically organized from purpose to details to caveats, with no fluff.

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

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

For a 2-parameter tool with no output schema, the description covers all necessary context: what it does, when to use it, how parameters affect behavior (especially tolerance_pct), what verdicts are returned, and the crucial distinction between 'could_not_verify' and 'unsupported.' It also implies the output structure (value + citation + reasoning) sufficiently for an agent to invoke and interpret results.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra nuance beyond the schema, particularly for tolerance_pct: 'Overrides the tolerance implied by the claim wording — set 1–2 for hallucination detection where any material error must be refuted' and explains the default cap of 5. Claim examples are also provided, adding practical usage 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 opens with explicit trigger phrases ('Is it true that…', 'fact check', 'verify the claim that…') and states a specific verb+resource: 'natural-language claim verification against authoritative sources.' It also distinguishes itself from siblings by noting it replaces 4–6 sequential calls, making its 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 says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also details two usage paths (SEC EDGAR for company-financial claims, grounded pipeline for all other factual claims), providing clear context on when each path applies. This goes beyond a generic statement and helps select the tool correctly.

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