Here

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

Description adds critical behavioral context beyond annotations: it makes external API calls (Anthropic requires BYO key with cost), returns per-model structured data, and is idempotent/read-only. No contradiction with annotations; fully transparent.

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

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

Four sentences front-loaded with core purpose and key details. No redundant information, though return format could be more compact. Still efficient 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?

Given 4 parameters, rich annotations, and no output schema, description covers purpose, parameter usage, and return structure (per-model fields). Mentions raw_response but could detail combined view. Still adequate for agent to use correctly.

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

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

Schema coverage is 100% but description adds value: explains entity is the thing to ask about, models list with defaults, _apiKey only needed for Anthropic, context for disambiguation. Adds examples and clarifies optionality beyond schema descriptions.

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

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

Description clearly states the tool probes LLMs for knowledge about an entity and returns a visibility score (0-100). It differentiates from sibling tools like ask_pipeworx by focusing on multiple model probing and scoring rather than single knowledge base 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?

Explains default model (free Workers AI) and condition for Anthropic (requires API key). States use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. Lacks explicit when-not-to-use or alternatives, but context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: it routes across 5,798 tools, fills arguments automatically, and returns stable pipeworx:// citation URIs. It also sets performance/suitability expectations with 'one fast call' and 'works on every tier', which is useful for tool selection.

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

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

The description is longer than average, but it is front-loaded with the critical instruction ('PREFER OVER WEB SEARCH') and dense with discriminative information. Examples and explicit sibling comparisons earn their place. Slight redundancy exists between the inline domain list and the examples, but overall the structure supports quick scanning.

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

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

For a general-purpose routing tool with no output schema, the description covers the essential context: what types of questions to send, what happens under the hood (routing, argument filling), what the response includes (structured answer + citation URIs), and when to choose a sibling. The absence of error-handling details is acceptable given the tool's broad, open-world nature and the presence of a dedicated grounded alternative.

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%: every parameter is documented as an alias for the natural-language question, and the main 'question' parameter has a clear description. The tool description itself adds no new parameter-level semantics, but examples in the schema illustrate valid inputs. Baseline 3 is appropriate because the schema carries the parameter burden adequately.

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

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

The description states a specific role: route natural-language factual questions to the right underlying tool and return structured answers with citations. It names the broad domains (SEC, FDA, FRED/BLS, USPTO, ATTOM, weather, clinical trials, stocks, sports, etc.), which makes the tool's purpose concrete. It also explicitly differentiates itself from ask_pipeworx_grounded and deep_research.

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

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

The description is unusually explicit about when to use this tool: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and 'works on every tier'. It also names alternatives and the exact conditions for stepping up: ask_pipeworx_grounded for hallucination-resistant single answers, and deep_research for broad/multi-part questions. This gives an agent clear routing logic.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, covering the safety profile. The description adds genuinely non-obvious behavioral context on top: this is an experimental edge whose routing may change live when a candidate is under test, that no candidate is currently active (so behavior currently matches ask_pipeworx exactly), and crucially that it 'falls back to nothing' — it is a full working router, not a fragile wrapper. That last clarification prevents a likely misjudgment. Not a 5 because it doesn't discuss how a candidate test might alter response quality or whether results are flagged as experimental.

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

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

Four sentences, each earning its place: purpose/identity, current state with a specific retirement date, usage directive, and a misconception-preventing clarification. The critical scoping info ('identical universal router', 'currently matches ask_pipeworx exactly') is front-loaded. It is slightly wordy in the middle ('the last was retired on outcome evidence 2026-07-26' is more detail than strictly needed), which keeps it from 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?

For a beta twin of a stable tool, the description covers the unusual aspects well: experimental status, current parity with the stable router, usage conditions, and the reassurance that it is fully functional. Since there is no output schema, the description's pointer to 'same response shape' as ask_pipeworx is a reasonable delegation to the sibling rather than a gap. It is not a 5 because it assumes the agent will consult ask_pipeworx for response format details, and it never says what kinds of questions are appropriate for a universal router.

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 six parameters (question plus five aliases: q, text, input, query, prompt) are already fully documented in the schema, so the baseline is 3. The description adds no parameter-level meaning beyond noting 'same arguments' as ask_pipeworx, which confirms parity but doesn't enrich understanding of any individual parameter. It meets the baseline but doesn't exceed it.

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

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

The description identifies the tool as a beta twin of ask_pipeworx: an identical universal router with experimental routing improvements, and explicitly scopes it ('same 5,798 tools, same arguments, same response shape'). It distinguishes itself from the stable sibling ask_pipeworx by the beta/experimental framing. It stops short of 5 because the actual user-facing function ('answer my question by routing to the tool network') is only conveyed indirectly via 'universal router' and 'use it exactly like ask_pipeworx' — an agent unfamiliar with ask_pipeworx would need to open that sibling to fully understand the operation.

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 an explicit when-to-use directive: 'Use it exactly like ask_pipeworx when you want the newest routing,' and explains the evaluation context ('results are compared against the stable router to decide what merges'). It names the primary alternative (ask_pipeworx) and the condition that selects this variant. It doesn't provide exclusion criteria, such as when to prefer the stable router or ask_pipeworx_grounded, so it misses the 'when-not-to-use' part of a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description goes further by disclosing the exact success return shape, all refusal reason enum values, that evidence is a verbatim quote, and the extra LLM call cost. This meaningfully expands on the annotations without contradicting them.

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

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

Every sentence carries functional information: purpose, routing behavior, output contract, refusal behavior, use cases, and cost trade-off. The structure front-loads the core purpose and then supplies operational detail 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?

Despite having no output schema, the description fully specifies the success and failure return contracts, including the refusal_reason taxonomy. It also covers the relationship to ask_pipeworx and the conditions under which this grounded mode should be chosen, making the tool actionable.

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

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

Schema coverage is 100% and the schema already documents the single meaningful `question` parameter plus all five aliases. The description does not add parameter-specific semantics, but with full schema coverage, no further compensation is required.

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 purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly identifies the tool as an answer-extraction variant that uses the same routing as ask_pipeworx, then returns a grounded answer and evidence. This distinguishes it from sibling tools like ask_pipeworx and ask_pipeworx_beta.

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 whenever an answer will be quoted, cited, or acted on,' and states when not to use it: 'prefer ask_pipeworx for casual lookups.' It also names the direct alternative and the cost tradeoff, which fully covers usage selection.

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 covers behavioral traits beyond annotations: fan-out process, fan-out examples per category, response shapes, safety mechanisms (low-confidence short-circuit, closed markets), resolution rule risk, parent event extraction, and news fallback fields. Annotations provide basic hints, and the description enriches them significantly.

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 paragraphs and bolded key terms. Every sentence adds value; however, it is somewhat verbose and could be tightened. Still, it is appropriately detailed 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 no output schema, the description fully explains the return fields (result.market, result.analysis, result.evidence), edge cases (low confidence, closed markets, wide spreads), cancellation rules, and parent event extraction. It is complete and leaves no major gaps.

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

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

The description adds substantial meaning beyond the schema: explains that market accepts slug, URL, or question text; depth parameter options 'quick' vs 'thorough' with explanation; include_raw parameter with context on when to use true/false and size implications. All 3 parameters benefit from detailed elaboration.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data in one call, with a specific verb and resource. It distinguishes from siblings by its single-bet deep research focus versus other tools like polymarket_edges for edge scanning.

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 scenarios are provided ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'). While it doesn't explicitly list alternative tools, the context is clear. Slight deduction for lacking when-not-to-use guidance.

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

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

Description adds behavioral context beyond annotations: mentions data sources (SEC EDGAR/XBRL, FAERS), fiscal year handling, result sorting by primary metric, and citation URIs. No contradiction with annotations (readOnly, openWorld, idempotent).

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?

Single paragraph is dense but every sentence adds value. Front-loaded with trigger phrases. Slightly less structured than ideal (could benefit from bullet points), but still 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?

Despite no output schema, description explains return format (paired data + URI citations) and result ordering. Covers both entity types, fiscal year handling, and data sources. Complete for the tool's complexity.

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

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

Schema coverage is 100%, and description adds extra meaning: examples for 'values' (tickers/CIKs, drug names), constraints (2-5 items), and explains how type affects data pulled. Adds sorting and data source details beyond schema.

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

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

The description clearly states it performs side-by-side comparison of 2-5 companies or drugs, with specific trigger phrases like 'which is bigger' and 'head to head'. It distinguishes from siblings by noting it replaces 8-15 sequential lookups.

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

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

Explicit when-to-use examples provided. States 'ALWAYS PREFER over sequential single-pack lookups' and differentiates behavior for type='company' vs. type='drug'. Provides clear context for alternative tool usage.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) already cover the safety profile, and the description adds substantial context on top: account/paid-tier gating, 15-90s latency, parallel facet decomposition across 5,798 tools, gap-recovery hops per depth tier, contradictions[] scanning, semantic excerpting of large records, and the guarantee that gaps[] are explicit and findings are never invented. It also explains that citation_uri is present only when fetchable — a key reliability trait.

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 (~280 words) but justified by the tool's complexity, and the most critical gate (account required, fallback to ask_pipeworx) is front-loaded. Every sentence carries decision-relevant or invocation-relevant information with no filler; the slight deduction is for density — a wall of text with long sentences and parentheticals that could be broken up for faster parsing.

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

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

Despite having no output schema, the description fully specifies return values (findings packet with evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], hop field). For a tool this complex — three depth tiers, auth gating, latency, fallback routing, and explicit failure modes — nothing an agent needs to decide or call correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds real value beyond it. For depth, it maps the enum values to account gating ('thorough' needs a paid plan), hop behavior (standard adds gap recovery, thorough chases leads), and latency ranges. For question, it specifies which question types succeed (broad/multi-part comparisons) and which fail (breaking news → empty gaps[]), which the schema's terse 'broad/multi-part is fine' does not 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 names a precise verb and resource — 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources... in ONE call' — and distinguishes it from siblings by explicitly stating what it is NOT ('this is NOT open-web search'). It also clarifies scope ('best for broad/multi-part questions over structured data') and describes the output packet, so an agent can tell it apart from ask_pipeworx or compare_entities without opening the schema.

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

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

The description gives explicit when-to-use and when-not-to-use guidance with named alternatives: use ask_pipeworx for a single lookup, for breaking/colloquial current-news topics, or when not signed in. It also states the positive case — broad/multi-part questions over structured data — so routing decisions are fully specified.

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

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

Annotations already provide readOnlyHint=true and idempotentHint=true. The description adds valuable behavioral details: returns top-N most relevant tools with names, descriptions, full input schemas with curated examples, ready to call directly with no second lookup. No contradictions.

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

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

The description is moderately long but each sentence adds value: purpose, use cases, output details, and guidance. Could be slightly tightened, but remains clear 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 6 parameters, no output schema, and 32 sibling tools, the description is very complete. It explains what the tool returns (names, descriptions, full schemas with examples), that results are ready to call, and when to use it. No significant gaps.

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

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

Schema coverage is 100% with all parameters documented. The description adds context beyond the schema by explaining the query parameter accepts natural language and lists example tasks (e.g., 'analyze housing market trends'). It also clarifies the limit parameter default and max.

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

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

The description clearly states the tool finds tools by describing data/task, lists specific domains (SEC filings, financials, etc.), and explains it returns top-N relevant tools with full schemas. This distinguishes it from siblings like 'recall' or 'search_within' which have different purposes.

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

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

Explicitly says 'use when you need to browse, search, look up, or discover what tools exist for' and lists many domains. Also advises 'Call this FIRST when you have many tools available'. Does not explicitly mention when not to use, but the context is clear.

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

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

Annotations already carry the safety profile (readOnly, idempotent, non-destructive), so the description goes beyond them with rich operational detail: sources_used/sources_failed semantics ('an empty section is a real no data, not a bug'), fda_products expected-empty case, GDELT→GNews fallback, USPTO soft-fail until reactivation, and private-company resolved:false with a notes line. These edge-case disclosures materially reduce the chance an agent misreads results as failures.

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 front-loaded with purpose and preference, and most sentences earn their place. However, it is a long single block with garbled/truncated mid-sections (e.g., 'fundamentals (LATEST 10-K Revenues + NetIncomeLoss + Cash, sorted...' cuts off), and the type-interchangeability note is repeated nearly verbatim in the schema. It is justifiably long for the tool's complexity but poorly structured for 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, the description carries the full burden of explaining return values — and it does: it enumerates cik, company_name, resolved_from/resolved_to, recent_filings with pipeworx URIs, fundamentals fields, sources_used/sources_failed, LEI, hiring, and news sections. It covers fallbacks and expected-empty cases for each source. It loses a point because the visible text appears truncated in the middle (fundamentals detail) and omits practical concerns like latency or rate limits.

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 above the schema by providing concrete examples ('AAPL', '0000320193', 'Moderna'), the zero-padding requirement for CIKs, and the interpretive consequence of name inputs (resolved_from/resolved_to fields). This pushes it above baseline, though the type-interchangeability point partly duplicates the schema.

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

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

The description opens with concrete example queries and a crisp definition — 'full cross-source profile of a US public company in ONE parallel call' — giving a specific verb, resource, and scope. It clearly differentiates itself from siblings like resolve_entity and compare_entities by emphasizing the holistic multi-source fan-out nature of the call.

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?

'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' is an explicit when-to-use directive with a selection condition. It also states accepted input shapes and the private-company resolved:false behavior. It stops short of a 5 because it never names sibling tools (e.g., compare_entities) and states when NOT to use this tool.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. Description adds context about clearing sensitive data but does not introduce new behavioral traits beyond what annotations provide. 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?

Two sentences, no unnecessary words. Purpose is front-loaded, and each sentence adds value (what it does, when to use).

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?

Tool is simple (1 param, no output schema). Description covers purpose, usage, and param context adequately. No gaps given the tool's complexity.

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

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

Schema coverage is 100% and description adds minimal value beyond the schema's description of the 'key' parameter. 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?

Clearly states 'Delete a previously stored memory by key.' Verb (delete) and resource (memory) are specific. Distinguishes from sibling tools 'remember' and 'recall' by explicit pairing.

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

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

Explicitly says when to use: 'when context is stale, the task is done, or you want to clear sensitive data.' Also suggests pairing with related tools, providing clear context.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds that it fetches the page (network call), extracts title/description/key links, and emits standard markdown, providing behavioral 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?

Three sentences: purpose, process, use cases. No fluff, front-loaded with key action. Every sentence adds value.

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

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

Despite no output schema, description adequately describes output format ('standard llms.txt markdown format', 'single text blob ready to drop at site-root/llms.txt'). Covers purpose, process, output, and use cases entirely for a simple tool with good 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 url and max_links described). The description does not add extra meaning beyond schema; it implies url usage in the first sentence but doesn't elaborate further. Baseline 3 is appropriate as 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 'Generate a production-ready llms.txt file for any URL' with specific verb and resource. It explains the process and distinguishes from siblings by being specific to llms.txt generation, not general AI visibility.

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

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

The description lists three concrete use cases (client site indexing, own project drafting, competitor auditing). It provides clear context for when to use, but does not explicitly exclude alternatives or mention when not to use.

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

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

Annotations already declare read-only, idempotent. Description adds behavioral info (returns specific fields, supports place name or lat/lng) but no deeper detail on auth or 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?

Two concise sentences with examples, no fluff.

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

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

Despite no output schema, description lists return fields. Missing pagination details but adequate for a simple query tool.

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

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

Schema has 100% coverage. Description adds examples and clarifies format for `near`, surpassing 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?

Clearly states it finds places/POIs near a location, with examples and fields returned. Distinguishes from sibling geocoding/route tools.

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

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

Provides context on when to use (finding places) and examples, but does not explicitly exclude alternatives like geocoding or routing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by detailing return values (latitude/longitude, normalized address, match type, match score) and mentions 'high-accuracy geocoding', providing behavioral context beyond annotations.

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

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

The description is concise (two sentences), well-structured with the key instruction front-loaded ('PREFER OVER WEB SEARCH'). Every sentence adds value with no unnecessary words.

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

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

Without an output schema, the description fully explains what is returned (lat/lng, full address, match type, match score) including match type values. Parameters are well-covered in the schema. The description is complete for a simple geocoding tool given the rich 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%, so baseline is 3. The description adds examples and mentions the 'q' parameter via example queries but does not significantly enhance understanding beyond the schema's own descriptions for 'limit' and 'country'. It provides no additional semantics beyond what's in the schema.

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

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

The description clearly states the tool converts addresses/place names to coordinates ('turning an address or place name into precise coordinates'), using specific verbs and resources. It distinguishes from siblings like here_reverse_geocode by focusing on forward geocoding.

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

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

The description explicitly says 'PREFER OVER WEB SEARCH', giving clear when-to-use guidance versus a common alternative. It provides example queries. However, it does not explicitly mention when not to use or alternatives like here_reverse_geocode for the reverse operation.

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, destructiveHint, so the safety profile is clear. Description adds useful behavioral information: 'Returns the normalized address, place title, and distance to the matched location'. No contradictions or extra behavioral traits beyond what annotations provide.

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

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

Two sentences: first states purpose, second states return values. Front-loaded with key information, no wasted words. Extremely 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?

Given the tool's simplicity (2 simple params, no output schema), the description fully covers its operation. It explains inputs and outputs adequately, with no missing 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%, and parameters are well-described in the schema. The description mentions coordinates and provides examples, but does not add new meaning beyond the schema properties.

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

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

Description clearly states the tool's purpose: 'Turn coordinates into the nearest street address (reverse geocoding)'. It provides an example query format and distinguishes from siblings by naming 'reverse geocoding' (as opposed to forward geocoding in here_geocode).

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

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

Usage is evident from the purpose and example. It explains what the tool does and gives a concrete query example. However, no explicit when-not or alternative tool guidance is provided.

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

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

Annotations already indicate readOnly, idempotent, and no side effects. The description adds behavioral details: returns distance, travel times (with traffic, free-flow, delay), and turn count. 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 a single, well-structured paragraph. It front-loads the key differentiator ('TRAFFIC-AWARE'), includes examples, and is concise with no wasted words.

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

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

Given high-quality annotations and schema, the description is complete. It explains return values (distance, times, turn count) and input flexibility. While no output schema exists, the description compensates adequately.

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 has 100% coverage, so baseline is 3. The description enhances this with examples and clarifies that origin/destination can be place names or lat,lng, and transport_mode defaults. This adds value beyond the schema.

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

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

The description uses specific verbs ('routing and ETA') and clearly identifies the resource (HERE) and key differentiator (traffic-aware, real-time traffic ETAs). It distinguishes itself from sibling tools like here_geocode and here_reverse_geocode by focusing on routing with traffic.

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 (traffic-aware routing), includes examples, and mentions constraints (origin/destination can be place names or lat,lng). However, it does not explicitly state when not to use or name alternatives among siblings, though the differentiation from 'keyless routing' is implicit.

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 show readOnlyHint, idempotentHint, destructiveHint false. Description adds that it returns specific fields (id, type, params, etc.) and covers the 'active' scope and include_inactive behavior, enriching the safety profile.

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

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

Two efficient sentences: first defines purpose and output, second provides usage context. No wasted words.

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

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

For a simple read-only tool with 1 optional parameter and no output schema, the description fully covers purpose, output fields, and usage guidance without gaps.

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

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

Schema coverage is 100%. The only parameter (include_inactive) is fully described in the schema; description adds no extra semantic value beyond what the schema provides.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource. It distinguishes from siblings like 'subscribe' and 'unsubscribe'.

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

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

Provides explicit use cases: 'review what you're monitoring before adding more' and 'find an id to cancel'. Could be enhanced with explicit when-not-to-use, but current guidance is sufficient.

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

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

Discloses the claim_token flow for anonymous filing, the ability to later query resolution status, rate limiting (5/day), and the fact that it is free with no quota impact. All annotations are false, so no contradiction; description adds significant behavioral context.

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

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

Long but every sentence earns its place. Front-loaded with the core action, then use cases, exclusions, mechanics, and limits. Structured in a logical flow 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?

Even with no output schema, the description covers all necessary context: return behavior (claim_token), rate limits, message length expectations, and the feedback lifecycle. No gaps remain for an agent to use this tool correctly.

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

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

Schema covers 100% of parameters with descriptions, but the description adds functional meaning: it explains how claim_token works and how to pass it, and instructs users to frame issues in terms of Pipeworx tools/packs, which maps directly to the context object fields.

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

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

Description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes from sibling tools by scoping to this connection's tools, not generic querying or research tasks.

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 (bug, feature/data_gap, praise) and an explicit when-not-to-use exclusion for tools from other MCP servers, even naming the alternative action (file with that server). 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 already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds value by explaining the data source (CF analytics-engine), caching (5min-1h), and the self-aggregating, no-PII nature, going beyond what annotations provide.

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

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

The description is well-structured: it starts with the tool's output, then lists use cases, then technical details. Every sentence is informative and earns its place with no redundancy.

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

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

Given one optional parameter, no output schema, and comprehensive annotations, the description is complete. It explains the data source, caching, and usage context, leaving no gaps for agent invocation.

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

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

Schema coverage is 100% with the 'window' parameter already described. The description adds nuance about shorter vs. longer windows ('hot right now' vs. 'steady-state demand'), providing extra semantic value beyond the base schema.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume' over a window, specifying the resource and action. It distinguishes from siblings like 'discover_tools' by focusing on real-time trending data.

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

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

The description explicitly lists three use cases (discovering hot data sources, confirming canonical choice, seeing alignment) and notes window behavior. It lacks explicit when-not-to-use guidance but provides clear context for appropriate use.

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

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

Annotations indicate readOnly, openWorld, and idempotent. Description adds rich behavioral context: monotonicity checks, partition sum, semantic anchor, partition filter, fill check, and that the tool does not execute trades. 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?

Description is lengthy but well-organized with clear sections for each mode, backtick formatting, and concise explanations. Every sentence adds value, though could be slightly more condensed.

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

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

No output schema, but description thoroughly explains response structure (opportunities array, partition_check object, fill check details). Covers important edge cases (placeholder filter, low similarity skip, realizable edge) and directs to other tools for further steps.

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 both parameters. Description adds meaningful context beyond schema (e.g., event slug vs URL, topic as seed question, mode behavior), justifying a score above 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 clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between three modes (trending scan, event, topic) and contrasts with sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicit guidance on when to use each mode: no args for trending scan, event for specific market, topic for cross-event scanning. Also explains when not to trade (realizable_edge_pp ≤ 0) and directs to polymarket_fill_risk for custom sizing.

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. It details the three model families, response structure (by_segment), caching (1h at KV level), edge calculation (including slippage), and warnings like 'Market moved X.Xpp in 24h'. No contradictions with annotations (readOnlyHint, etc.).

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 very long and detailed, covering model families in depth. While well-structured with clear sections, it is not concise; the verbosity may reduce quick readability for AI agents. Front-loading the main use case helps, but overall length is a downside.

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 (9 parameters, no output schema), the description is thoroughly complete. It explains output structure (by_segment, fed_note, diagnostics), how segments are calculated, and how filters work. No major missing pieces for an agent to understand the tool's 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?

Despite 100% schema coverage, the description adds significant meaning to parameters. For example, it explains the role of 'min_liquidity' and 'max_spread_pp' as tradeable-edge filters, provides default behaviors, and gives practical advice like bumping slippage for thin partitions. This goes well beyond the schema's descriptions.

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

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

The description clearly states the tool's purpose: scanning Polymarket markets for opportunities where Pipeworx data disagrees with market prices. It explicitly says 'Built for "what should I bet on today"', distinguishing it from sibling tools like polymarket_arbitrage or polymarket_edge_tracker with a specific use case.

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

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

The description implies usage for discovering betting opportunities but does not explicitly state when to use this tool versus alternatives. It includes context like caching and exclusion of Fed bets from ranking, but lacks direct comparison to siblings. Some implicit guidance is present, but no explicit exclusions or preferences.

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 as true/false, covering safety. The description adds significant behavioral context beyond annotations, including limits (60-day TTL), response structure (tracked, expired, snapshot_dates), and that decay numbers are from daily closes, not intraday.

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 purpose, then details and limits. It is somewhat verbose but each sentence adds value. For a telemetry tool with a nested response, the length is justified.

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

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

Given no output schema, the description adequately covers the response structure (tracked, expired, snapshot_dates) and limitations. It lacks precise field definitions for the time-series data but provides enough context for an agent to understand the output's purpose.

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

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

Schema coverage is 100% with descriptions for both days and window. The description adds context: 'lookback', 'snapshot family', and clarifies defaults (14, '1wk') and constraints (max 30, valid families). This adds meaning beyond the schema's brief descriptions.

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

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

The description clearly states the tool's purpose: answering 'how long has this edge existed and is it shrinking?' with specific verb+resource (edge persistence and decay telemetry). It distinguishes from siblings like polymarket_edges by focusing on historical trends rather than current snapshots.

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: for analyzing edge persistence vs. freshness, by contrasting a fresh wide edge with a 3-week-old wide edge. However, it does not explicitly mention alternatives or when not to use this tool, though sibling differentiation is clear.

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

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

Annotations already indicate read-only, open-world, and idempotent behavior. The description adds crucial behavioral context: the risk of partial fills leading to unhedged directional positions, and details of what the tool returns (e.g., verdict, thin_legs, forced_directional_risk). No contradictions.

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

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

The description is somewhat long but highly informative; every sentence adds value. Front-loaded with core purpose then mode details. Minor length allows for comprehensive guidance.

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

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

Despite lacking an output schema, the description thoroughly enumerates return fields for both modes (e.g., top_of_book, vwap_fill_price, capture_ratio, thin_legs) and covers edge cases. Complete for a complex tool with two modes.

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 significantly enhances understanding: for 'side', it explains default logic; for 'size_usd', it clarifies interpretation for buys vs sells and basket meaning; for 'market' and 'event', it maps to modes. Adds substantial meaning beyond schema.

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

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

The description clearly defines the tool as a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes two distinct modes (single-market and basket), making its purpose unambiguous and differentiated from siblings.

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

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

Explicitly states when to use this tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Also warns against partial basket fills converting arb into unhedged positions, providing excellent usage boundaries.

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

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

Annotations already mark readOnly/openWorld/idempotent, and the description substantially extends this with practical behavioral disclosures: compatibility codes, pairing_unverified, non-equivalent bet shapes, temporal_alignment null semantics, skipped leg counters, and the gross-vs-net fee caveat. This gives the agent a far richer safety model than the 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?

The description is long, but appropriately so given there is no output schema: it front-loads the core purpose, then progresses through modes, response shape, safety fields, codes, skipped counters, and fees. The structure with labels like 'TWO MODES', 'RESPONSE', and 'SAFETY FIELDS' keeps the density navigable. It slightly exceeds a minimal length, but every section is load-bearing for safe invocation.

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

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

With no output schema, the description compensates by covering the response surface: leg prices, top_spreads_pp, compatibility codes, per-entry flags, skipped/uncertain categories, temporal_alignment behavior, fee disclosures, and counters. An agent could call this tool in either mode and correctly interpret the most important safety and data-quality signals without seeing sample output.

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 schema already documents all three parameters. The description adds value by explaining mode semantics, that topic auto-fetches matching events, that explicit parameters override the mapped side, and that both modes use identical matching logic. It does not add exhaustive per-parameter syntax detail, but the mode framing is genuinely useful beyond the schema.

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

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

The description opens with a specific verb and resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes itself from the polymarket_* siblings by naming both venues and explaining that the signal is the price delta between them, not a single-venue edge.

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 tool states two explicit modes, when to use each, and that both run the same matcher: 'topic' for pre-mapped shortcuts and explicit ticker/slug for custom pairings. It also warns that pre-mapped topics often return compatibility warnings. However, it does not explicitly contrast itself against sibling arbitrage tools like polymarket_arbitrage, so the 'vs alternatives' guidance is implied rather than fully stated.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds scoping per identifier and listing behavior, which is useful beyond annotations.

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

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

Three sentences, front-loaded with main functionality. Every sentence adds value: functionality, use case, and integration with siblings. No redundancy.

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

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

Given the tool's simplicity (one optional param, no output schema), the description covers all necessary aspects: how to use, when to use, scope, and pairing with related tools.

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

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

Schema coverage is 100% and the schema already explains the key parameter. Description restates behavior but does not add new semantic meaning beyond what the schema provides.

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

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

Explicitly states the tool retrieves a saved value or lists all keys. Clearly distinguishes from sibling tools 'remember' and 'forget' by name and action.

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

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

Provides explicit guidance on when to use (look up stored context without re-derivation) and implicitly when not (use forget for deletion). Mentions scoping and pairing with remember/forget.

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 safe read-only behavior; description adds valuable specifics: mark_read affects future calls, returns source/citation_uri/payload, and notes feed persistence and pagination via limit. No contradictions.

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

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

Five sentences, front-loaded with main action, then details in logical order. No redundancy each sentence adds unique 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?

Despite no output schema, description covers return fields, filtering, pagination (limit), mark_read behavior, and even alternative access method. Sufficient for agent to use correctly.

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

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

Schema covers all 5 parameters (100% coverage). Description adds contextual examples (e.g., 'sec_8k' for type, ISO timestamp for since, default limit 50) and clarifies mark_read effect, moving beyond schema to enhance understanding.

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

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

Description clearly states action ('pull fired events'), resource ('subscription feed'), and key return fields (source, citation_uri, payload). Distinguishes from HTTP endpoint alternative, making 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?

Provides context that polling works fine and mentions an HTTP alternative for scripts/dashboards, but does not explicitly state when to use this tool vs sibling tools or when not to use it.

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

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

Beyond annotations (readOnly, idempotent, etc.), the description details multi-source parallel calls, fallback mechanism, soft-fail for USPTO, and the return format including citation URIs.

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?

Front-loaded with example queries, every sentence adds value, no redundancy.

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

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

Despite no output schema, description fully explains the return structure (grouped changes, count, URIs). Covers all behavioral aspects for effective use.

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

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

Schema coverage is 100%, but description adds context: explains 'since' formats (ISO/relative), mentions recommended default, and clarifies 'value' accepts ticker or CIK.

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

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

The description specifies the tool fetches a change feed for a company from multiple sources within a time window. It provides example queries like 'what's new with X' and distinguishes from sibling '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?

Explicitly tells when to use this tool vs 'entity_profile', gives query examples, and describes fallback behavior between GDELT and GNews.

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

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

The description adds significant behavioral context beyond annotations: persistence scoped by identifier, 24-hour retention for anonymous, persistent for authenticated users. Annotations provide idempotentHint=true and destructiveHint=false, which are consistent. The description could mention overwrite behavior explicitly, but the idempotent hint suggests safe overwrite.

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?

Highly concise at four sentences, each adding unique value. Front-loaded with purpose, then usage guidance, then technical details. No wasted words.

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

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

Covers storage behavior, scope, persistence, and pairing with siblings. No output schema needed for a write operation. Could mention size limits, but not essential for typical use. Completeness is adequate.

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

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

Schema coverage is 100% with good descriptions. The description adds value by providing concrete examples of keys (subject_property, target_ticker, user_preference) and values, enhancing the context beyond the schema alone.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later.' It specifies the verb 'save' and resource 'data' as key-value pairs. The description distinguishes itself from sibling tools 'recall' and 'forget' by focusing on saving, not retrieving or deleting.

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

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

Explicit guidance on when to use: 'when you discover something worth carrying forward.' It also mentions pairing with recall and forget for related operations. While it doesn't explicitly state when not to use, the context is clear. The description also clarifies retention policies for authenticated vs anonymous sessions.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses important behavioral nuances: graceful degradation when GLEIF or OpenFIGI is unavailable, cascading internal lookups, conditional parent/ownership data, and the fact that ISINs resolve to the issuing legal entity. This substantially enriches the agent's understanding of what the call will and will not produce.

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 user-intent examples and a clear 'use first' directive, and every section earns its place given the tool's complexity. However, the long parenthetical-heavy sentences and nested clarifications make it denser and harder to parse than ideal, slightly reducing conciseness.

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

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

Despite lacking an output schema, the description fully explains what types of results are returned for each entity type (CIK, ticker, company name, LEI, FIGI, RxCUI, ingredient, brand, citation), including edge cases like non-US issuers and instruments without tickers. No critical operational aspect 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?

Even though schema coverage is 100%, the description adds critical parameter semantics beyond the schema: accepted input forms (ticker, CIK, ISIN, or name), what value should contain for bonds versus full noun phrases, and the distinction between brand and generic drug names. This is exactly the kind of practical guidance that prevents incorrect invocation.

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 with specific verbs: it resolves user-spoken names and identifiers to canonical/official identifiers required by other tools. The extensive query examples and supported types (company, drug) make the resource and scope immediately obvious, and it distinguishes itself as the identifier-resolution step rather than a profiling or research tool.

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

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

The description gives an explicit usage rule: 'Use FIRST whenever you have a name but need an ID.' It also clarifies what kinds of instruments resolve here (including non-equity instruments) and notes that it replaces 2-3 manual lookups. However, it does not explicitly name alternative tools or state when not to use it, so the guidance is strong but not fully exclusionary.

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 safety traits (readOnly, idempotent). The description adds behavioral detail: how it works (probes each entity with ai_visibility_check, ranks, surfaces extremes). However, it does not mention potential cost/rate limit implications of multiple probes.

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 with no filler; the purpose and mechanism are front-loaded. Every sentence earns its place.

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

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

Despite lacking an output schema, the description sufficiently describes the return format (ranked list with score, confidence, signal density). All key aspects are covered.

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

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

Schema coverage is 100%, and the description adds meaning beyond schema: clarifies 'entities' ordering (first is subject), explains 'context' use for disambiguation, and notes default model for 'models'.

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

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

The description uses a specific verb ('compare') and resource ('AI visibility across multiple entities side-by-side'), and clearly distinguishes from siblings like ai_visibility_check (single entity) and compare_entities.

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

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

It provides a clear use case ('competitive AI-marketing audits') and an example query, but does not explicitly state when not to use or mention alternative tools.

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

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

Annotations already set safe, read-only, idempotent traits. The description adds crucial behavioral context: multi-source fan-out, bundlephobia's slow first measurement (5-30s), and the sources_failed field. 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?

Packaged densely - three sentences cover purpose, usage, ecosystem scope, and edge cases. Could be slightly more concise (e.g., merge the first two sentences), but every sentence adds unique 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?

Despite no output schema, the description lists all return fields and explains behavior during partial failures. It addresses complexity: multi-source, version defaults, ecosystem restriction, and performance caveat. Fully complete given the tool's sophistication.

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

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

Schema coverage is 100% with clear parameter descriptions. The description adds useful context: defaults to latest version when omitted, and confirms scoped packages are accepted. Slightly more than the 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 instantly communicates the tool's composite nature (deps.dev + bundlephobia), the specific question it answers ('is X safe / popular / small'), and the output summary fields. It distinguishes itself from any potential sibling tools that might do similar checks (e.g., 'deps.dev:version' for other ecosystems).

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

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

Explicit 'Use whenever...' instruction with example queries. Clearly states ecosystem limitation (NPM v1) and directs users to alternative tools for other ecosystems. Also describes graceful degradation for partial failures.

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?

Discloses embedding model (BGE-base-en), similarity metric (cosine), window size (500-char overlapping), character cap (200K chars with truncation flag), and offset verification, far exceeding the read-only/idempotent annotations.

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

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

Front-loaded with core purpose, then usage guidance, then technical details. Every sentence is informative and no fluff.

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

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

Despite no output schema, description clearly states return type (top-N passages with offsets and scores) and edge cases (truncation). Covers all needed 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%, so baseline is 3. Description adds no new information beyond the schema's parameter descriptions; it restates the text and query examples but doesn't clarify limit behavior.

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

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

Clearly states semantic search inside a fetched record with specific examples (SEC 10-K body, article). Explicitly pairs with ask_pipeworx_grounded, distinguishing itself from siblings.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and mentions alternative grounding tool, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations indicate a non-read-only, non-destructive, open-world, and idempotent operation. The description adds context: subscription creation requires authentication, returns an ID, and details delivery constraints (SMS cap, webhook signing). 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 reasonably concise for the complexity, with clear sections for types and delivery. Every sentence adds value, though it is somewhat lengthy. Front-loaded with the core purpose.

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

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

Given no output schema, the description mentions returning the subscription ID. It covers types, parameters, delivery channels, and constraints. Lacks explanation of what happens on duplicate subscriptions or error scenarios, but still quite 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%, but the description significantly enhances understanding by providing concrete examples for each subscription type and detailed delivery options (e.g., phone verification, webhook secret). This goes well 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 clearly states the action ('Create a proactive monitoring subscription') and the resource ('live-data event stream'), and explicitly mentions returning the subscription ID. It distinguishes from siblings like 'unsubscribe' and 'list_subscriptions'.

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

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

Provides clear context such as the requirement for a Pipeworx OAuth account and the inability of anonymous/BYO users to persist subscriptions. Lists supported types with examples but does not explicitly state when not to use this tool or recommend alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds significant context: it returns example questions with exact tool+argument shapes from a live catalog, and lists categories. This fully describes behavior beyond annotations.

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

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

Every sentence adds value: starts with example questions, states purpose, lists categories, gives usage instructions. No fluff, well-structured, appropriately sized for the complexity.

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

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

With no output schema, the description fully covers return format (category-bucketed examples with tool+argument shape). It also mentions live catalog and meta-tools. Annotations cover safety. Complete for a discovery tool with one optional parameter.

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

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

Schema coverage is 100%, so baseline is 3. The description reaffirms the topic parameter's purpose and optionality but does not add new semantic information beyond the schema. It provides usage context, which is more relevant to usage guidelines than parameter semantics.

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

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

The description clearly states that the tool returns category-bucketed example questions about Pipeworx capabilities, with specific verb+resource and explicit differentiation from siblings like 'discover_tools' by positioning it as the onboarding entry point.

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 explains when to use this tool (first interaction, when unsure of capabilities, to learn meta-tools) and provides two usage modes: full spread with no arguments or focused with a topic. No exclusions needed, but the context is clear.

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

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

Annotations indicate write operation with idempotency and non-destructive nature. Description adds value by clarifying ownership enforcement and that rows are deactivated (not deleted), with reference to 'recent_alerts' for historical availability.

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

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

Two concise sentences, front-loaded with key action. Every sentence provides essential information 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?

For a simple tool with one parameter, description covers purpose, ownership, behavioral effect, and connection to historical data. No output schema needed.

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

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

Input schema has 100% coverage with one parameter 'id'. Description adds ownership context beyond schema, enhancing understanding.

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

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

Description clearly states 'Cancel a subscription by id', specifying the action and resource. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Explains ownership enforcement ('you can only cancel your own subscriptions') and side effects (deactivation vs deletion). Provides context on when to use, though no explicit alternatives.

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

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

The description goes well beyond the annotations by explaining key behavioral nuances: the distinction between could_not_verify (error) and unsupported (no source coverage), the verification_error field, the two processing paths, and the return format with verdicts and citations. This aligns with and enriches the openWorldHint and readOnlyHint annotations without contradiction.

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

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

The description is relatively long but well-structured: it front-loads purpose with examples, then details processing paths and critical caller guidance. Every sentence provides needed information for a complex tool, though it could be slightly more concise 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?

Despite no output schema, the description fully explains return values, verdict categories, error handling, and fallback behavior. It covers both main claim types and gives implementation details like pipeworx:// citations. This makes the tool self-sufficient for an agent to invoke correctly.

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

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

Schema coverage is 100%, with both claim and tolerance_pct already well-described in the input schema. The description adds context about claim handling (e.g., exact percent-delta math for financial claims) but doesn't significantly advance parameter understanding beyond the schema, so it earns the baseline score.

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, with explicit example queries. It distinguishes itself from siblings by focusing on fact-checking and returning verdicts, and it details the two distinct processing paths (structured SEC EDGAR for company-financial claims, grounded pipeline for other claims).

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' providing clear context. It also explains that it replaces 4–6 sequential calls, indicating efficiency. However, it doesn't explicitly name alternative tools or state when not to use it, so it lacks full when-not guidance.

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