Ban Fr

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

Annotations already declare readOnly/openWorld/idempotent, so the bar is lower. The description adds valuable context: the default model is free (Workers AI Llama-3.3-70b), and passing _apiKey incurs direct Anthropic charges, which is an important cost disclosure. It also states the return format (per-model score, confidence, signals, raw_response) without contradicting annotations.

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

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

Three sentences, front-loaded with the core purpose, followed by optional key behavior and return format. No filler or redundant restatement of the tool name; every sentence contributes essential information.

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

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

Despite no output schema, the description covers the return value structure (per-model score, confidence, signals, raw_response, combined view), default behavior, billing implications, and use cases. Combined with complete schema documentation and read-only annotations, an agent has all necessary context to call the tool correctly.

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

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

Schema description coverage is 100%, so baseline 3 applies. The description mostly reiterates what the schema already states (e.g., workers-ai is the free default, _apiKey enables Anthropic) without adding new parameter-level meaning beyond the property 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 probes one or more LLMs about a business/brand/product/topic and scores visibility 0-100 per model. It uses a specific verb ('probe') and resource ('LLMs'), and distinguishes itself from sibling tools like ask_pipeworx (Q&A) and scan_competitor_ai_presence (competitor-specific) by focusing on generic visibility scoring.

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 (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains when to use the default model vs. passing _apiKey for Anthropic. It does not explicitly name alternatIVes or list when not to use it, but the context is sufficient for an agent to decide.

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

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

With readOnlyHint=true and idempotentHint=true annotations already covering the safety profile, the description adds valuable context: routing behavior across 5,347 tools, argument auto-filling, stable citation URI format (pipeworx://), tier availability, and single-call latency. It doesn't overclaim beyond what annotations imply and adds meaningful behavioral context that annotations don't capture.

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 informative but quite long. It's front-loaded with the key preference cue, provides a clear examples list, and closes with escalation guidance. Every sentence earns its place, though verbosity is higher than strictly necessary — the domain list and examples could be trimmed slightly without losing value.

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

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

The tool has no output schema, so the description must explain what comes back — it does (structured answer with citations). The multi-tool routing complexity is well explained with domain coverage, escalation paths, and tier behavior. The single required parameter makes param handling simple, and the description fully compensates for the missing output schema.

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

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

Schema coverage is 100% with the 'question' parameter well documented and six aliases listed. The description adds context about the question format (natural language, accepts aliases, examples provided in schema). Baseline 3 is appropriate since the schema already covers all six parameters and the description doesn't need to add parameter-level detail.

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

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

The description uses specific verbs ('routes', 'returns', 'fills arguments') with clear scope — 5,347 tools across 1,393 sources — and explicitly lists the domains covered. It clearly distinguishes ask_pipeworx from siblings by naming ask_pipeworx_grounded and deep_research as alternatives. This is a strong, specific purpose statement.

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?

Exceptionally explicit usage guidance. It states 'PREFER OVER WEB SEARCH', provides trigger phrases ('what is', 'look up', 'find'), concrete examples, declares this the 'default entry point' for most questions, and gives explicit when-to-step-up conditions for ask_pipeworx_grounded and deep_research, plus a note for breaking news. Sibling differentiation is thorough.

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, destructiveHint=false, and the description doesn't contradict these. Beyond annotations, the description adds valuable context: that it's a full working router (not a disabled/partial implementation), that it 'falls back to nothing' as a working tool, and that behavior may change dynamically when a candidate is under test. It discloses the experimental nature and version-retirement detail (2026-07-26), which is genuinely useful behavioral transparency.

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

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

The description is well-structured, front-loads the core purpose, then explains the experimental distinction, current state, usage, and fallback behavior. Each sentence earns its place. Slightly on the longer side but every clause contributes essential operational context for an experimental tool. Minor deduction for the parenthetical date and tool-count details which are informative but slightly verbose.

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

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

For a universal routing tool with one core param (question) at 100% schema coverage, no output schema needed, and strong annotations, the description covers purpose, experimental status, current behavioral parity, usage instructions, and comparison against the stable sibling. It's complete for an agent deciding between ask_pipeworx and ask_pipeworx_beta. Not a 5 because it doesn't describe what the response looks like or what 'routing' entails functionally, but the output schema absence and openWorldHint reduce the burden.

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% — all 6 parameters are aliases for 'question' and are fully documented in the schema. The description adds the context that this is a natural-language universal router (the question param accepts a query), which supplements the schema. With high schema coverage and only one semantic parameter (question plus its aliases), the description doesn't need to add more; 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 this is the beta variant of ask_pipeworx, an identical universal router with the same tool count, arguments, and response shape. It explicitly distinguishes itself from the sibling ask_pipeworx by being the experimental edge with candidate routing improvements, and from ask_pipeworx_grounded as a different variant. The verb+resource ('universal router') is specific and the scope is precisely delimited.

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

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

The description explicitly states when to use it ('Use it exactly like ask_pipeworx when you want the newest routing') and how it differs from the stable router ('results are compared against the stable router to decide what merges'). It explicitly notes the current state ('No candidate is active right now') so the agent knows it functionally matches ask_pipeworx today. This far exceeds baseline 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, idempotentHint=true. The description adds substantial behavioral context beyond annotations: it describes the refusal mechanism with specific refusal_reason values, the evidence extraction requirement (verbatim quote), the return shape, and the one-extra-LLM-call cost. It doesn't detail rate limits or auth but provides strong behavioral disclosure.

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

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

The description is information-dense but front-loaded with the core purpose before diving into mechanics. It's longer than ideal but every sentence earns its place — covering return shape, error modes, use cases, and the cost tradeoff. The refusal code list is compact and useful.

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

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

For a single-parameter tool with strong annotations and complete schema coverage, this description fully addresses what the agent needs: purpose, differentiation from sibling, behavioral guarantees, return structure, refusal semantics, and the cost tradeoff. Nothing critical is missing.

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

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

Schema coverage is 100% and the description adds meaning by clarifying the natural-language query nature and listing accepted aliases. The parameter semantics are well-handled by the schema; the description's contribution is confirming query flexibility but adds little beyond what the alias descriptions convey.

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, distinct purpose: 'Hallucination-resistant answer mode for high-stakes reads' with a verb+resource combination. It clearly differentiates from the sibling ask_pipeworx by detailing the grounded extraction behavior and refusal mechanics.

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

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

Explicitly states when to use ('whenever an answer will be quoted, cited, or acted on'), gives concrete example domains (financial verdicts, legal claims, medical lookups, public statements), AND names the alternative (prefer ask_pipeworx for casual lookups, citing cost difference). This is exemplary usage guidance.

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

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

While annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, the description adds extensive behavioral detail: resolver contract fields, fan-out examples per classifier, safety short-circuits ('low_confidence_match', 'market_closed_or_inactive'), wide-spread market flags, cancellation rule parsing, and news fallback behavior. This goes well beyond the annotations and gives a complete picture of how the tool behaves in edge cases.

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

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

The description is long but well-structured, using clear section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY, etc.) and front-loading the core purpose in the first sentence. Each section covers a distinct aspect of behavior, so it earns its place. It could be trimmed slightly, but the organization keeps it navigable and information-dense.

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

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

Given the tool's complexity and lack of an output schema, the description is exceptionally complete. It details response shapes (market, analysis, evidence), resolver contract fields (market_match_confidence, market_match_score, alternatives, suggestions), parent-event extraction, news fallback fields, and multiple blocking/edge-case statuses (low_confidence_match, market_closed_or_inactive, illiquid_wide_spread). It also covers resolution-rule risk and safety measures, leaving no significant gap for an agent to misuse the tool.

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

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

The input schema already provides 100% coverage with detailed descriptions for all parameters (market, depth, include_raw). The description repeats the market input formats but adds no additional parameter-specific semantics beyond what the schema states. Thus, the baseline of 3 for high schema coverage applies; the description does not meaningfully compensate further.

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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the resource (Polymarket bet), the action (research/pull data), and differentiates from siblings by emphasizing a one-call evidence packet plus market-vs-model comparison. The explicit use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') further solidify its purpose.

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

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

The description provides clear usage context with explicit use-case phrases: 'Use for ...' and examples. It also describes input formats (slug, URL, question text). However, it does not explicitly mention when not to use this tool or name alternative sibling tools like polymarket_edges or polymarket_arbitrage, earning a 4 rather than a 5.

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

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

Annotations already indicate read-only, non-destructive behavior. The description adds valuable behavioral context: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs in results. This goes well beyond annotation basics, though it doesn't mention potential errors or rate limits.

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 each sentence earns its place—trigger phrases, explicit preference guidance, data source details, and result format. It could be broken into bullets for scannability, but it's appropriately sized for the tool's complexity and delivers high information density.

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 only 2 parameters and full schema coverage, the description is quite complete: it covers usage, data sources, sorting behavior, and return format (paired data + citation URIs). It lacks caveats about edge cases (e.g., invalid tickers) but for a read-only comparison tool with clear schema, it's sufficient.

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

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

Schema coverage is 100%, but the description enriches parameter meaning by explaining the semantics of each type ('company' pulls financials, 'drug' pulls adverse-event/trial counts) and providing concrete examples for values. This adds practical guidance beyond the schema's field descriptions.

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

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

The description clearly states the tool's function: side-by-side comparison of 2-5 companies or drugs in a single parallel call. It gives concrete trigger phrases and distinguishes it from sequential single-pack lookups, making it unambiguous and distinct from siblings like entity_profile.

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

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

Provides explicit when-to-use guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also explains the two entity types and what data each pulls, clarifying appropriate contexts for company vs drug comparisons.

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

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

Although annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, the description adds substantial behavioral context: returns verbatim evidence + confidence + source + fetched_at + pipeworx:// citation, explicit gaps[] for unanswerable facets, a hop field and citation_uri per finding, contradictions[] for standard/thorough, semantic excerpting of large records, cost/plan dependency (paid plan for thorough), and expected latency ranges (15-60s, up to ~90s). No contradiction with annotations.

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

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

The description is quite long (a dense paragraph) but front-loaded with the most critical information (ACCOUNT REQUIRED + when to use ask_pipeworx instead). Every sentence adds substantive operational detail about hops, gaps[], citations, excerpts, and latency. It's efficient relative to the information density, though slightly more verbose than the TDQS 4.3 benchmark example. Could be split into cleaner sections but earns its length.

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

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

For a complex tool with 2 params, no output schema, and full schema coverage, the description is remarkably complete: it covers auth/plan requirements, when to use alternatives, output shape (findings packet fields), behavior on unanswerable facets (never invents, gaps[]), iteration semantics per depth level, contradiction detection, excerpting strategy, and timing expectations. This is comprehensive for a research agent that needs to predict output shape and routing behavior.

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% — both parameters (question and depth) are documented in the schema. The description does add marginal value for the depth parameter by explaining the hop/recovery behavior for standard and thorough in plain language (gap recovery, contradiction scan, lead-chasing), which goes slightly beyond the schema. However, it largely restates what the schema already covers, so the baseline 3 for full schema coverage is appropriate.

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

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

The description states a very specific verb+resource scope: grounded multi-source research across Pipeworx's 1393 structured data sources in ONE call, explicitly distinguishing it from open-web search. It contrasts with ask_pipeworx (single lookup) and names coverage areas (SEC, FRED/BLS, FDA, USPTO, etc.), giving clear differentiation from siblings like compare_entities, bet_research, and ask_pipeworx_grounded.

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?

Exceptionally explicit when-to-use guidance: states ACCOUNT REQUIRED and when not signed in to use ask_pipeworx instead; gives clear examples of best-fit questions ('compare X and Y's regulatory + financial exposure'); explicitly says for BREAKING/current-news prefer ask_pipeworx because it routes to live news APIs while deep_research returns empty gaps[]; also clarifies depth progression (standard vs thorough).

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

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

Beyond the readOnlyHint/idempotentHint annotations, the description discloses the return payload: top-N tools with names, descriptions, and full input schemas, including curated examples, and that results are 'ready to call directly, no second schema lookup needed'. This gives a complete behavioral contract without contradicting annotations.

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

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

Three sentences, front-loaded with the core action, then usage guidance, then return format. No filler; every sentence contributes a distinct piece of 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?

With no output schema, the description takes on the responsibility of explaining return values, and does so thoroughly: top-N, fields (names, descriptions, full schemas with examples), and readiness for direct invocation. It also states when to call first, making the tool fully self-contained for an agent.

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

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

Input schema covers 100% of parameters, so the baseline is 3. The description adds value by explaining that the output is top-N (directly informing the `limit` parameter) and that results include full schemas, hinting at the rich output. The `query` parameter's flexibility is reinforced by the topic list, but no additional syntax details are provided beyond the schema's own aliases and examples.

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

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

The description opens with 'Find tools by describing the data or task', a specific verb+resource statement that clearly distinguishes this meta-tool from sibling tools like ask_pipeworx or deep_research. It enumerates supported domains (SEC filings, FDA drugs, etc.), making the tool's scope concrete.

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

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

Explicitly states 'Use when you need to browse, search, look up, or discover what tools exist' and instructs 'Call this FIRST when you have many tools available and want to see the option set', providing clear when-to-use guidance and implicitly contrasting with single-answer tools. Although no alternative tool names are given, the guidance is actionable and specific.

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

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

While annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, the description adds substantial behavioral context: it fans out across multiple sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), returns specific fields, notes a soft-fail for USPTO sunset, describes a GDELT→GNews fallback, and limits filings to 5. This goes well beyond what annotations provide, giving the agent a clear picture of operations.

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

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

The description is long but well-structured, front-loaded with user-facing examples and then a detailed breakdown of outputs. Every sentence earns its place by describing scope, alternates, limitations, or return values. It could be slightly tightened, but it remains highly informative without redundancy.

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

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

With no output schema, the description thoroughly enumerates the return structure (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI). It also covers fallback behavior, source sunset, and parameter constraints. This is complete enough for an agent to select and invoke the tool correctly without additional context.

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

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

Schema coverage is 100% with good descriptions for type and value. The description adds value by providing concrete examples ('AAPL' or zero-padded CIK '0000320193'), reinforcing the zero-padding requirement, and explicitly restating that names are unsupported. This is meaningful enhancement over schema alone, though not exhaustive since the schema already covers the basics.

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

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

The description clearly states it provides a 'full cross-source profile of a US public company in ONE parallel call' - a specific verb+resource combination. It distinguishes itself from siblings by explicitly saying it should be preferred over chaining single-pack SEC/XBRL/news lookups for holistic views, and differentiates from resolve_entity for name resolution.

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: 'ALWAYS PREFER over chaining... when the user asks for a holistic view.' It also clearly states a key exclusion: 'names not supported (use resolve_entity first if you only have a name).' This gives clear when-to-use and when-not-to-use guidance with an alternative.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds context about when to use deletion (stale context, done task, sensitive data) but does not disclose additional behavioral traits like irreversibility or error handling. Since annotations cover the safety profile, a 3 is appropriate.

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

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

Two sentences, front-loaded with the core action, and zero redundancy. Every sentence earns its place.

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

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

For a simple one-parameter delete tool with strong annotations and no output schema, the description covers purpose, usage, and parameter semantics sufficiently. Might mention permanence or error behavior, but destructiveHint covers that, so it's nearly complete.

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

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

Schema coverage is 100% with a clear parameter description ('Memory key to delete'). The description's 'by key' 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's function: 'Delete a previously stored memory by key.' It uses a specific verb (delete) and resource (memory), and differentiates from siblings like remember (store) and recall (retrieve).

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

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

Explicitly provides when-to-use guidance: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' Also mentions complementary tools 'Pair with remember and recall,' which clarifies its role among alternatives.

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

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

Annotations already indicate read-only, idempotent, and non-destructive. The description adds process details (fetches page, extracts title/description/key links) and output format (single text blob), which is useful context beyond the annotations.

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

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

The description is compact: three sentences covering what, how, and when. No fluff, each sentence earns its place, and key information is front-loaded.

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

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

The tool is simple (2 params, no output schema) and the description covers process, output format, and use cases. It lacks edge-case handling details (e.g., invalid URLs), but given the simplicity and rich annotations, 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 coverage is 100% with both parameters described. The description adds no extra parameter-level details 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 uses a specific verb (generate) and resource (llms.txt file for any URL), clearly explaining what the tool produces and its purpose. It distinguishes itself from siblings by focusing on generating the file itself, not just checking or scanning AI presence.

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 (client indexing, drafting own project, auditing competitor) that clarify when to use it. However, it does not mention when NOT to use it or name alternatives like ai_visibility_check, so no explicit exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds valuable context beyond these: it specifies the output format (scored GeoJSON with score 0-1 and specific fields) and the geographic restriction (France only). This enriches the behavioral model without contradicting the annotations.

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

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

The description is two sentences, front-loaded with the action verb and resource, and every clause adds value. It mentions the output format and scope in a compact manner with zero 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 read-only, non-destructive geocoding tool with a rich input schema, the description covers the main purpose, geographic scope, and output shape (scored GeoJSON, fields included). Since there is no output schema, describing the return format is essential and handled well. It could mention errors or rate limits, but those are less critical for this simple read operation.

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

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

The input schema has 100% parameter description coverage, with each parameter having a detailed description. The tool description adds no additional parameter-level semantics beyond what the schema provides. Baseline 3 is appropriate because the schema does the heavy lifting.

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: 'Forward-geocode a French address, street, locality or commune.' This uses a specific verb with a specific resource type and geospatial scope. It distinguishes itself from the sibling 'reverse_geocode' by explicitly using the term 'Forward-geocode' and adding 'France only'.

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

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

The description implies when to use the tool (for forward geocoding) and provides clear context (France only, returns scored GeoJSON matches). It does not explicitly mention alternatives or when-not-to-use, but the contrast with 'reverse_geocode' is strongly implied. The parameter descriptions also offer usage hints (e.g., bias with lat/lon), which adds guidance beyond the main description.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds value by stating the return fields, scoping to the caller's subscriptions, and the default of active only. This goes beyond the structured data and provides useful behavioral context without contradiction.

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

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

The description is concise, consisting of three short sentences that front-load the purpose, list return fields, and give usage guidance. There is no redundancy or unnecessary detail. Every sentence contributes value, 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 list tool with one optional parameter and rich annotations, the description provides sufficient context: it states what is returned, the scope (caller's active subscriptions), and appropriate use cases. The absence of an output schema is mitigated by listing return fields. It lacks only minor details like pagination, but these are not apparent necessities here.

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

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

Schema description coverage is 100% for the only parameter (include_inactive), and the schema already explains it. The description does not add extra meaning about the parameter, but it does indirectly clarify that 'active' is the default by saying 'active subscriptions.' Baseline 3 is appropriate since the schema handles the 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 lists the caller's active subscriptions, which is a specific verb-resource pair. It distinguishes itself from sibling tools like subscribe and unsubscribe by focusing on listing, and it specifies the return fields (id, type, params, etc.).

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

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

The description provides clear usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This implicitly references alternatives (subscribe/unsubscribe) but does not explicitly name them or state when not to use the tool. Strong but not maximally explicit.

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

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

Annotations provide no behavioral hints (all false), so the description carries the full burden. It discloses rate limiting ('Rate-limited to 5 per identifier per day'), free usage, no quota consumption, and that the team reads digests daily—useful context not present in the schema or 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 compact and front-loaded. Every sentence earns its place: the purpose, use-case triggers, content guidance, rate limit, and quota note. There is 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 3-parameter tool with a nested optional context object and no output schema, the description covers purpose, when to use, what to write, rate limits, and cost. Nothing essential is missing for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful guidance for the message parameter ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt') and reinforces the type enum with real-world triggers, going slightly beyond the schema.

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

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

The first sentence, 'Tell the Pipeworx team something is broken, missing, or needs to exist,' clearly states the verb and resource. It explicitly enumerates feedback categories (bug, feature, data_gap, praise), which distinguishes it from siblings like ask_pipeworx that answer queries.

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

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

The description gives explicit triggers: 'when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It stops short of naming alternative tools for 'when not to use,' but the categories plus 'don't paste the end-user's prompt' 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?

The description goes well beyond the provided annotations, revealing that the data is self-aggregating, derived from CF analytics-engine, contains no PII (just pack, tool, count), and is cached 5min-1h depending on window. These are concrete behavioral details not present in the annotations.

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

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

The description is front-loaded with the core purpose, and the use-case list provides value. It is slightly verbose with the three enumerated use cases, but each sentence earns its place. It could be tightened, but it's well-structured and readable.

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 single-param tool with no output schema, the description fully covers the return shape (top tools, top packs, total call volume, and the (pack, tool, count) tuple), the available windows, privacy, and caching. No essential context is missing.

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

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

The schema already fully describes the `window` parameter with enum values and an explanation of tradeoffs between short and long windows. The description adds a brief mention of the windows and cache timing but doesn't materially extend the schema's parameter semantics, so it stays at baseline 3.

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

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

The description opens with a clear question-and-answer format: 'What other AI agents are calling on Pipeworx right now.' It then lists the exact outputs (top tools, top packs, total call volume) and the time windows. This is a specific verb+resource+scope that clearly distinguishes it from siblings like discover_tools.

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

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

The description provides three explicit use cases, including discovering hot data sources, confirming canonical tool choice, and aligning with agent needs. It does not explicitly name alternative tools or state when not to use it, so it stops short of the full 5-level 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?

Even though annotations already declare readOnly/idempotent/non-destructive, the description adds rich behavioral context: the fill-check mechanism, the partition filter dropping placeholder slugs, the >3pp threshold for signals, and the warning that realizable_edge_pp <= 0 means do not trade. This goes far beyond the annotations and sets accurate expectations for output and edge cases.

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

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

The description is long but every sentence delivers unique value: modes, semantic anchor, partition filter, response fields, fill check, and pointer to sibling tool. It is front-loaded with the core purpose and structured with clear labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). No filler or redundancy.

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

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

Given the complexity (two modes, edge cases, output format, integration with other tools) and the lack of an output schema, the description covers every necessary aspect: response field names, threshold semantics, failure modes (null arb signal), and how to interpret fill-check results. It is self-contained and leaves nothing critical unexplained.

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 descriptions already cover both parameters 100%, but the tool description adds critical semantics: the difference between event (single-event mode, specific slug) and topic (cross-event mode, seed question), plus the 'top ~200 markets' behavior when both are omitted. This transforms the parameters from simple strings into meaningful mode selectors.

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

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

The description opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes three modes (no args, event, topic) and identifies the tool's unique niche among siblings by naming the fill-risk tool as a companion. This is far clearer than typical tool descriptions.

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

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

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

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

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

Annotations declare readOnly/idempotent/non-destructive, and the description adds extensive behavioral detail beyond that: caching behavior ('Cached 1h at the KV level'), model family specifics (e.g., lognormal barrier, GDELT ratio), Kelly capping at 0.25, placeholder-slug filtering, partition-level Kelly behavior, and a 24h-move warning. It also explains why Fed bets are unreliable. No contradictions with annotations.

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

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

The description is lengthy but highly structured with clear sections (model families, knobs, response top-level, caching). Every sentence conveys useful information, but the sheer density might overwhelm some agents. It is appropriately detailed for the tool's complexity, but not maximally concise; a more compact summary could improve scannability.

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

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

With no output schema and a complex response (three segments, diagnostics, nested fields), the description fully covers the return structure, including how to interpret empty segments, the role of diagnostics, and the Fed candidates note. It also explains the three opportunity types in detail, making the tool's behavior transparent even without structured output definitions. It is complete for an agent to invoke and interpret results.

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

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

The input schema already provides 100% coverage with detailed descriptions for all 9 parameters, so the baseline is 3. The description adds extra meaning by explaining how parameters interact, e.g., min_partition_leg_kelly applies to per-leg Kelly inside top_legs because parent-level kelly_fraction_half is always 0 for partition arbs, and min_kelly filters single-leg opportunities only. It also clarifies the semantics of slippage_pp and tradeable-edge filters. This goes beyond simple schema repetition.

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 pair: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It further specifies the intended use case ('what should I bet on today') and differentiates from siblings by focusing on Pipeworx disagreement rather than pure arbitrage or tracking. The tool's unique value proposition is 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 states when to use it: 'Built for what should I bet on today — agents discover opportunities without paging hundreds of markets.' It also provides guidance on knobs to adjust (min_liquidity/max_spread_pp) and a notable exclusion: Fed bets are excluded from ranking because the signal is unreliable. However, it does not explicitly name alternative sibling tools or say 'use this instead of X', so it falls just short of perfect.

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

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

The description extensively discloses behavioral traits beyond annotations: response structure (tracked[], expired[], snapshot_dates[]), limitations (60-day TTL, snapshot gaps due to cache-miss), and computation details (decay based on daily closes of edge_pp_net, not intraday). This adds significant value beyond the readOnlyHint and idempotentHint annotations.

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

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

The description is long but well-structured, front-loaded with the core purpose, followed by parameter details, response breakdown, and limitations. Each section uses clear formatting (e.g., uppercase field names) and provides necessary information. It could be slightly more concise, but 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?

Given the tool's complexity, no output schema, and minimal parameters, the description is thoroughly complete. It explains the return structure (tracked, expired, snapshot_dates), what each element means, and critical limitations (TTL, snapshot gaps, calculation basis). This fully equips an agent to understand what the tool will return and its constraints.

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

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

Schema coverage is 100% with descriptive parameter definitions. The description adds minimal extra meaning: it restates defaults (days default 14, window default '1wk') and adds max 30, but the schema already includes these details. Since the schema already does the heavy lifting, 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 tool's function: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and answers a specific question: 'how long has this edge existed and is it shrinking?'. It distinguishes itself from siblings like polymarket_edges by focusing on historical tracking rather than current edge values.

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: to evaluate edge persistence and decay before trading, with the example contrasting fresh vs. old edges. It does not explicitly exclude alternatives, but the purpose is well-scoped. No explicit alternatives are mentioned, but the use-case is evident from the description.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description goes well beyond by detailing how it walks the order-book ladder, what metrics it returns (top_of_book, vwap_fill_price, slippage_pp, etc.), and warns about 'partial basket fills convert an arb into an unhedged directional position' — a key behavioral risk not evident from annotations alone.

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

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

Despite its length, the description is tightly organized with clear sections (SINGLE-MARKET vs BASKET), leading with a crisp purpose statement. Every sentence earns its place, providing necessary detail for a complex two-mode tool without fluff.

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

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

With no output schema, the description must explain return values, and it does so thoroughly for both modes, including page-level details like thin_legs[], max_clean_notional_usd, and forced_directional_risk. It also covers usage context, risk warnings, and alternative tools, making it complete for an AI 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% and already describes each parameter well. The description adds value by clarifying the one-of relationship between market and event, explaining the auto default for side in basket mode, and how size_usd is interpreted differently per mode (max spend/target proceeds vs settlement notional). However, much of this repeats schema details, so it doesn't fully exceed the baseline.

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

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

The description opens with a specific verb+resource ('Realizable-vs-theoretical edge check against live CLOB order-book depth') and clearly distinguishes single-market vs basket modes. It also explicitly contrasts with siblings by naming polymarket_arbitrage and polymarket_edges, making the tool's unique role unmistakable.

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

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

Explicit usage guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains when not to rely on theoretical overround, mentioning the risk of partial fills, which effectively sets boundaries for when this tool is appropriate.

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

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

The description goes far beyond annotations by explaining compatibility_warning conditions, temporal_alignment semantics, and skipped_cross_type counters. This adds substantial behavioral context that annotations alone do not provide, and it does not contradict the readOnly/idempotent hints.

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

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

The description is long but well-structured with clear labels (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loads the core purpose. Some sentences could be tightened, but the thoroughness is justified for a complex tool.

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

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

With no output schema, the description correctly explains return values, including spread structure and safety fields. It covers the complexity well, though it omits error-handling examples and a full sample response, leaving some edge cases unaddressed.

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

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

Schema coverage is 100% for all three parameters, but the description adds meaning by explaining the mode-based interaction (topic auto-fetch vs explicit overrides) and the purpose of the safety fields. This goes beyond the schema's property descriptions.

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

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

The description opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' which is a specific verb+resource pairing. However, it does not explicitly differentiate from sibling tools like polymarket_arbitrage or compare_entities, so it stops short of full 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?

The description clearly explains two usage modes (topic shortcuts vs explicit ticker/slug) and warns that pre-mapped topics often return compatibility warnings. It does not reference alternative tools, but it provides strong contextual guidance for when to use this tool and what to expect.

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, so safety is covered. The description adds scoping context ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the dual-mode behavior of retrieving versus listing. It does not mention error handling or return format, but these are minor gaps beyond the annotation baseline.

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. The primary action is front-loaded, followed by usage context, scoping, and pairing with siblings. Every sentence adds value without redundancy.

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

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

The description covers purpose, usage, scoping, and relationships with related tools. Since there is no output schema, it could have explicitly stated what is returned (e.g., the saved value or list of keys), though the phrase 'list all saved keys' implies this. Missing error behavior (e.g., if key is not found) is a minor gap for an otherwise simple tool.

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

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

The schema already provides 100% coverage for the single 'key' parameter, including the note to omit it to list all keys. The description adds examples of key values (ticker, address, notes), which provides some semantic color, but does not significantly increase understanding beyond the schema's own description.

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

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

The description clearly states the tool's function: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It uses specific verbs and resources, and explicitly distinguishes from sibling tools by mentioning remember and forget. The examples of use cases (target ticker, address, research notes) further clarify purpose.

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

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

The description provides explicit usage guidance: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also names alternatives and complements: 'Pair with remember to save, forget to delete.' This clearly indicates when to use this tool versus memory-related siblings.

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

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

The description adds rich behavioral detail beyond annotations: the payload structure (source, citation_uri, raw payload), the side-effect of mark_read (flags events read so next call shows newer ones), and the persisted feed nature. This is valuable context even though readOnlyHint and idempotentHint already set 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 four sentences that front-load the purpose and then efficiently cover payload, filtering, and the alternative endpoint. 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 read-oriented tool with no output schema, the description covers return payload, filtering, and side effects. It could mention the unread_only parameter or default limit, but the schema already provides those. The external endpoint and polling note add completeness.

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

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

The schema covers all 5 parameters with 100% description coverage, so baseline is 3. The description adds meaning by giving a concrete type example ('sec_8k') and explaining mark_read behavior semantically. However, it omits unread_only and limit details, which the schema already documents, so not a full 5.

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

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

The description clearly states the tool pulls fired events from the subscription feed and returns the most recent alerts, distinguishing it from sibling tools like list_subscriptions or recent_changes. The verb 'pull' and resource 'fired events' are specific.

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

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

The description provides clear usage context: filtering by type and since, setting mark_read, and notes that polling works well. It also mentions an alternative HTTP endpoint for scripts/dashboards, but does not explicitly contrast with sibling tools or state when not to use it.

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

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

Goes well beyond annotations by disclosing data source fan-out, rate-limit fallback (GNews when GDELT rate-limited or 5xx), USPTO soft-fail due to API sunset, and return structure (changes[] grouped by source + total_changes + pipeworx:// citation URIs). No contradiction with readOnly/idempotent hints.

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

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

Dense but efficient: front-loaded with the core purpose, then specifics. The list of example queries is slightly redundant but helps intent matching. Every sentence adds value (sources, fallback, since format, output, alternative).

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

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

Even without an output schema, the description explains return values and sources. It mentions grouped changes and citation URIs, but does not detail the fields of each change, which would be useful for a complex tool. Still, it gives enough to set expectations.

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

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

Schema already describes all 3 parameters at 100% coverage (type, since, value). Description adds a minor recommendation ('Use "30d" or "1m" for typical monitoring') and examples, but this is additional guidance, not essential semantics. Baseline for high coverage is 3.

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

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

The description states a clear purpose: 'change feed for a company in the last N days/weeks/months in ONE parallel call' with specific sources (SEC, GDELT/GNews, USPTO). It distinguishes itself from entity_profile by explicitly naming the alternative for static profiles.

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

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

Provides explicit when-to-use examples ('What's new with X', 'latest on Y') and an explicit exclusion: 'Use entity_profile instead when you want the static profile...'. Also details fallback behavior (GDELT→GNews) to inform expected performance.

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 include idempotentHint=true and destructiveHint=false. The description adds context beyond annotations: key-value scoping by identifier, authentication-based persistence (24-hour retention for anonymous), and pairing with recall/forget. No contradiction.

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

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

Three sentences packed with purpose, usage, storage semantics, and sibling pairing. Slightly longer than minimal but every clause adds value; front-loaded with the core 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 simple 2-param tool with no output schema, the description covers purpose, usage, persistence, scoping, and pairing with related tools. Complete for an agent to decide when and how to invoke.

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

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

Schema covers both params fully with examples, but description reinforces that value accepts any text, clarifying flexibility beyond the schema. Adds meaning to the key-value concept and storage model.

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?

Specific verb 'save' + resource 'key-value pair' clearly states the tool's function. It distinguishes from siblings by explicitly mentioning recall and forget, and by describing persistent memory vs. retrieval.

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

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

Explicitly states when to use: 'when you discover something worth carrying forward' with concrete examples. Also notes persistence differences by authentication status, giving clear context for when to rely on it.

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

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

Beyond the annotations (readOnly, non-destructive, etc.), the description reveals internal behavior: cascades through multiple lookup endpoints, auto-disambiguates inputs, and returns citation URIs. It also clearly states what each call returns for company and drug types, adding significant transparency not available from 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 minimal but well-structured with quoted examples, SUPPORTED TYPES, and a value proposition. Every sentence serves a purpose, though some redundancy exists (e.g., 'replaces 2-3 manual lookups' could be implied). Still, it remains readable and scannable.

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

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

For a two-type resolver with no output schema, the description covers inputs, outputs, and disambiguation behavior effectively. It lacks details on error handling or edge cases, but the provided information is sufficient for typical use, especially given the rich schema and annotations.

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

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

Schema coverage is 100% (both parameters have descriptions), so the baseline is 3. The description adds value by explaining that the 'value' parameter accepts multiple formats (ticker, CIK, or name for company) and mentions auto-disambiguation, which goes beyond the schema. This nuance justifies a score above baseline.

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

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

The description states exactly what the tool does: resolves user-spoken names to canonical/official identifiers. It includes concrete examples ('ticker', 'CIK', 'RxCUI') and explicitly distinguishes from other tools with 'Use FIRST whenever you have a name but need an ID.' The supported types and their outputs are clearly specified.

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

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

Provides clear when-to-use guidance ('Use FIRST whenever you have a name but need an ID') and explains the tool replaces 2-3 manual lookups. However, it does not explicitly mention when not to use it or name alternative sibling tools, 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?

Annotations already provide safety hints (readOnly, idempotent, non-destructive). The description adds meaningful context beyond that: it specifies the return format (scored GeoJSON matches) and the exact fields returned (label, postcode, citycode, context, distance in metres), as well as the France-only limitation. No contradictions with annotations.

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

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

The description is two sentences, front-loaded with the primary action and scope, followed by a compact summary of the return fields. Every sentence earns its place with no redundancy or fluff.

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

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

The tool is relatively simple (3 params, no output schema). The description adequately covers the purpose, return format, and geographic constraint. It could mention that multiple matches may be returned or how they are ordered, but the main context is sufficiently covered.

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

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

The schema descriptions cover 100% of parameters, including units (WGS84) and the 'type' enum. The description adds no additional param-specific meaning beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb 'reverse-geocode' combined with the resource 'coordinate' and clearly states the geographic scope ('France only'). This distinctly differentiates it from the sibling tool 'geocode' (forward geocoding) and other location tools.

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

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

The description clearly establishes the tool's context (reverse geocoding for French addresses) and geographic constraint ('France only'), but it does not explicitly name alternatives or state when not to use it. The verb itself implies the use case, so this is still 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 provide read-only, idempotent, non-destructive hints. The description adds behavioral value by revealing the probing process (calls ai_visibility_check), ranking by score, and output structure (ranked list with score, confidence, signal density). No contradiction with annotations.

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

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

Two sentences, front-loaded with the core purpose, followed by an example and return details. No filler words; 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?

Without an output schema, the description appropriately describes the return format (ranked list with score, confidence, signal density). It covers the multi-entity comparison, ranking, and use case. It could mention behavior on probe failure or score interpretation, but is complete for a read-only tool with clear annotations and schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's mention of 'your brand + N competitors' merely restates the schema's 'first entry treated as subject.' It adds no additional meaning beyond the schema for 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 clearly states the tool's function: 'Compare AI visibility across multiple entities side-by-side.' It specifies the action (compare), resource (AI visibility), and scope (multiple entities). It distinguishes from siblings like ai_visibility_check by explicitly focusing on multi-entity comparison and ranking.

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

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

Provides clear context for when to use this tool: 'Useful for competitive AI-marketing audits' and cites an example question. It names ai_visibility_check as the underlying probe, implying single-entity checks. However, it does not explicitly state 'use this instead of X for single entities' or mention exclusions, but the contextual guidance is strong.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, destructiveHint=false. Description adds valuable behavior beyond annotations: composite fan-out, graceful partial failures, bundlephobia timing (5-30s), and sources_failed handling. No contradiction with annotations.

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

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

Five dense sentences, front-loaded with the composite purpose, then use-case, return fields, ecosystem scope, and failure behavior. Each sentence adds necessary information; only minor redundancy (e.g., mentioning bundlephobia twice) prevents a 5.

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 enumerates all return elements (summary block fields, per-advisory detail, links, alternative versions), covers sources, ecosystem extension, timing, and error degradation. This fully compensates for missing structured return 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 100%, with package and version fully described including scoped package example and default for omitted version. The description adds no parameter syntax or semantics beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description uses a specific verb+resource: 'Composite "should I add this npm package to my project" check in ONE call' and enumerates concrete sources (deps.dev, bundlephobia) and scope (npm package). It clearly distinguishes itself from sibling research tools by focusing on package evaluation.

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

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

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

Annotations already declare readOnly, idempotent, and non-destructive properties, so the safety profile is covered. The description adds value by specifying the resolved data fields (INSEE code, postcode, population, coordinates), which helps the agent understand the operational behavior without being too verbose.

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 exactly two sentences: the first clearly answers 'what does this do', and the second references the alternative. There is no redundant phrasing and it is front-loaded, making it highly concise and well-structured.

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

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

The tool is simple with only two parameters and strong annotations. The description explains the output fields but does not explicitly state that the tool returns multiple results or describe the response format. Considering the absence of an output schema, a note about the list nature would improve completeness, but it is otherwise adequate.

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

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

The input schema provides full descriptions for both parameters (q and limit), achieving 100% schema coverage. The description adds the phrase 'by name' which matches q, but doesn't offer any additional semantic nuance beyond the schema, 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 states a specific verb ('look up') and resource ('French commune'), and lists the exact output fields (INSEE citycode, postcode, population, centre coordinates). It clearly distinguishes itself from the sibling tool geocode by labeling itself as a shortcut, making the purpose unambiguous.

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

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

The description explicitly mentions it is a 'shortcut for geocode with type=municipality', giving clear context for when to use it instead of the more general geocode tool. However, it does not explicitly state when not to use it or compare with other lookup tools like reverse_geocode, so there is a minor gap.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description goes well beyond this by disclosing the exact embedding model (BGE-base-en), window size (500-char overlapping), the 200K character cap, and truncation behavior (longer inputs are truncated and flagged), which is valuable behavioral context for the agent.

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

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

The description is slightly long but every sentence carries substantive information: the core action, the use case, the pairing, and the technical details. It is front-loaded with the main purpose and then adds distinguishing context. No sentences are filler, but it could be tightened by moving the embedding detail to a separate note.

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, but the description clearly explains what the tool returns: top-N passages with character offsets and similarity scores. It also covers limitations (200K cap, truncation), the algorithm, and the input format. For a tool with 3 well-described parameters, this is fully complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add significant meaning beyond the schema, though it does reinforce the character limit on the text parameter and provides example queries. The schema already documents each parameter well, so the description adds marginal value.

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

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

The description clearly states the tool performs semantic search inside a fetched record, with a specific verb ('search') and resource ('inside a fetched record'). It also distinguishes itself from siblings by explicitly noting it pairs with ask_pipeworx_grounded, differentiating the workflow of searching within already-fetched text versus broader queries.

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

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

The description gives explicit when-to-use guidance: 'Use when the record is too big to cram into the prompt' and explains the benefit of saving context. It also mentions pairing with ask_pipeworx_grounded, indicating an alternative/supplementary workflow, but does not explicitly state when not to use the tool or list other sibling alternatives for exclusion.

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

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

Annotations already indicate a non-read-only, idempotent, non-destructive operation, so little is needed on basic side effects. The description adds meaningful context: requires a Pipeworx OAuth account, anonymous/BYO cannot persist, feed is always-on, and SMS has a 10/day cap. It does not discuss webhook behavior, but that is covered in the input schema's webhook field, so the description adds sufficient value without contradiction.

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

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

The description is moderately long but well-structured, leading with the purpose, then supported types, then delivery channels. Each section is information-dense and relevant. It could be tightened by dropping the phrase 'Supported types' when it only lists three of five, but overall it is efficiently organized 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?

Given the tool's complexity (3 params, nested object, multiple subscription types and delivery channels), the description covers the core behavior, return value, auth requirements, and primary delivery modes. It omits two subscription types (patent_grant, clinical_trial) and the webhook channel from the main text, but the input schema's param and delivery descriptions fill these gaps. No output schema exists, but 'Returns the new subscription id' is enough for basic use; webhook secret details are in the 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 the baseline is 3. The description adds value with concrete examples for sec_8k (items ['5.02'] = officer change), polymarket_edge (topic:'fed'), and fred_series (series_id:'UNRATE'), and reiterates SMS verification constraints. It does not fully cover patent_grant and clinical_trial in the main description, but the schema's params description covers those, keeping this dimension above baseline.

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

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

The description opens with a specific verb and resource: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly distinguishes itself from sibling tools like recent_alerts (pull) and unsubscribe (remove), and states the primary return value (subscription id). Though it omits two schema-listed types from its examples, the core purpose is unambiguous.

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

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

The description provides clear context on when to use the tool: creating persistent subscriptions for live-data events, with explicit account requirements (OAuth, anonymous/BYO cannot persist) and delivery options. It also hints at alternative consumption via recent_alerts or a JSON endpoint. It lacks explicit 'when not to use' or comparable sibling exclusions, but the context is clear enough.

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

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

Annotations already declare the tool read-only, idempotent, and non-destructive. The description adds valuable behavioral context: results are category-bucketed, drawn from a live catalog, and each example includes the exact tool and argument shape. It also explains the effect of omitting vs. passing a topic, going beyond the annotation hints.

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

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

The description is dense but every sentence earns its place: it covers user intents, return contents, both invocation modes, and workflow placement. The structure flows naturally from example queries to purpose to operational details, and the length is appropriate for an onboarding tool.

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

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

For a low-complexity tool with one optional parameter, no output schema, and strong annotations, the description is complete. It fully explains what the tool returns, how to call it, and when to use it during an initial agent interaction. Nothing essential is missing.

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

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

The sole optional `topic` parameter is already fully documented in the schema, including the allowed values and the note to omit for a cross-category spread. The description restates these examples but adds no new semantic detail beyond the schema, so the baseline 3 applies.

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

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

Description opens with the exact user intents and immediately identifies this as the onboarding entry point for a connected agent. It then specifies concrete return content—category-bucketed example questions paired with the exact tool and argument shape—which clearly distinguishes it from sibling tools like discover_tools or ask_pipeworx.

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

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

Provides explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains the no-argument vs. topic-focused invocation. However, it does not name explicit exclusions or direct users to alternatives like discover_tools for other discovery scenarios.

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 adds valuable behavioral context: ownership enforcement and that the row is deactivated rather than deleted, preserving historical events in recent_alerts. This fully explains the write operation's side effects and aligns with the destructiveHint and idempotentHint flags.

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

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

The description is two sentences, front-loaded with the primary action, and includes only necessary behavioral nuances. Every sentence earns its place, with no redundancy or fluff.

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

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

For a simple one-parameter mutation tool with full schema coverage and informative annotations, the description covers the action, a key constraint (ownership), and the non-destructive side effect. It also ties to recent_alerts for follow-up. This is complete enough for an agent to select and invoke correctly.

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

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

The input schema already documents the single parameter 'id' with a full description ('Subscription id (uuid) returned by subscribe'), providing 100% coverage. The description adds no additional parameter detail, so it meets the baseline of 3 without exceeding it.

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

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

The description clearly states the tool's action: 'Cancel a subscription by id.' This is a specific verb+resource pairing that distinguishes it from siblings like subscribe and list_subscriptions. The ownership enforcement note further clarifies scope.

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

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

The description gives clear context: use to cancel a subscription by id, ownership is enforced, and the effect is a deactivation rather than deletion. It doesn't explicitly mention alternatives, but the intended use is evident and no exclusions are needed.

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

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

With annotations (readOnly, openWorld, idempotent, non-destructive), the description adds substantial behavioral detail: the routing logic for financial vs other claims, the verdict categories, the inclusion of verifiable citations, and the fact that it replaces multiple sequential calls. It describes how results are produced and what the user gets, going well beyond the annotations.

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

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

The description is a single dense paragraph but is packed with necessary information: triggers, use case, routing, return values, and efficiency gains. Every sentence earns its place, though it could be slightly more structured with bullet points. It's concise for the complexity covered.

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

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

The description fully covers the tool's behavior: when to use, how different claim types are handled, the exact types of verdicts, and the return format (verdict, value with citation, reasoning). There is no output schema, but the description compensates completely by enumerating return values. For a 2-parameter tool, this is very complete.

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

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

Schema coverage is 100% and both parameters are well-documented in the schema. The description adds context about 'exact percent-delta math' and tolerance behavior, but the schema already explains tolerance_pct thoroughly. The additional value is marginal but present, so a 4 is appropriate.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It uses specific trigger phrases and describes the scope (company-financial vs any other factual claim). While it doesn't explicitly name sibling tools, it differentiates from general ask/search tools by its fact-checking focus.

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

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

The description provides explicit usage guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also delineates the two paths (SEC EDGAR for financial claims, grounded pipeline for others), giving clear context. It doesn't mention alternatives or when not to use, but the guidance is sufficient.

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