Cdec Ca

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

Beyond the readOnly and idempotent annotations, the description reveals important behaviors: the default model (Workers AI Llama-3.3-70b) is free, calling Anthropic requires a BYO _apiKey and incurs direct costs to the user, and the return structure is disclosed ('Returns per-model {score, confidence, signals, raw_response} + a combined view'). This is genuine behavioral context that helps an agent anticipate side effects and requirements.

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

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

The description is compact and front-loaded, with the primary action stated first. Each sentence carries unique information: purpose, default behavior/cost, return format, and use cases. No filler or redundant repetition of the schema or annotations.

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

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

Given the tool's moderate complexity (4 params, annotations, no output schema), the description covers all essential decision-making factors: what it does, what the return structure looks like, cost implications, and when to use it. The annotations already handle safety, so no further disclosure is necessary.

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

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

The input schema already covers all four parameters with 100% description coverage, but the description adds value by specifying the default model, clarifying that omitting 'models' uses only the free workers-ai model, and noting that _apiKey is only needed when 'anthropic' is included. This supplements the schema's existing descriptions with operational details.

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

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

The description opens with a specific verb and resource: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' This clearly states the tool's core function and distinguishes it from sibling tools like scan_competitor_ai_presence by focusing on knowledge scoring, not just presence detection.

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

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

The description provides clear use cases: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' This gives agents context on when to deploy the tool, though it lacks explicit exclusions or alternatives (e.g., 'use this instead of scan_competitor_ai_presence when...').

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, and description adds that it fills arguments and returns pipeworx:// citation URIs, works on all tiers, one fast call. However, no mention of potential failure modes or rate limits, so not a 5.

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 the most important instruction ('PREFER OVER WEB SEARCH'), then organized into categories, examples, and alternatives. Every sentence serves a purpose; 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?

Given no output schema, description explains return format (structured answer with stable URIs). It covers scope, use cases, examples, and alternates, making it fully contextual.

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 with alias descriptions. Description adds meaningful examples and trigger phrases that clarify what to put in the question parameter, which raises 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?

Clearly states it answers factual questions by routing to 5,521 tools and returning structured answers with citations. Examples and domain list (SEC, FDA, FRED, etc.) make it unmistakable. Explicitly differentiates from siblings by naming ask_pipeworx_grounded and deep_research.

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

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

Explicitly instructs to prefer over web search, gives trigger phrases and examples. Names alternatives for specific needs (grounded for hallucination-resistant, deep_research for broad multi-part). Says breaking-news is handled internally.

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

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

Beyond the annotations (read-only, open world, idempotent), the description discloses that candidate routing improvements are enabled live whenever under test, and that no candidate is active as of 2026-07-26, so behavior currently matches ask_pipeworx exactly. It also clarifies it's a full working router with no fallback, which is important behavioral context.

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

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

The description is four sentences but each contributes: beta status, current state, usage directive, and clarification that it's a full router. It's slightly longer than strictly necessary but still well-structured and 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?

The description covers purpose, relationship to the stable tool, current behavior, usage context, and response shape via reference to ask_pipeworx. With no output schema, the 'same response shape' statement provides sufficient expectation setting.

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 aliases for the question parameter well-documented. The description adds no new parameter semantics beyond noting identical arguments to ask_pipeworx, so it relies on the schema's already complete documentation.

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 version of ask_pipeworx, a universal router with the same 5,521 tools, arguments, and response shape. It explicitly distinguishes it from the stable ask_pipeworx by noting experimental routing improvements and the current state of no active candidate.

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

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

The description explicitly instructs to use it exactly like ask_pipeworx when wanting the newest routing, and notes results are compared against the stable router to decide merges. It implies an experimental edge for testing but doesn't provide explicit exclusions for when to prefer the stable version.

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, etc., but the description adds substantial behavioral context beyond that: it discloses the refusal behavior with specific refusal reason enums, the fact that answers are extracted only from tool results, and the return structure including evidence and confidence. This gives the agent a clear model of how the tool behaves under failure, which annotations cannot express.

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

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

The description is dense but every sentence earns its place: main purpose, routing behavior, extraction constraint, return shape, refusal reasons, use case, and cost/alternative. It is front-loaded with the core functionality, then flows logically into details. No filler or redundancy despite the length, which is justified by the complexity of the 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?

There is no output schema, so the description must carry the burden of explaining return values and failure modes, which it does thoroughly with a concrete return object and refusal_reason enum list. It also covers the relationship to siblings, performance cost, and the exact conditions for choosing this tool. For a tool with this complexity and no output schema, the description is remarkably complete.

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

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

Schema description coverage is 100% and the only meaningful parameter is the question text, with all other parameters being aliases. The description does not add syntax details beyond saying 'Your question in natural language,' but since the schema already fully documents all parameters, a baseline of 3 is appropriate. No additional semantic value is provided beyond what the schema already states.

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

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

The description opens with a specific verb and resource: 'Hallucination-resistant answer mode for high-stakes reads' and clearly distinguishes itself from the sibling 'ask_pipeworx' by emphasizing grounded extraction with evidence. It also names the exact alternative, making the tool's unique value explicit.

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

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

It explicitly states when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also provides a clear alternative and cost comparison: 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups.' This is textbook usage guidance with a when-not-to-use clause.

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

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

Even with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description adds extensive behavioral context: resolver match scores, status codes (low_confidence_match, market_closed_or_inactive), tradeability warnings, cancellation rules (refund_50_50, etc.), and GDELT fallback behavior. It does not contradict the annotations; 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 (~600 words) but structured with clear section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and front-loaded with the core purpose and use cases. Every section adds valuable operational detail, though some fan-out examples could be trimmed to improve 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?

Given the tool's complexity and the absence of an output schema, the description thoroughly covers return structure (result.market, analysis, evidence), the resolver contract, parent event extraction, news fallback fields, safety statuses, and resolution-rule risks. It leaves little ambiguity about what the agent will receive and how to interpret it.

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

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

The input schema already provides rich descriptions and examples for all three parameters (100% coverage), including default values and response size implications. The description restates the accepted market formats and depth behavior but adds no new parameter-level meaning beyond what the schema already documents, so the schema carries the burden.

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

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

The description opens with 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call,' a specific verb+resource statement. It clearly distinguishes from sibling tools by naming use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and providing classifiers and fan-out behavior, making the tool's purpose unambiguous.

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

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

The description gives explicit usage guidance with 'Use for' examples and safety caveats such as 'ALWAYS inspect these before trusting the analysis block' and 'Check this before sizing sports/esports/event-occurrence bets.' However, it does not explicitly name alternative tools to use instead, 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?

Even though annotations already indicate read-only/idempotent, the description adds valuable behavioral detail: data provenance (SEC EDGAR/XBRL, FAERS), expected output format (paired data + citation URIs), sorting by primary metric, and handling of off-calendar fiscal years. No contradictions.

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

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

The description is dense and packs a lot of actionable info with no filler, but it reads as a long, unbroken block of text. Breaking it into shorter bullet-style sentences could improve scannability, though every sentence earns its place.

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

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

Despite lacking an output schema, the description covers the full context: trigger phrases, entity types, data sources, sorting behavior, output format (paired data + citations), and even mentions the efficiency gain vs sequential lookups. This is sufficient for an AI to select and invoke the tool correctly.

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

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

Schema coverage is 100%, but the description greatly amplifies the semantics: it specifies which financial fields are retrieved for companies (revenue, net income, cash, long-term debt), which counts for drugs (adverse events, approvals, active trials), and gives explicit examples for values. This goes well beyond the bare 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 specifies a precise verb+resource action: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It differentiates from sibling tools like entity_profile and from sequential single-pack lookups, making the tool's unique role unmistakable.

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

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

Provides explicit usage triggers ('Compare X and Y', 'rank these companies'), clearly states when to prefer this tool over sequential lookups ('ALWAYS PREFER'), and gives per-type instructions with concrete data sources for company vs drug.

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

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

The annotations indicate read-only, idempotent, non-destructive, and open-world hints, but the description adds no behavioral details such as date range handling, output granularity, or constraints. Without description, the agent cannot know if this returns a single day's data or a range, or how missing data is handled.

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 fragment, not a sentence, and is under-specified rather than concise. It uses placeholder syntax that could apply to many tools, and while short, it does not earn its place because it conveys almost no actionable 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 having an output schema and annotations, the description is too incomplete for a tool with 4 parameters and time-series semantics. It fails to explain the meaning of 'daily data', the required start parameter's role or end parameter, and what constitutes valid sensor and station IDs. This is well below the minimum viable description for an agent to use the tool correctly.

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

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

The description vaguely signals that station and sensor are key parameters but does not explain their accepted values, units, or relationships. The schema only documents the start date format (25% coverage), and the description fails to compensate for the undocumented end, sensor, and station_id semantics.

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

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

The description "Daily data for (station, sensor)" lacks an explicit verb, essentially restating the title with a parameter pattern. It does not clearly state that the tool retrieves or returns daily measurements, making it vague and largely tautological. It distinguishes from siblings like hourly_data only via the word 'daily'.

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 mention of when to use this tool, prerequisites, or relationships to alternatives like hourly_data or event_data. The description provides zero guidance on selecting this over sibling tools.

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

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

Description goes well beyond the readOnly/idempotent annotations by disclosing account requirements, latency ('Expect 15-60s... up to ~90s'), and failure modes ('returns mostly empty gaps[]' for topics outside the catalog). It also commits to 'never invented' evidence and explains semantic excerpting, adding substantial behavioral context with no contradictions to 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 longer than usual but every sentence carries operational weight—account warnings, alternative tools, depth tiers, return format, and latency. It is front-loaded with the account requirement and fallback, and the density is justified for a multi-mode research tool, though it sacrifices brevity.

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

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

Given there is no output schema, the description thoroughly covers return values: it lists the findings packet fields (evidence, confidence, source, fetched_at, citation), gaps[], contradictions[], and hop. It also addresses edge cases like account tiers, unsupported topics, and citation_uri presence, making the tool's behavior fully understandable without an output schema.

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

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

Although the schema already documents both parameters (100% coverage), the description enriches them significantly: it explains the depth parameter's meaning via 'quick=3', 'standard=5', 'thorough=8' with hop and contradictions semantics, and advises on question phrasing for the question parameter. This adds practical insight beyond the enum labels.

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

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

The description opens with a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1452 STRUCTURED data sources' and immediately clarifies 'this is NOT open-web search', distinguishing it from general search tools. It provides concrete examples ('compare X and Y's regulatory + financial exposure') and contrasts with sibling ask_pipeworx, making the tool's 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 gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and when-not-to-use: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also covers account prerequisites and fallback behavior ('If you are not signed in, use ask_pipeworx instead'), naming alternatives clearly.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds behavioral context by stating that it 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and that each result is ready to call directly. This goes beyond the annotations by explaining the output format and readiness for direct invocation.

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

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

The description is structured as two sentences, front-loaded with purpose and usage. The second sentence is long but packs critical information about return value and invocation semantics, as well as a domain list. While the domain list is extensive, it is necessary to convey scope. No words are wasted, though it could be slightly tighter.

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

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

The tool has no output schema, so the description ably compensates by explaining the return format in detail: names, descriptions, full input schemas with curated examples, and readiness for direct calls. It also explains the 'top-N' behavior and the limit parameter's role. This makes the tool's behavior well-specified despite the absence of an output schema.

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

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

Schema description coverage is 100%, with all six parameters fully described in the schema. The description adds minimal parameter-specific meaning beyond the schema, mostly mentioning 'top-N' which relates to the limit parameter. The query parameter is described in both the schema and description consistently, but the description does not significantly extend the schema's parameter documentation.

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: 'Find tools by describing the data or task.' It explicitly enumerates the domains it covers (SEC filings, financials, FDA drugs, etc.) and distinguishes itself from siblings by positioning it as a meta-tool for discovering other tools, unlike the domain-specific 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?

Explicit usage guidance is provided: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This clearly tells the agent when to use this tool instead of directly calling a domain-specific tool.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses key behavioral traits: it fans out across multiple sources, returns specific fields like recent_filings with URIs, notes a soft-fail for patents due to the USPTO API sunset, and describes a GDELT→GNews fallback. This gives the agent a clear picture of what to expect.

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

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

The description is dense but every clause earns its place: examples, the core purpose, usage preference, the fan-out list, return details, caveats, and input format. It is front-loaded with user intents and structured with semicolons, making it easy to scan. No filler or redundancy.

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

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

With no output schema, the description carries the full burden of explaining return values. It does so thoroughly: CIK + company name, recent_filings with URIs, fundamentals with specific metrics and sort order, patents with a soft-fail note, news fallback, and LEI. It is complete for a profile tool of this complexity.

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

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

The input schema already has 100% coverage with detailed descriptions for both parameters ('type' with enum and 'value' with ticker/CIK examples and the name restriction). The description largely repeats this information with examples like 'AAPL' and '0000320193', adding minimal new semantic value beyond the schema.

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

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

The description clearly states a specific verb and resource: it builds a 'full cross-source profile of a US public company in ONE parallel call.' It lists the data sources and return fields, and it explicitly differentiates from sibling tools by saying to prefer it over chaining single-pack lookups and to use resolve_entity for names.

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

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

The description provides explicit when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also gives a clear alternative for a specific case: names are not supported, so use resolve_entity first. This is direct and actionable.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds no new behavioral context. It doesn't disclose return format, limitations, or any other runtime behavior. The phrase 'irregular data' is a data property, not a behavior, so the description contributes nothing 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 extremely short, but this is under-specification rather than conciseness. A single noun phrase cannot adequately describe a functional tool with four parameters. It lacks structure and substance, so it does not earn its place.

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

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

Given the 4-parameter schema, no parameter descriptions, and an output schema that isn't described, this description is wholly insufficient. An agent cannot reliably invoke this tool based on the provided information.

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

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

Schema description coverage is 0%, and the description does not explain any of the four parameters (start, end, sensor, station_id). The examples provide some implicit hints, but the description itself is silent, so it fails to compensate for the lack of schema documentation.

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 'Event-based irregular data' provides no verb or action, only a vague noun phrase that essentially restates the tool name. It fails to distinguish this tool from siblings like daily_data or hourly_data, making it a tautological restatement with no real purpose clarity.

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

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

There is no guidance on when to use this tool versus alternatives. The description and annotations contain no mention of appropriate scenarios, exclusions, or alternative tool names. With siblings like daily_data and hourly_data, the agent has no way to choose between them.

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 destructive and idempotent behavior, so the description adds value by specifying what is destroyed ('a previously stored memory') and why it might be used ('clear sensitive data'). This adds context 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 two sentences, front-loads the core action, and contains no filler. Every sentence contributes purpose or usage context, making it highly 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?

For a simple one-parameter deletion tool with rich annotations (destructive, idempotent), the description covers purpose, usage, and parameter context. No output schema exists, and the description need not explain return values. The tool is fully specified.

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 describes the only parameter 'key' as 'Memory key to delete', covering 100% of parameter semantics. The description redundantly mentions 'by key' but adds no additional parameter detail, so the baseline score of 3 is appropriate.

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

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

The description clearly states the action ('Delete a previously stored memory by key') with a specific verb and resource. It distinguishes itself from sibling tools like 'remember' (store) and 'recall' (retrieve) by making the delete operation explicit.

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

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

The description provides explicit use cases: 'when context is stale, the task is done, or you want to clear sensitive data'. It lacks an explicit when-not or alternative tool mention, but the single-purpose nature of the tool makes the guidance sufficient.

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

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

Annotations already declare read-only and idempotent behavior. The description adds value by disclosing the fetch operation, extraction steps, and output format ('single text blob'), which goes beyond the annotations. It does not discuss error handling or rate limits, but the added context is meaningful.

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 (three sentences) and front-loaded with the primary purpose. It includes process, output, and use cases with no wasted words, making it easy to scan.

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

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

For a tool with no output schema, the description clearly states the output is a 'single text blob ready to drop at site-root/llms.txt' and covers the core workflow. It doesn't mention error handling, but for a simple read-only tool it is sufficiently complete.

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

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

Schema description coverage is 100%, with both `url` and `max_links` already well-described in the schema. The description adds context about 'key links' but does not provide additional parameter syntax or examples beyond the schema. 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 states a specific verb and resource: "Generate a production-ready llms.txt file for any URL." It explains the outcome (indexing by AI crawlers) and the process (fetches, extracts, emits), clearly distinguishing it from sibling tools like scan_competitor_ai_presence by focusing on file generation.

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

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

The description lists three explicit use cases (client sites, own project, competitor audit) under 'Useful for.' While it doesn't mention alternatives or when not to use the tool, the clear use cases provide strong contextual guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. However, the description adds no additional behavioral context such as pagination, filtering behavior, or response characteristics, and merely repeats the noun phrase already implied by the name.

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?

While the description is extremely short, it is under-specified rather than concise. Two words add no operational value, and the description does not earn its place as a useful specification.

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 annotations and an output schema, the description is entirely inadequate for a data-query tool with four parameters and three required fields. It provides no context about what hourly data is returned, how to filter it, or how it relates to sibling tools like daily_data or event_data.

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 provides no explanations for the four parameters (start, end, sensor, station_id). With required parameters and no semantic detail, the agent has no basis to understand what values to supply or how they affect the query.

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

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

The description 'Hourly data.' is a direct restatement of the tool name and title, providing no verb or action. It fails to specify what the tool does with hourly data (e.g., retrieve, query, list) and does not distinguish it from sibling tools like daily_data or event_data.

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

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

The description provides no guidance on when to use this tool versus alternatives such as daily_data or event_data. There is no context, prerequisites, or exclusions, leaving the agent to guess the tool's intended use case.

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 no behavioral context beyond the annotations. It does not explain how 'latest' is determined, whether a single record or a series is returned, or any edge cases. Annotations already indicate the operation is read-only and idempotent, but the description contributes nothing additional.

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 phrase, but it is under-specified rather than concise. It lacks a sentence structure that states purpose or scope, so it fails to earn its place as a useful description.

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

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

While output schema and annotations exist, the description is too vague to tell an agent when to choose 'latest' over similar time-series tools. The tool's role in the domain remains unclear, making selection and correct invocation difficult.

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 'Latest value' provides no explanation of the sensor or station_id parameters. The examples in the schema are the only hints, but the description itself fails to add meaning or usage details for 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 'Latest value' merely restates the tool's name and title without specifying what kind of value, for which sensor or station, or what action is performed. It does not distinguish from sibling tools like daily_data or hourly_data, making it effectively a tautology.

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 daily_data, hourly_data, or event_data. There is no mention of time frames, data granularity, or prerequisites for invocation.

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

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

Despite the annotations already declaring readOnly, openWorld, idempotent, and non-destructive behavior, the description adds meaningful context by specifying the scope ('caller's'), the default state ('active'), and the exact response fields (id, type, params, created_at, last_fired_at, fire_count). This goes beyond the annotations and helps the agent understand what to expect.

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

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

The description is three concise sentences, with the primary action and scope front-loaded, followed by return fields and usage guidance. Every sentence provides value; there is no redundancy or unnecessary detail.

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

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

For a low-complexity list operation with one optional parameter, complete annotations, and no output schema, the description is fully adequate. It covers the scope, default behavior, return fields, and practical use cases, leaving no significant gaps.

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

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

The input schema already fully describes the only parameter (include_inactive) with a clear description, including its default behavior. The tool description does not add any additional parameter-level semantics, so a baseline score of 3 is appropriate.

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

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

The description clearly states the action ('List'), the resource ('the caller's active subscriptions'), and distinguishes itself from sibling tools like subscribe and unsubscribe by emphasizing review and cancellation id lookup. It also enumerates the exact return fields, adding specificity.

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 the agent when to use this tool: 'before adding more' (i.e., before subscribing) and 'to find an id to cancel' (i.e., before unsubscribing). This directly references the actions of sibling tools, giving clear usage context without 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?

The description discloses rate limits (5 per identifier per day), free usage (doesn't count against tool-call quota), and the claim_token round-trip workflow. These are meaningful behavioral details well beyond the annotations (which are all false). It also explains that the team reads digests daily and signal affects roadmap, setting expectations.

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

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

The description is long but each sentence carries useful info, and it is structured logically: purpose → usage scenarios → scope → claim_token flow → expectations → limits. It front-loads with the primary purpose, though some redundancy with schema descriptions (e.g., 2000 chars max) could be trimmed.

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 4 params, nested objects, and no output schema, the description covers intake instructions, scope limitations, the claim_token lifecycle, rate limits, and what the team does with feedback. It comprehensively explains how and when to use the tool without needing an output schema.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond the schema by instructing users to 'describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt' and explains the claim_token usage pattern explicitly. This enhances parameter understanding even though the schema is detailed.

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

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

The description opens with a clear, specific action: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It names the resource (Pipeworx team/tools) and the four feedback types. It also distinguishes itself from siblings like ask_pipeworx by focusing on reporting issues rather than asking questions.

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

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

Explicit scenarios are listed: bug, feature/data_gap, praise, and it explicitly warns against reporting issues for non-Pipeworx MCP servers, redirecting to the appropriate place. It also clarifies that Pipeline tool names are those listed by this connection, reducing 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?

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description adds valuable context: it is a self-aggregating signal derived from CF analytics-engine, contains no PII, returns a simple (pack, tool, count) structure, and is cached for 5min-1h depending on the window. This goes well beyond what annotations alone 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 well-structured: an engaging opening sentence, a clear listing of return values, a bulleted list of use cases, and a concise note on data source and caching. While slightly longer than the two-sentence minimum, every sentence earns its place and there is no fluff.

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

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

For a simple tool with one optional parameter and no output schema, the description thoroughly covers what the tool does, what it returns, when to use it, and how the data is sourced and cached. The return format is described at a high level, which is sufficient given the lack of an output schema.

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

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

The only parameter, window, is fully documented in the schema with enum values, defaults, and trade-off descriptions. The tool description repeats this information but adds no new semantic meaning. With 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description opens with a clear, specific statement: 'What other AI agents are calling on Pipeworx right now.' It explicitly names the resources (top tools, top packs, total call volume) and the time windows. This distinguishes it from sibling tools like discover_tools or ask_pipeworx, 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 provides three concrete use cases (discovering hot data sources, confirming canonical tool choice, aligning with agent demand) and explains the trade-offs between shorter and longer windows. While it doesn't explicitly name alternatives or say 'use X instead', the context is clear enough to guide appropriate usage.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description reveals deep behavioral details: the ≥0.30 Jaccard similarity anchor, placeholder slug filtering, the >3pp tolerance for partition deviations, and the fill-check pricing against live CLOB depth. It even warns that a non-positive realizable edge means the opportunity is not tradable.

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 logically ordered: purpose, usage modes, algorithm details, edge-case filters, response format, and fill-check guidance. It is dense and every sentence contributes, but the heavy text block could benefit from bullet points or subheadings for readability. Still, 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?

With no output schema, the description thoroughly specifies return values for both modes, including exact field names like gap_pp, suggested_trade, and partition_check. It also covers edge cases and tool boundaries, making it a complete specification for an agent to use this tool correctly.

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

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

Although the schema already describes both parameters well (100% coverage), the description adds crucial context: what happens with no arguments, concrete examples of event slugs and topics, the algorithmic distinction between event and topic modes, and the response structure for each. This substantially exceeds the schema's baseline.

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

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

The description opens with a clear verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes itself from siblings by focusing on arbitrage and explicitly referencing polymarket_fill_risk for custom sizing, making the tool's scope unmistakable.

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

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

Usage is explicitly specified: no args for trending_scan, `event` for a specific market, and `topic` for cross-event scanning. It also names an alternative tool (polymarket_fill_risk) and explains when not to trade based on the fill check, giving clear decision boundaries.

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, open-world, idempotent, and non-destructive. The description goes far beyond by detailing the three model families and their logic, the net-of-slippage edge, the Kelly caps, the 24h-move warning, the caching at KV level, and the diagnostic output (funnel counters, filter_skips) that reveals why segments might be empty. It also discloses the unreliability of the Fed signal, adding valuable behavioral context.

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

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

The description is dense but well-structured, front-loaded with the purpose and then organized into model families, knobs, response format, and caching. Every sentence carries substantive information, though the single block of text could be more scannable with clearer sections or lists. It is appropriately sized for the tool's complexity.

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

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

With no output schema, the description must explain return values, and it does so thoroughly: response top-level includes by_segment, fed_candidates/fed_note, and _diagnostics; each opportunity carries edge_pp_net, kelly_fraction, kelly_fraction_half, market liquidity/spread/volume, and a 24h-move warning. It also explains why segments can be empty via funnel counters and filter_skips. The description is complete for an agent to use the tool effectively.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by explaining min_partition_leg_kelly in the context of basket trades, clarifying that min_edge_pp is net of slippage, and providing practical guidance on slippage_pp (zero fees, typical 20-50bp). This adds value beyond the schema's self-contained parameter descriptions.

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

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

The description clearly states the tool's function: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It uses a specific verb-and-resource structure and explicitly mentions the intended use case ('what should I bet on today'), effectively distinguishing itself from sibling tools like polymarket_arbitrage and polymarket_edge_tracker.

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

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

The description explains when to use the tool: to discover opportunities without paging hundreds of markets, and notes that Fed bets surface here but are excluded from ranking. It does not explicitly name alternatives or state 'when not to use,' but the intended context is clear and practical.

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

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

The description goes far beyond the annotations (which already declare read-only, open-world, idempotent, non-destructive). It details critical behavioral aspects: snapshots are written on cache-miss, gaps mean no scan occurred, history depth is bounded by a 60-day TTL, and decay metrics are based on daily closes rather than intraday data. This enriches the agent's understanding of data reliability and limitations, adding significant value beyond the structured annotations.

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

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

Despite being lengthy, the description is highly structured with clear sections (Args, RESPONSE, LIMITS) and uses bold/uppercase headers for readability. Every sentence carries substantive information: the opening question, parameter defaults, response shape with enumerated fields, and limitations. There is no redundancy or filler; the length is proportionate to the tool's complexity.

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

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

With no output schema, the description takes full responsibility for explaining the return value, and it does so in detail: tracked[] with full time-series and trend classification, expired[] with lifespan_days, and snapshot_dates[]. It also covers operational constraints (TTL, cache-miss gaps) and clarifies the meaning of negative edge values. This is a complete, self-contained explanation that enables 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?

The input schema already covers both parameters with descriptions and defaults (100% coverage). The description adds meaningful context by framing 'window' as a 'snapshot family' (24hr | 1wk | 1mo), which clarifies the concept, and reinforces the days default and max. It also explains the response uses these parameters to pull time-series data. This is a moderate enhancement over the schema, justifying a score above the baseline.

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

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

The description clearly states the tool's function: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and poses the key question it answers: 'how long has this edge existed and is it shrinking?'. This distinguishes it from sibling tools like polymarket_edges (which likely generates current edges) by focusing on historical persistence, and from polymarket_arbitrage by targeting edge decay rather than spread analysis.

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

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

The description implies when to use: to differentiate between a fresh wide edge and a 3-week-old wide edge, suggesting it's for evaluating whether an edge is still viable. It also mentions 'the median lifespan is your competition clock', providing practical context. However, it does not explicitly name alternative tools or state when NOT to use this tool, so it falls short of full exclusionary guidance.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the tool is known to be safe. The description adds substantial behavioral context: it 'walks the ladder,' returns specific metrics like slippage and max_fillable_usd, and warns about the dominant loss mode (partial basket fills converting an arb into an unhedged directional position). This far exceeds the baseline set 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 long but densely packed with essential information, structured into clear sections (overview, required mode, single-market, basket, usage guidance). Every sentence adds value — no filler or tautology. The most important usage guidance is front-loaded in uppercase, and the format is easy to scan.

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

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

Given the tool's complexity (two modes, many return fields, no output schema), the description is remarkably complete. It explains the exact return values for both modes, names the risk factors (thin_legs, forced_directional_risk), and provides actionable guidance on when to use it. There is no missing information that would prevent an agent from selecting and invoking the tool correctly.

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

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

Schema description coverage is 100%, so baseline is 3. However, the description adds critical semantics beyond the schema: for market mode, size_usd is 'max spend on buys, target proceeds on sells'; for basket mode, it's 'settlement notional — shares per leg, each paying $1 at resolution.' It also clarifies the side parameter's defaults and auto behavior in basket mode, which is not in the schema.

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

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

The description starts with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes single-market mode from basket/partition mode and differentiates itself from siblings like polymarket_arbitrage and polymarket_edges by framing the check as a pre-trade validation 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?

Explicit usage guidance is given: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains when to use each mode (single-market vs basket) and how to choose the side, making alternatives and exclusions 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 only provide readOnly/idempotent/openWorld hints. The description goes far beyond by disclosing compatibility_warning conditions, temporal_alignment semantics, and skipped_cross_type/subtype counters. It also transparently warns that 'most pre-mapped topics return compatibility_warning today,' setting correct expectations.

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

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

The description is front-loaded with the core purpose and then methodically covers modes, response, safety fields, and a caveat. It is long, but every sentence contributes critical information for a complex tool. The lack of bullet points or paragraph breaks slightly hurts scannability, but it remains appropriately sized for the tool's complexity.

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

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

Despite having no output schema, the description explains the response shape ('leg-by-leg prices ... plus matched spread[].top_spreads_pp') and all key safety fields. It even covers edge cases like temporal misalignment and non-equivalent bet shapes. The final caution about pre-mapped topics is valuable operational context that fully equips 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 meaningful context by grouping parameters into two modes and explaining that explicit tickers/slugs override the topic mapping. For 'topic', it clarifies that shortcuts 'auto-fetch the matching event on each venue,' which adds behavioral nuance not in the schema.

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

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

The description opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' a specific verb+resource that clearly defines the tool. It also distinguishes from siblings by emphasizing the safety logic (e.g., 'when the bet shapes are equivalent that delta is a real signal, when they aren't the tool says so') and from other polymarket tools like 'polymarket_arbitrage' or 'polymarket_edges'.

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

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

The description explicitly explains TWO MODES ('topic' shortcuts vs explicit ticker/slug) and gives detailed when-not guidance: 'aligned:false means spreads are mathematically meaningless across the temporal gap' and 'pre-mapped ≠ tradeable.' It effectively tells an agent both how to invoke the tool and when to be cautious about its results.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: scoping to identifier types (anonymous IP, BYO key hash, account ID) and the omit-key-to-list behavior. 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?

Four compact sentences, each earning its place: core action, usage example, scoping, and sibling pairing. The description is front-loaded with the primary behavior and contains no filler or redundancy.

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

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

For a simple read-only tool with no output schema, the description covers the return behavior (value or list of keys), the intended use case, the scope, and related tools. No important gaps remain.

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

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

The schema already documents the sole 'key' parameter and explains that omitting it lists all keys (100% schema coverage). The description adds semantic value by giving example key types ('user's target ticker, an address, prior research notes') and noting that saved values come from remember, helping the agent compose meaningful key arguments.

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 'Retrieve a value previously saved via remember, or list all saved keys,' naming a specific action and resource, and clearly distinguishes the dual behavior of fetching vs listing. It also explicitly references sibling tools (remember, forget), making its purpose unambiguous within the tool family.

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 concrete usage context ('Use to look up context the agent stored earlier... without re-deriving it from scratch'), explains the scope ('Scoped to your identifier'), and explicitly names alternatives: 'Pair with remember to save, forget to delete.' This clearly tells the agent when to use recall versus related tools.

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

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

The description discloses the mark_read side effect ('flag returned events read so the next call only shows newer ones'), a behavioral trait beyond the safety hints. It also describes the return content and persistence, adding context not available from annotations. There is no contradiction with the readOnlyHint since the side effect is optional and off by default.

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-loads the core function, and each sentence contributes distinct context: return fields, filtering/side effects, and alternative access. No redundant or fluff content.

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

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

With no output schema, the description adequately describes the return payload (source, citation_uri, raw event payload). It covers persistence, filtering, mark_read behavior, and polling, which is complete for a tool with 5 optional parameters and no destructive actions.

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?

All 5 parameters have descriptions in the schema, giving a baseline of 3. The description adds a concrete type example ('sec_8k') and explains mark_read's impact on future calls, enriching semantics for those parameters. Other parameters (limit, since, unread_only) are left to the schema, so not fully enriched.

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

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

The description opens with a specific verb phrase 'Pull fired events from your subscription feed', clearly identifying the action and resource. It further details the returned fields and filtering options, distinguishing it from generic tools like 'latest' or 'recent_changes' by focusing on the evaluator's alert feed.

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 usage context by noting 'Polls work fine' and offering an alternative HTTP endpoint for scripts/dashboards, implying interactive use for this tool. However, it does not explicitly reference sibling tools or state conditions when not to use this tool, so guidance is clear but not exhaustive.

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

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

Beyond annotations, the description reveals the parallel fan-out behavior, GDELT-to-GNews fallback on rate limits/5xx, the PatentsView API sunset soft-fail, and the exact return shape (changes[], total_changes, pipeworx:// URIs). This is rich, non-obvious behavioral context that annotations alone do not provide.

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

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

The description is dense and information-packed, but it remains well-organized, front-loaded with examples, and appropriately sized for the tool's complexity. It could be slightly trimmed, but no sentence is wasted.

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

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

Despite lacking an output schema, the description specifies the return structure, the types of changes grouped by source, and the citation URIs. It also covers failure modes and source behavior, making the tool fully self-explanatory for an AI agent.

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

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

With 100% schema coverage, the description still adds value by giving examples for `since` (ISO and relative formats) and `value` (ticker vs CIK), and by noting only "company" is supported. It clarifies recommended settings, which the schema does not.

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

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

The description opens with concrete user paraphrases ("What's new with X") and then defines the tool as a change feed for a company in a time window, fanning out to SEC, GDELT/GNews, and USPTO. It explicitly distinguishes itself from the sibling entity_profile tool, making the purpose unmistakable and non-overlapping.

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 clearly states when to use the tool (recent-change queries) and explicitly recommends entity_profile for static-profile needs. It also includes practical guidance such as using "30d" or "1m" for typical monitoring and describes fallback behavior between sources.

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?

Annotated with idempotentHint and false destructiveHint, the description adds context about key-value scoping by identifier and session persistence (authenticated vs anonymous 24-hour retention). This goes beyond annotations by specifying data lifecycle, though no details on overwrite behavior or error cases are given.

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

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

Three sentences, each earning its place: purpose, when-to-use with examples, and storage/retention details plus companion tool references. No fluff or redundancy. Front-loaded with the primary action.

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 two-parameter tool with no output schema, the description covers all essential operating conditions: persistence behavior, session scoping, and companion tools. It is complete enough for an agent to use correctly without additional documentation, despite minor gaps like key overwrite semantics.

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

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

Schema coverage is 100% with both parameters (key, value) well-described including examples. The description adds no new parameter semantics beyond what the schema provides, so baseline 3 is appropriate. The tool description repeats the key-value concept but doesn't enrich it.

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

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

The description clearly states a specific action ('Save data the agent will need to reuse later') with a defined resource (memory key-value store). It distinguishes itself from sibling tools like recall and forget by explaining its role in storing for later retrieval. The purpose is unambiguous and well-scoped.

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

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

Provides explicit use cases ('Use when you discover something worth carrying forward') with concrete examples (ticker, address, preference). It also mentions pairing with recall/forget to complete the workflow. Lacks an explicit 'when not to use' statement or direct alternatives, but the guidance is strong enough to be clear.

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

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

Annotations already declare read-only, idempotent, and open-world behavior, but the description adds no additional behavioral context such as whether snapshots are historical or current. The word 'snapshots' is minimal and does not go 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 extremely short, but this is under-specification rather than conciseness. It omits essential information about the tool's behavior and parameters, so the brevity does not serve the agent.

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

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

For a simple one-parameter tool, an output schema exists to explain return values, but the description fails to clarify the meaning of station_id or whether the snapshot is point-in-time or time-series. This leaves the agent uncertain about valid invocations.

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 single parameter station_id has zero schema description coverage, and the description does not mention it. Examples in the schema (e.g., 'SHA', 'ORO') hint at station codes, but no explicit meaning or usage is provided.

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 identifies the resource (reservoir storage) but lacks an explicit verb, reading as a noun phrase. It does not differentiate from sibling data tools like daily_data or event_data.

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

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

No guidance is provided on when to use this tool versus alternatives, nor any indication of how station_id should be used. The description offers no contextual cues for invocation.

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

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

Annotations already cover safety (readOnly, idempotent, etc.), and the description adds meaningful operational details: cascading through multiple lookup endpoints internally, auto-disambiguation for company names, and returning citation URIs. This goes beyond what annotations alone provide.

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

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

The description is well-structured: opening with illustrative queries, then stating the purpose, providing usage guidance, and detailing supported types. All sentences contribute useful information, though it is slightly lengthy. The purpose is front-loaded, making it easy to scan.

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

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

With no output schema, the description carries the burden of explaining return values, and it does so thoroughly: it lists specific outputs for each type (ticker, CIK, company_name, RxCUI, ingredient, brand, citation URIs). It also covers supported input variations and internal behavior, making it complete for an agent to use effectively.

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

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

Schema coverage is 100%, so the baseline is 3. The description enriches parameters by providing concrete input examples (e.g., 'AAPL', '0000320193', 'ozempic') and clarifies accepted forms per type, including auto-disambiguation for company names. This adds value beyond the schema.

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

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

The description clearly states the purpose: resolving a user-spoken name to a canonical/official identifier required by other tools. It uses a specific verb ('resolve') and resource ('entity'), provides relatable examples, and distinguishes itself from sibling tools by focusing on the name-to-ID conversion use case.

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

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

The description gives explicit usage guidance: 'Use FIRST whenever you have a name but need an ID.' It also notes that the tool replaces 2-3 manual lookups, implying efficiency. It does not enumerate exclusions or alternatives, but the context is clear enough for an agent to decide when to invoke it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds useful behavioral context: it probes each entity with ai_visibility_check, ranks by score, surfaces most/least recognized, and returns a ranked list with score, confidence, and signal density. This goes beyond the annotations and explains the multi-probe, aggregation process.

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 well-structured sentences with no filler. It front-loads the main purpose, includes a concrete example, and mentions the output format. Every sentence earns its place.

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

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

Given the tool's complexity, the description covers purpose, process, use case, and output format. Since there is no output schema, it explicitly lists returned fields (score, confidence, signal density). It also references the underlying mechanism (ai_visibility_check), making it complete 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?

Schema coverage is 100% with all parameters described, so baseline is 3. The description reinforces the entities parameter (your brand + N competitors) and mentions optional shared context, but adds little new meaning beyond the schema. It does not compensate for gaps because there are none.

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 ('Compare'), resource ('AI visibility across multiple entities'), and differentiates from sibling ai_visibility_check by explicitly mentioning it probes each entity with that tool and ranks results. It is clear this is a multi-entity comparison tool for competitive audits.

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 a clear use case ('competitive AI-marketing audits') with a concrete example question, but it does not explicitly mention when not to use it or name alternative tools for single-entity checks or other comparisons. Clear context but no 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 mark the tool as read-only, idempotent, and non-destructive, but the description adds valuable behavioral context beyond that: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30 seconds, and failures are reported via sources_failed while the rest of the data still returns. This discloses latency and failure behavior not captured 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 dense single paragraph that front-loads the core purpose and use cases, then covers output fields, ecosystem limits, and failure behavior. Every sentence contributes useful information without redundancy or fluff, making it well-structured and appropriately sized.

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 takes on the burden of explaining return values and does so thoroughly: a summary block with specific fields, per-advisory detail, links, and alternative versions. It also covers timeout behavior and degraded partial results, making the tool's behavior fully understandable for an agent.

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

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

The schema already documents both parameters with 100% coverage, so the description adds limited value here. It does clarify that the package parameter is npm-specific and that version defaults to latest, but these are marginal additions over the schema. The baseline of 3 is appropriate for high schema coverage.

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

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

The description clearly states the tool as a composite "should I add this npm package" check that fans out across deps.dev and bundlephobia, giving a specific verb, resource, and scope. It distinguishes itself from siblings by explicitly limiting v1 to the NPM ecosystem and pointing to deps.dev:version for other ecosystems.

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

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

The description gives explicit use cases: 'whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides an alternative for non-NPM packages, stating that PyPI/Maven/Cargo/Go fall under deps.dev:version directly, which helps an agent decide when not to use this tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds concrete behavioral details beyond this: BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, a 200K-char cap with truncation flagging, and the return of character offsets and similarity scores.

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 succinct despite its length; every sentence carries functional information, from the core mechanism to the integration with ask_pipeworx_grounded. It is front-loaded with the primary purpose and usage context, followed by technical specifics.

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 is present, so the description takes on the burden of explaining return values (passages with offsets and similarity scores), truncation behavior, and the 200K-char limit. The pairing with ask_pipeworx_grounded also provides a complete usage workflow.

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

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

The schema already covers all three parameters with 100% coverage, so the baseline is 3. The description enriches the 'text' parameter with usage examples (SEC 10-K body, article) and clarifies the return includes offsets/similarity, but it doesn't add semantic details for the 'limit' parameter 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 this tool performs semantic search within a previously fetched text, returning top-N passages with offsets and similarity scores. It explicitly distinguishes itself from siblings like ask_pipeworx_grounded by framing it as a complementary pre-processing step.

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

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

It explicitly tells the agent when to use it: when the record is too big to fit in the prompt, to save context. It also names a sibling tool (ask_pipeworx_grounded) and explains the pairing, though it doesn't state explicit exclusions.

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

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

The description adds no behavioral context beyond what the annotations already declare (readOnlyHint, idempotentHint, etc.). It does not mention return format, pagination, or any special behavior. The annotations cover safety, but the description contributes nothing.

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

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

The description is only two words, but this is under-specification rather than effective conciseness. It lacks a full sentence and any useful structure, providing no meaningful information to the agent.

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?

Although the output schema exists and the tool is simple, the description is too minimal to be complete. It does not explain the tool's role, what 'station' refers to, or how the returned metadata could be used. The description fails to provide sufficient context for reliable tool selection.

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 0% schema description coverage, the description carries the full burden for parameter semantics, yet it says nothing about the 'station_id' parameter. There is no explanation of what IDs are valid, how to obtain them, or what the parameter represents.

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 'Station metadata' is essentially a restatement of the tool name/title 'Station Info' with no action verb. It does not specify what operation is performed (e.g., retrieve, list, get) and does not distinguish this tool from any 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?

There is no guidance on when to use this tool or when to consider alternatives. The description provides no context, prerequisites, or exclusions, leaving the agent to guess the intended use case.

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 meaningful behavioral context beyond annotations: the OAuth account requirement, the always-on feed, and SMS verification with a 10/day cap. Annotations already cover safety/idempotency, so the description’s extra details on auth, delivery, and return value are valuable. It omits webhook, but the schema covers that.

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 front-loaded: purpose, return value, requirements, then types and delivery. It is efficient with no fluff, but the enumerated types and channels run together, making it slightly harder to scan.

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

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

With a rich schema covering all parameters and webhook details, the description is mostly complete for selecting and invoking the tool. It omits two subscription types (patent_grant, clinical_trial) and webhook, but those are fully documented in the schema, so the overall context 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 has 100% parameter coverage with detailed examples for all types and delivery options. The description repeats some examples but adds no new meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the new subscription ID. This specific verb+resource action distinguishes it from sibling tools like list_subscriptions, recent_alerts, and unsubscribe.

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

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

The description provides clear context for when to use subscribe: to set up ongoing monitoring of event streams. It also notes the prerequisite OAuth account requirement and outlines supported types and delivery channels, 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, so the description does not need to restate safety. It adds useful behavioral context: returns live-catalog-derived example questions with exact tool and argument shapes, and describes the parameter behavior (omit for full spread, pass topic to focus). 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 longer than the average but every sentence adds value. It front-loads common queries, states purpose, then gives return details and usage guidance. No filler.

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

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

For a zero-required-param tool with no output schema, the description fully covers what to expect: the returned structure (category buckets), content (example questions with tool+argument shape), and the optional topic parameter's effect. It also provides usage context relative to other tools.

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 fully covers the `topic` parameter with a description. The tool description adds concrete examples ('finance', 'pharma', 'betting') and clarifies the output scope for omitted vs. provided topic, going beyond the schema's enum-like list.

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

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

The description clearly identifies the tool as an onboarding entry point that returns category-bucketed example questions, with a specific verb ('suggest') and resource (what to ask Pipeworx). It differentiates from sibling meta-tools by positioning itself as the first step, which also distinguishes it from other query tools.

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

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

Provides explicit guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains the alternative of passing a topic to focus. It implies when to use vs. meta-tools by naming them (ask_pipeworx, entity_profile) as things you learn about here.

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

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

Beyond the annotations, the description discloses important behavioral traits: ownership enforcement and soft-delete behavior with historical events retained via recent_alerts. These add significant context that annotations alone would not provide.

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

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

The description is three sentences, each carrying meaningful information, and the primary action is front-loaded ('Cancel a subscription by id'). 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 single-parameter mutation tool with no output schema, the description covers all essential aspects: action, ownership constraint, side effect (deactivation) and data retention. It is fully context-rich 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 description coverage is 100%, so the baseline is 3. The description does not add parameter-specific details beyond 'by id', but the schema already fully documents that id is a uuid returned by subscribe. No additional semantics are needed.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Cancel a subscription by id.' It also adds scope (ownership enforced) and distinguishes itself from related tools like subscribe and recent_alerts by clarifying its unique behavior of soft-deactivation.

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

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

The description provides clear context for when to use the tool, such as ownership enforcement ('you can only cancel your own subscriptions') and the non-destructive nature ('deactivated not deleted'). However, it does not explicitly name alternatives or exclusions, so it falls short of a 5.

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

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

The description goes well beyond the annotations by detailing the two pipeline paths (SEC EDGAR/XBRL fast path vs. grounded pipeline), the return structure (verdict types, actual value, citation, reasoning), and the automatic fallthrough behavior. This gives the agent a clear mental model of how the tool behaves, complementing the readOnly/openWorld/idempotent hints 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 long but front-loaded with a clear purpose and paraphrases. Every section adds useful context: routing, return values, and efficiency benefit. It could be slightly more concise, but the structure is logical and easy to scan.

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

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

Given the tool's complexity and absence of an output schema, the description thoroughly covers what the tool does, what inputs matter, how different claim types are handled, and exactly what is returned (verdict, value, citation, reasoning). It leaves little ambiguity for an AI agent deciding to invoke it.

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

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

The input schema already has 100% coverage with detailed descriptions for both parameters (claim with examples, tolerance_pct with semantics and range). The description does not add parameter-specific meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description explicitly states the tool's purpose: 'natural-language claim verification against authoritative sources.' It provides clear paraphrases ('fact check', 'verify the claim that…') and distinguishes itself from general Q&A or research tools by focusing on returning a verdict with evidence. The mention of replacing 4–6 sequential calls uniquely identifies this as a composite fact-checking 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 gives a clear trigger: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains routing for company-financial vs. other claims, which implies when it applies. However, it does not explicitly state when not to use it or mention alternative sibling tools, so it falls short of a 5.

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