Futuur

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

Annotations already declare readOnly, openWorld, and idempotent hints. The description adds valuable operational context: the default free model, the fact that `_apiKey` passes through to Anthropic with direct cost to the user, and the return structure (per-model plus combined). No contradictions. It could mention rate limits or cache behavior, but the added cost and model context is meaningful 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 three tightly structured sentences. The first front-loads the core action and outcome, the second covers operational details (default model, API key cost), and the third lists use cases. No redundant phrasing or filler.

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

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

Even without an output schema, the description provides the return shape ('per-model {score, confidence, signals, raw_response} + a combined view'), model selection, cost, and use cases. For a 4-parameter read-only tool with strong annotations, this is complete enough for an agent to select and invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining cost implications of `_apiKey` ('BYO key — you pay Anthropic directly') and reinforcing the default model behavior. This exceeds what the schema alone provides, though much of the parameter detail is already in the schema.

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

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

The description uses a specific verb ('probe') and resource ('LLMs') with a measurable outcome (visibility score 0-100). It clearly distinguishes what the tool does from generic search or ask tools, and the mention of default vs optional models adds concrete scope. This is more specific than a typical list 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 explicitly lists target use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' This provides clear usage context. However, it does not name sibling tools like scan_competitor_ai_presence or offer exclusions/when-not-to-use, so it misses the highest level of guidance.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, lowering the burden on the description. The description adds useful behavioral context by explaining that the tool routes to other tools, fills arguments, and returns structured answers with stable citation URI. It does not fully describe edge-case behavior such as what happens when no source matches, hence the 4.

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

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

The description is long but every section contributes: the domain list conveys scope, the examples provide concrete query patterns, and the alternative-tool guidance ensures proper selection. It sacrifices a little conciseness to include robust decision rules, which matters for a tool of this 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?

For a broad, high-level router tool, the description is nearly complete: it states what the tool does, when to use it, how to distinguish it from siblings, and what to expect as an output (structured answers with citations). No output schema exists, so this description carries that burden well.

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% — the single meaningful parameter 'question' is documented as a natural-language request, and all aliases (q, text, input, query, prompt) are explicitly enumerated as aliases. The tool description adds no additional parameter semantics beyond those already present in the schema, so the baseline score of 3 is appropriate.

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

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

The description unambiguously identifies the tool as an orchestration/router: it routes the question to one of 5,596 tools across 1,465 verified sources, fills arguments, and returns structured answers with pipeworx:// citation URIs. The explicit list of domains (SEC filings, FDA data, FRED/BLS, patents, weather, clinical trials, etc.) and the opening phrase 'PREFER OVER WEB SEARCH' clearly distinguish it from the broader universe of search tools.

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

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

It gives precise trigger phrases: 'what is', 'look up', 'find', 'get the latest', 'how much', 'current', and any factual query about real-world entities, events, or numbers. It also gives explicit alternative routing: ask_pipeworx_grounded for a single authoritative answer, deep_research for broad multi-part questions, resolve_entity when an ID is needed first, and discover_tools for checking which sources exist.

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

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

With annotations declaring readOnlyHint, openWorldHint, idempotentHint, and destructiveHint of false, the description is not responsible for safety. It adds real behavioral context by explaining the live candidate experimentation, the current inactive-candidate state, and the fact that it works as a full router rather than falling back to the stable one.

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

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

The description is longer than minimal but information-dense, covering identity, current state, usage, and the crucial no-fallback clarification. It is front-loaded with the 'beta version of ask_pipeworx' identity and the comparison to the stable router. A few implementation-specific details, like the exact number of tools and the date, are more detail than strictly necessary.

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

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

The required question parameter and the six aliases are documented in the schema, and the description clarifies how the beta tool behaves relative to the stable one. It does not spell out the response structure, but it states the response shape is the same as ask_pipeworx, which is a meaningful and sufficient reference for an agent.

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

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

Schema description coverage is 100%, with each parameter explicitly documented as an alias for the question field. The description adds only a generic 'same arguments' statement and does not add detail per parameter. Since the schema already carries the full parameter meaning, a baseline 3 is appropriate.

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

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

The description clearly positions this as a beta variant of ask_pipeworx, a universal router with the same tools, arguments, and response shape as the stable version. It distinguishes the tool from ask_pipeworx and ask_pipeworx_grounded in the sibling list by explaining that it is the experimental edge of the same functionality.

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 it exactly like ask_pipeworx when you want the newest routing.' It also clarifies the current state, that no candidate is active, and that this is not a fallback wrapper but a full working router. This provides strong direction for choosing it over alternatives.

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

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

The description thoroughly discloses behavioral details beyond the annotations: it explains the tool only extracts from tool result content, provides the full success response shape, and enumerates explicit refusal reasons. It also mentions the additional LLM cost versus the sibling. No annotation contradiction exists.

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

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

The description is dense and packs useful detail, including response shape, return values, refusal reasons, and alternative routing. It is slightly longer than strictly necessary, but each sentence adds meaningful information for someone selecting this tool.

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

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

Without an output schema, the description ensures the agent knows exactly what to expect: success payload with evidence and confidence, refusal payload with failure categories, and the cost/risk trade-off. Combined with the broad, detailed annotations, an agent can use this tool without ambiguity.

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

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

The input schema has 100% parameter description coverage, with all six parameters mapped to a natural-language question alias list. The description adds no extra parameter-heavy semantics beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description states a specific verb and resource: it is a hallucination-resistant answer mode that grounds its output only in fetched tool data. It distinguishes itself from ask_pipeworx by emphasizing exact extraction from the tool result and refusal behavior, so an agent can reliably tell which mode is intended.

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

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

The description gives explicit usage conditions: use it when answers will be quoted, cited, or acted on and facts must not be invented, and prefer ask_pipeworx for casual lookups because of the extra LLM call. This is clear when-to-use and alternative 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?

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses extensive behavioral traits: low-confidence matching short-circuits with a blocking status, closed markets either return a specific status or surface via low_confidence_match, wide-spread markets get tradeability flags, and the cancellation-rule parsing exposes settlement risks. It also details fallback behavior under GDELT 429s and the implications of include_raw sizes.

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?

Although long, the description is meticulously structured with uppercase section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, NEWS FIELDS, SAFETY) and front-loaded with the core purpose. Every section adds necessary context for a complex research tool, and there is no filler or tautology.

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 edge cases. It comprehensively covers response shapes (result.market, result.analysis, result.evidence), resolver contract fields, parent_event extraction, news fallback flags, market statuses, safety short-circuits, and cancellation-rule risk, leaving little ambiguity for an agent to misuse the tool.

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

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

The input schema already describes all three parameters with 100% coverage, so the baseline is 3. The description adds value beyond the schema by explaining how the market parameter can be a slug, URL, or question text and how the tool resolves it, what depth levels imply via fan-out examples, and why include_raw=false is recommended with response size implications. This enriches parameter understanding without being redundant.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It immediately distinguishes itself from sibling tools like get_market or deep_research by focusing on bet research with fan-out to category-specific data packs, and it explicitly lists use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z').

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 with clear examples and classifier categories, and it provides detailed fan-out examples. However, it does not explicitly name alternatives or state when not to use this tool (e.g., for simple market quotes use get_market), so it falls short of a 5 but is clearly above the baseline.

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

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

Annotations already indicate readOnly/openWorld/idempotent, and description adds rich behavioral context: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, result sorting by primary metric, and per-entity citation URIs. No contradiction with annotations.

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

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

Every sentence earns its place; the description is front-loaded with trigger phrases and then packs factual details (data sources, fiscal year handling, sorting, citations). Although long, it is dense and structured for quick 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?

For a tool with no output schema, the description sufficiently describes return semantics (paired data, sorted results, citation URIs), use cases, and constraints. It fully compensates for the absence of an output schema and covers both entity types.

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

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

Schema has 100% parameter coverage, but description adds meaning beyond property names: explains what each type actually pulls (revenue, adverse-event counts, trial counts) and gives concrete value examples (tickers vs drug names). This goes beyond the basic schema text.

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

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

Description uses specific verb 'compare' with clear resource (companies/drugs) and examples of user phrasings. It explicitly distinguishes from sequential single-pack lookups and sibling entity_profile, and scope is precise (2–5 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?

Provides explicit when-to-use triggers ("X vs Y", "which is bigger", "rank these companies") and states ALWAYS PREFER over sequential lookups. Also clarifies type-specific behavior (company vs drug) and that it replaces 8–15 lookups.

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 account/tier requirements, parallel tool decomposition, gap reporting with "never invented" evidence, contradiction detection for certain depths, resolvable citation behavior, semantic excerpting, and latency estimates. These are exactly the non-obvious behaviors an agent needs before invoking the tool.

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

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

The description is long, but densely organized: it front-loads account requirements and alternatives, then explains the core mechanism, use cases, depth behavior, output details, and timing. Each sentence earns its place even though the total length is higher than a typical tool description.

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

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

Since there is no output schema, the description adequately carries the return-value burden by describing the findings packet: evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], and hop fields. Combined with coverage of auth, depth, routing, and timing, an agent has enough context to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining what the depth values actually change in terms of hops and recovery behavior, clarifying that thorough requires a paid plan, and confirming that questions can be broad and multi-part. This is meaningful extra value, though the schema already does substantial work.

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: grounded multi-source research over Pipeworx's 1,465 structured data sources in a single call. It explicitly contrasts itself with open-web search and ask_pipeworx, and gives example questions to make the target use concrete and distinct from sibling tools.

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

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

The description provides strong routing guidance: use this for broad/multi-part structured questions; use ask_pipeworx for single lookups, breaking/current news, or when the user is not signed in. An agent can decide which sibling to invoke without additional inference.

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

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

Annotations already communicate the safe read-only/idempotent nature. The description adds valuable behavioral context beyond that: it specifies the return format (names, descriptions, full input schemas with curated examples), guarantees the results are ready to call without a second lookup, and notes the top-N relevance behavior. This meaningfully extends what the 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 three sentences, each earning its place: purpose, return-value detail, and strategic usage. It is front-loaded with the core verb and resource, then efficiently adds necessary detail without unnecessary filler. No redundancy with annotations or schema.

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

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

Given the tool's moderate complexity, no output schema, and rich annotations, the description is complete. It explains what is returned (top-N tools with schemas/examples), why to use it first, and what kinds of queries are supported. No critical behavioral aspect is left unexplained.

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

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

Schema description coverage is 100%, so parameters are fully documented structurally. The description adds general context (query is a natural language description) and implies the limit parameter via 'top-N', but does not deepen semantics beyond the schema. This meets the baseline for full schema coverage without adding unique parameter insight.

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

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

The description clearly states a specific verb+resource: 'Find tools by describing the data or task.' It identifies the tool as a discovery/meta-search tool, distinguishing it from siblings which are task-specific. The scope is explicit (SEC filings, FDA, FRED, etc.), making the purpose unmistakable.

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

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

The description provides explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and a strategic directive to 'Call this FIRST when you have many tools available.' It also implies when not to use (when you need 'just one answer'), effectively guiding the agent toward this tool for exploration and away from it for direct known-tool calls.

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, it discloses a parallel-call execution model, a soft-fail for the USPTO API sunset ('soft-fails until reactivated'), a GDELT→GNews fallback, and output limits like 'up to 5' filings. It also states the US-public-company scope, which annotations do not cover.

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 packed with useful details, but it contains some redundancy (e.g., repeating the schema's parameter guidance). It is front-loaded with trigger phrases and a clear purpose, earning a 4.

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 well by enumerating the exact return fields (cik, recent_filings, fundamentals, patents, news, LEI) and their ordering/limits. It also covers input constraints, fallback behavior, and sibling differentiation, making it highly complete for a tool of this complexity.

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

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

Schema description coverage is 100%: both 'type' and 'value' already provide detailed descriptions including ticker vs CIK and the unsupported-name caveat. The description mostly restates this with examples ('AAPL', '0000320193'), adding no new semantic meaning beyond the schema.

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

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

The description opens with concrete user phrasings and clearly states 'full cross-source profile of a US public company in ONE parallel call.' It explicitly differentiates from sibling tools by instructing to 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news 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?

It gives explicit when-to-use guidance: 'ALWAYS PREFER over chaining single-pack...when the user asks for a holistic view.' It also provides an exclusion and fallback: 'names not supported (use resolve_entity first if you only have a name).'

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds contextual value by noting it clears 'sensitive data the agent saved earlier' and applies to 'previously stored memory', which helps the agent understand the nature of what is destroyed. No contradiction with annotations.

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

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

The description consists of three short sentences, with the action verb and object front-loaded. It provides purpose, usage guidance, and sibling pairing without any filler or redundancy.

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

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

For a single-parameter deletion tool with destructive and idempotent annotations, the description is sufficiently complete: it covers what the tool does, when to use it, and the type of data involved. It does not mention return values, but there is no output schema, so this is not a significant gap.

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

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

Schema coverage is 100% and the only parameter ('key') has a clear description ('Memory key to delete'). The description's mention of 'by key' adds no additional meaning beyond what the schema already provides, so it meets the baseline without enhancing parameter understanding.

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

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

Description starts with 'Delete a previously stored memory by key' – a specific verb (delete) with resource (memory) and mechanism (by key). It clearly distinguishes from siblings 'remember' and 'recall' by positioning itself as the removal counterpart, and 'previously stored' reinforces that it acts on existing memories.

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 when' conditions are provided: stale context, task done, or clearing sensitive data. This gives clear context for when the tool is appropriate. However, it does not explicitly state when not to use it or name direct alternatives, though pairing with 'remember' and 'recall' implies complementary usage.

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

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

Beyond the annotations (readOnly, idempotent, etc.), the description adds concrete behavioral details: it 'fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' This explains the operational flow without contradicting the readOnlyHint.

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

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

The description is concise—three functional sentences plus a bullet-like list of use cases. It is front-loaded with the primary action, and every sentence earns its place without redundancy.

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

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

For a simple 2-param read-only tool with strong annotations, the description is largely complete: it covers purpose, process, output format, and use cases. It lacks only explicit error/edge-case handling or exact markdown structure examples, but these are not critical for this tool.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add additional parameter-level meaning beyond what the schema already provides (url and max_links are both described in the schema). It mentions 'key links' but does not clarify parameter nuances.

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

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

The description begins with a specific verb+resource: 'Generate a production-ready llms.txt file for any URL.' It clearly distinguishes the tool from siblings like ai_visibility_check or scan_competitor_ai_presence by focusing on generating the llms.txt file itself, not merely checking 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 provides explicit use cases under 'Useful for:', such as getting a client's site indexed or auditing competitors. However, it does not name specific alternative tools or state when NOT to use it, so it falls short of the 5-level explicitness.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds meaningful context beyond annotations by specifying the exact return contents (outcome list, implied probabilities in both OOM and USDC, volumes, tags, description, resolution status) and the keyless auth requirement.

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

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

The description is two purposeful sentences with zero waste: a front-loaded verb+resource, a compact list of return fields, a concrete example id, and the keyless note. Every element earns its place.

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

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

For a one-parameter retrieval tool with no output schema, the description fully covers what the caller can expect, including the market's outcome structure and the specific probability formats. No significant 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?

The single id parameter has 100% schema coverage, including a clear description and how to obtain ids. The tool description only reiterates 'by id' and provides an example, so it adds no substantial semantics 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+resource ('Get one Futuur market by id') and enumerates the returned payload, clearly distinguishing it from list/search sibling tools like search_markets and top_markets.

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 a known market id, but it does not explicitly state when to use this tool versus alternatives or mention that ids come from search_markets/top_markets. That guidance exists in the parameter schema, not in the description itself.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations by specifying it returns the caller's own subscriptions (only active by default), and listing the exact return fields, which is useful for downstream actions like cancellation. No contradiction with annotations.

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

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

The description is two sentences with no filler. The first sentence states the core purpose and return fields; the second provides concrete usage guidance. Every word adds value, and the structure is front-loaded with the most important information.

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

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

Given the tool's simplicity (1 optional parameter, no output schema), the description is complete. It covers the tool's scope (caller's active subscriptions), return fields (compensating for lack of output schema), and typical use cases. There are no obvious gaps for an agent to invoke or interpret the results correctly.

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

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

The input schema has 100% coverage: the only parameter, include_inactive, is fully described as including cancelled subscriptions and defaulting to false. The description's mention of 'active subscriptions' implicitly aligns with this parameter, but it does not explicitly explain the parameter. With schema coverage this high, a baseline of 3 is appropriate.

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

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

The description clearly states the verb 'List' with the specific resource 'the caller's active subscriptions', and enumerates the exact return fields (id, type, params, created_at, last_fired_at, fire_count). This distinguishes it from sibling mutation tools like subscribe and unsubscribe, and from other list tools by focusing on 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?

The description provides explicit usage context: use it to review active monitoring before adding more subscriptions and to find an ID to cancel. While it does not explicitly name alternatives, the context clearly implies this is the read-only counterpart to subscribe/unsubscribe, making the usage intent 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?

Discloses behavioral specifics beyond annotations: the claim_token return/reuse workflow, a daily rate limit of 5 per identifier, that it's free and doesn't count against quota, and content policy (describe in terms of Pipeworx tools, don't paste user prompt). These are non-obvious traits an agent needs to use the tool correctly. No contradiction with annotations (readOnlyHint=false).

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 operational information: use cases, exclusions, token mechanics, rate limits, and content guidance. It is long but dense, with no fluff or repetition of the tool name. The description earns its length given the tool's routing rules and follow-up workflow.

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

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

The description covering use cases, exclusions, parameter behavior, rate limits, and the expected claim_token flow provides complete operational guidance. Even without an output schema, the description explains what the agent will receive and how to continue the follow-up loop, making it sufficient for this moderately complex tool.

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

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

Schema already provides thorough descriptions for all 4 parameters (100% coverage). The description adds real value beyond the schema by explaining the claim_token lifecycle (how to pass it back later to read status) and giving message content rules (be specific, 1-2 sentences, don't paste the user's prompt). This elevates it above 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?

Clearly states its function: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It distinguishes from sibling tools by focusing on team feedback rather than data retrieval or research, and clarifies that it applies only to tools served by this Pipeworx connection.

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 categories (bug, feature/data_gap, praise) and when-not-to-use (other MCP servers' tools), plus a disambiguation heuristic ('Pipeworx tool names are the ones this connection lists'). This is exemplary guidance for an AI agent deciding between this and alternatives.

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

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

Annotations already declare this tool read-only, open-world, idempotent, and non-destructive. The description adds substantial behavioral context beyond that: it is self-aggregating, derived from CF analytics-engine, contains no PII (only pack/tool/count), and is cached for 5 minutes to 1 hour depending on the window. These details give the agent a clear understanding of data source, privacy, and freshness.

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

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

The description is three sentences long and efficiently structured: the first sentence states the core purpose, the second lists usage scenarios, and the third provides technical details about data source and caching. Every sentence earns its place, though the list format could be slightly tighter.

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

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

For a simple, read-only aggregation tool with one optional parameter and no output schema, the description is comprehensive. It explains what is returned, when to use it, and key operational characteristics (caching, privacy, source). No critical information is missing for an agent to decide whether and how to invoke this tool.

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

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

The only parameter, window, has 100% schema coverage, including an enum and a description explaining that shorter windows surface hot trends while longer windows show steady-state demand. The tool description merely repeats the window options without adding new semantic detail, so the baseline score of 3 is appropriate.

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

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

The description opens with a clear, specific statement of what the tool does: 'What other AI agents are calling on Pipeworx right now' and explicitly lists the return contents ('top tools, top packs, and total call volume'). It distinguishes itself from siblings like discover_tools and top_markets by focusing on agent call activity rather than general discovery or market data.

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

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

The description provides an explicit 'Useful for' section with three concrete use cases: discovering hot data sources, confirming canonical tools, and checking alignment of use cases. However, it does not name any alternatives or state when not to use the tool, so it falls just short of full 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 the tool read-only, open-world, idempotent, and non-destructive. The description adds substantial operational context: it walks child markets, checks date/threshold ordering, applies Jaccard similarity threshold (≥0.30), drops placeholder slugs, and explains the fill check against live CLOB depth with a precise behavioral rule ('do not trade it'). This exceeds what annotations could convey.

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

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

The description is long but densely informative, with clear structure: first sentence states purpose, then each mode is explained in turn, and return fields are enumerated. No filler sentences, though it could be slightly tightened by moving the fill-check explanation to a separate section. Still, every sentence earns its place given the tool's complexity.

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

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

With no output schema, the description fully specifies the response structure (opportunities[], partition_check, fill check fields). It also covers edge cases (skipped_low_similarity, placeholder filter, null arb signal) and the no-argument defaults. Combined with the rich annotations, this is a complete, self-contained specification for a complex tool.

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

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

Schema coverage for both parameters is 100%, but the description goes far beyond the schema. It explains real-world usage examples ('fed-decision-may-2026'), accepts full URLs, clarifies that topic mode 'searches related events across the platform', and describes the internal processing for each parameter. This adds significant semantic meaning beyond the schema's bare definitions.

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

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

Description opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes from sibling tools like polymarket_edges and polymarket_edge_tracker by naming the exact detection methods and the multiple scan modes (trending_scan, event, topic).

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: no args for trending_scan of top ~200 markets, 'event' for single-market analysis, 'topic' for cross-event scanning. It also names an alternative tool for custom sizing ('For custom sizing use polymarket_fill_risk') and gives a clear do-not-trade rule when realizable edge is ≤0.

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

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

Annotations already cover read-only, idempotent, and non-destructive traits, but the description adds extensive behavioral context: response structure with by_segment and diagnostics, 1-hour KV caching keyed on all knobs, the '24h-move warning' when recent price movement exceeds the edge, and the fed_candidates exclusion rationale. It even explains why segments can be empty via funnel counters, going well beyond the annotation baseline.

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

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

The description is front-loaded with a clear first sentence, but it becomes a dense wall of text with ALL-CAPS headings and heavy jargon (FRED, GDELT, overround, backstops, Run 8). It is longer than necessary and contains an inconsistency (states FIVE model families but lists only four distinct models). Section headings help, but the overall lack of editing precision keeps it from being highly concise.

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 specifies the response shape: top-level by_segment with three keys, fed_candidates/fed_note, and _diagnostics with funnel counters and category counts. It also defines all opportunity fields (edge_pp_net, kelly_fraction, liquidity, spread_pp) and covers edge cases like empty segments and cached results. For a complex 9-parameter tool, this ensures a caller can anticipate behavior and interpret 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?

The input schema has 100% parameter coverage with detailed descriptions, which sets a baseline of 3. The description adds relational meaning beyond the schema: it clarifies that min_kelly never filters partition arbs and that min_partition_leg_kelly applies to per-leg Kelly inside top_legs, and it contextualizes slippage_pp within Polymarket's zero-fee but thin-book environment. This extra interaction knowledge justifies a score above baseline.

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

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

The description clearly states a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It differentiates from sibling tools like polymarket_arbitrage by focusing on model-driven edges and structural arbitrage, and it frames the use case as 'what should I bet on today' with concrete model families and response segments.

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 strong context for when to use the tool: discovering opportunities without paging through hundreds of markets, and it explains the role of tradeable-edge knobs like min_liquidity and max_spread_pp. However, it does not explicitly name alternative tools (e.g., polymarket_edge_tracker, get_market) or state when not to use this tool, so it stops short of a full when/when-not comparison.

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

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

Annotations declare safe read-only/idempotent behavior, but the description adds substantial non-obvious details: snapshots are written only on cache-miss (so gaps are meaningful), decay is computed on absolute edge_pp_net values, and history is bounded by a 60-day TTL plus snapshotting enablement. This greatly exceeds annotation coverage and does not contradict it.

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?

Although long, the description is densely packed and logically structured with explicit sections for Args, RESPONSE, and LIMITS. Every sentence conveys necessary nuance: the response format, edge-case behavior, and constraints. No filler or redundancy; the format aids 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?

Despite lacking an output schema, the description fully explains the response structure (tracked[], expired[], snapshot_dates[]), the meaning of each field, and important limitations (TTL, gaps, daily-vs-intraday). Given the tool's moderate complexity, this is complete and leaves no critical gaps for an agent to invoke and interpret results.

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

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

Schema coverage is 100%, providing baseline 3, but the description adds value by explaining the semantic role of 'window' as a snapshot family, reinforcing 'days' as lookback, and clarifying how parameters affect the response (e.g., snapshot_dates reflect actual data days). This enriches parameter understanding beyond the schema's mechanical definitions.

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

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

The description clearly states the tool's function: it provides 'edge persistence and decay telemetry' and answers the question 'how long has this edge existed and is it shrinking?' This distinguishes it from the sibling tool polymarket_edges, which likely lists current edges, while this tracker analyzes their history. The verb and resource are specific and unambiguous.

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

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

The description implies when to use it: 'a fresh wide edge and a 3-week-old wide edge are different trades' suggests checking edge age before trading. It also mentions 'the median lifespan is your competition clock,' providing contextual motivation. However, it does not explicitly name alternatives or exclusive conditions, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral context: it requires exactly one of `market` or `event`, describes mode-specific parameter interpretation, and discloses output fields including failure verdicts (clean|degraded|cannot_fill) and risk flags (thin_legs, forced_directional_risk). It even warns about partial basket fills converting an arb into an unhedged directional position. No contradiction with annotations; the description significantly enriches the safety profile.

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

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

The description is long but highly structured with clear labels (REQUIRES, SINGLE-MARKET, BASKET) and uses uppercase keywords for pivotal constraints. Every sentence serves a purpose: mode explanations, parameter semantics, output fields, and usage guidance. It's appropriately sized for a two-mode tool with rich return values; no dead weight or redundancy with schema.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so comprehensively: listing top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, theoretical_sum vs realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs, max_clean_notional_usd, and forced_directional_risk. It also covers parameter defaults, thresholds, and the strategic context (when to invoke before arbitrage trades). This is a model of completeness for a complex tool.

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

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

Schema coverage is 100% (every parameter has a description), but the tool description goes far beyond that. It explains that `market` selects single-market mode while `event` selects basket mode, clarifies that `side` default depends on mode and partition sum, and decodes `size_usd` differently for buys (max spend), sells (target proceeds), and basket mode (settlement notional shares per leg). This is essential disambiguation that the schema alone does not provide.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes itself from siblings like polymarket_arbitrage and polymarket_edges by focusing on fill risk and order-book depth. It also unambiguously describes two modes (single-market and basket), leaving no doubt about the tool's function.

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

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

The description provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the rationale (theoretical overround not capturable, partial fills create unhedged directional risk), which acts as a natural exclusion for small/thick-book trades. This is far beyond the typical 'use when needed' and clearly directs the agent to this tool over alternatives.

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

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

The description goes far beyond annotations by detailing complex behaviors: compatibility_warning triggers, temporal_alignment fields, skipped_cross_type/subtype counters, and what matched_pairs:0 with various conditions means. It also explains edge cases like non-equivalent bet shapes and semantically unrelated events, providing comprehensive behavioral transparency.

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

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

The description is lengthy but front-loaded with the core purpose and then structured into clear segments (modes, response, safety fields). Every sentence adds information about behavior or usage, though the text is dense and could benefit from bullet points or more whitespace to improve scanability. It is appropriately sized for the tool's complexity.

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

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

Given the tool's complexity, three simple parameters, and no output schema, the description thoroughly covers what the tool returns (leg-by-leg prices, top_spreads_pp), when warnings fire, and how temporal alignment affects meaning. It leaves no major gaps for an AI agent to misinterpret the tool's output or limitations.

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 substantial meaning to the parameters: it lists the exact topic values, explains that explicit tickers 'override' the topic-mapped side, and describes how the two modes interact. This enriches the schema's basic property descriptions, though the schema already carries much of the load.

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 computes a 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' using a specific verb-like intent (computing/spreading) and distinguishing it from other market tools by focusing on cross-venue comparison. It further specifies two modes and the exact output type, making its purpose unambiguous.

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

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

The description provides clear context on when to use the tool: it explains the pre-mapped topic shortcuts vs. explicit event pairings, and warns that 'real cross-venue spreads are rarer than the macro-shortcut list suggests' and 'pre-mapped ≠ tradeable.' It does not explicitly name sibling alternatives, but the guidance is strong enough to infer appropriate usage contexts.

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

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

Annotations already declare readOnlyHint and idempotentHint, so safety is covered. Description adds scoping detail ('Scoped to your identifier') and explains the optional key behavior for listing, which is 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, with the primary action in the first sentence and additional context in subsequent ones. No redundant or filler content.

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

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

For a simple 1-parameter tool with annotations and schema, the description covers purpose, usage, scoping, and relationship to sibling tools. No output schema means return format isn't required, and the low complexity doesn't necessitate more detail.

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 the single parameter with description 'Memory key to retrieve (omit to list all keys)'. The description repeats this information without adding new semantic details, so it earns the baseline.

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

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

Clearly states it retrieves a previously saved value or lists all keys, naming the specific verb 'Retrieve' and the resource (memory values). Distinguishes from sibling tools by explicitly referencing 'remember' and 'forget'.

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

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

Gives explicit guidance on when to use: to look up context the agent stored earlier without re-deriving it. Mentions the workflow with siblings ('Pair with remember to save, forget to delete'), which clarifies alternatives, though it doesn't explicitly say 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?

The description contradicts the annotations: annotations declare readOnlyHint=true, yet the description says 'Set mark_read:true to flag returned events read,' which is a state-changing side effect. This is a serious inconsistency, so score 1 per the rubric.

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

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

The description is three sentences with no filler. It is front-loaded with the primary purpose, then details return payload, filtering, mark_read behavior, and an alternative access method. Every sentence is informative.

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

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

The description covers return payload fields, filtering, mark_read side effect, polling suitability, and an alternative endpoint. Given there is no output schema, this is fairly complete, though the mark_read side effect is not reconciled with the readOnlyHint annotation, which is a completeness gap in terms of accuracy.

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 meaning beyond the schema by explaining the effect of mark_read ('so the next call only shows newer ones'), giving an example type ('sec_8k'), and clarifying that 'since' is an ISO timestamp. This enriches the 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 opens with a specific verb and resource: 'Pull fired events from your subscription feed.' It clearly states the tool returns recent alerts from the feed, and distinguishes itself from siblings like list_subscriptions by focusing on event payloads rather than the subscriptions themselves.

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

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

The description gives clear context on when to use the tool: to pull fired events, with filtering options. It also notes that 'Polls work fine' and provides an alternative URL for scripts/dashboards, which serves as an alternative. However, it does not explicitly state when not to use it or compare to siblings.

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

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

Beyond the read-only, idempotent, non-destructive annotations, the description reveals multi-source fan-out (SEC EDGAR, GDELT→GNews, USPTO), PatentsView sunset soft-fail, and the structured return shape (changes[], total_changes, pipeworx:// URIs). This is rich behavioral context the annotations alone do not provide.

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

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

The description is dense yet front-loaded with intent phrases. Every sentence contributes essential information: query patterns, source behavior, time formats, fallback logic, return structure, and an explicit sibling alternative. There is no filler.

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

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

With no output schema, the description compensates by stating the exact return structure (structured changes[] grouped by source + total_changes + citation URIs). It also covers operational caveats (rate limits, API sunset, soft-fail) and provides tool differentiation, making it comprehensive for a multi-source tool.

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

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

Schema coverage is 100%, so a baseline of 3 applies. The description adds meaningful guidance for `since` with formats and examples, plus a best-practice recommendation ('Use "30d" or "1m" for typical monitoring'). It does not add new semantics for `type` or `value`, but the added usage nuance justifies a 4.

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

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

The description opens with concrete user intents ('What's new with X', 'latest on Y') and immediately identifies the tool as a change feed for a company over a time window. It explicitly distinguishes itself from entity_profile, which serves the static profile, making its purpose unmistakable.

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

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

It gives explicit usage examples, explains source fallback behavior (GDELT preferred, GNews on rate limits/5xx), and names an alternative tool ('Use entity_profile instead when you want the static profile...'). This clearly tells the agent when to use this tool versus a sibling.

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

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

The description adds meaningful context beyond the annotations: memory is scoped by identifier, persists for authenticated users, and lasts 24 hours for anonymous sessions. It also implies non-destructive behavior (no mention of deletion, consistent with destructiveHint=false). This is exactly the kind of contextual detail that annotations don't capture.

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

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

The description is compact yet information-dense. Each sentence earns its place: purpose, usage triggers, storage model, persistence caveats, and related tools. It is front-loaded with the primary purpose and avoids fluff.

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

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

Given the tool's simplicity (2 params, no output schema) and the richness of annotations, the description covers all essential aspects: what it does, when to use it, how it behaves (persistence), and how it relates to sibling tools. No critical information 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% for both parameters (key and value), including examples for key naming and value content. The description adds only the general framing of 'key-value pair' which is already evident from the schema. No additional parameter semantics are provided beyond the structured fields, so the baseline 3 applies.

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

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

The description uses a specific verb 'Save' and a clear resource ('data the agent will need to reuse later'), making the tool's primary function unambiguous. It also differentiates from siblings by explicitly pairing with 'recall' and 'forget', showing how this tool fits into the memory workflow.

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

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

The description provides explicit when-to-use guidance with concrete examples ('a resolved ticker, a target address, a user preference, a research subject'). It also names the complementary tools 'recall' and 'forget', explaining how they should be used together.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=true. The description adds valuable behavioral details: it explains that unresolved identifiers are explicitly listed under 'unresolved' rather than omitted, that LEI/FIGI enrichment degrades gracefully (EDGAR still returns even if GLEIF/OpenFIGI is unavailable), and that each call internally cascades through multiple endpoints. 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 front-loaded with example queries and the core instruction 'Use FIRST whenever you have a name but need an ID', then systematically covers supported types and behavioral notes. It is long but each sentence adds unique, non-redundant information. Minor room for tighter phrasing, but the structure serves clarity well.

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 two required parameters, no output schema, and all parameters documented in the schema, the description covers what to expect from the output (identifiers with source labels, unresolved list), graceful degradation, and internal complexity. It does not provide an example return object, but the remarks about 'unresolved' and source labels give enough context for an agent to understand the response structure.

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

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

Schema coverage is 100%, but the description significantly enriches both parameters. For 'type', it elaborates on what each entity type resolves to (e.g., company yields CIK, ticker, LEI, FIGI with source labels). For 'value', it provides concrete examples (AAPL, 0000320193, 'ozempic') and explains that ISINs resolve to legal entities via GLEIF. This goes well beyond the schema's brief descriptions.

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

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

The description opens with concrete user queries like 'What's the ticker for...' and 'find the CIK for...', immediately establishing the verb 'resolve' and resource 'name to identifiers'. It clearly distinguishes from sibling tools by stating that this is the tool to use when you have a name but need an ID, and lists two supported entity types with their resolution targets.

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 FIRST whenever you have a name but need an ID', providing clear guidance on when to invoke this tool. It also explains the inputs accepted (ticker, CIK, ISIN, name for company; brand/generic for drug) and hints at alternatives by noting that it replaces 2-3 manual lookups. However, it does not explicitly state when NOT to use it or list alternative tools for already-resolved IDs.

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

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

Annotations already declare readOnly, idempotent, and non-destructive hints, so safety is covered. The description adds behavioral context: that it 'probes each entity' (multiple API calls), 'ranks by score', and 'surfaces which is most/least recognized', plus details on the return format. This goes beyond 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?

Two sentences, front-loaded with the core function, followed by a use case and output summary. Every sentence provides value with no wasted words.

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

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

For an orchestration tool with no output schema, the description adequately explains the output (ranked list with score, confidence, signal density) and the method (probing with ai_visibility_check). It could mention that it makes multiple API calls or that models can be specified, but those are in the schema. Overall, it's complete enough 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%, with all four parameters described in the schema. The description does not add additional parameter semantics beyond what's already in the schema, such as the first entity being the 'subject' which is already documented. Baseline 3 applies.

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

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

The description clearly states a specific verb ('Compare') and resource ('AI visibility across multiple entities side-by-side'). It distinguishes itself from sibling tools by mentioning it probes with ai_visibility_check and ranks results, making it unique among the listed 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 a clear use case: 'competitive AI-marketing audits' with the example question 'does Claude know about us as well as our competitors?'. It implies it should be used for multi-entity comparison, and references ai_visibility_check, suggesting the alternative for single entities. However, it lacks explicit 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?

With annotations already declaring readOnly, openWorld, and idempotent behavior, the description adds valuable context: it discloses partial failure degradation, the 5-30s timeout risk for bundlephobia on first measurement, the 'sources_failed' field, and the fact that it fans out to multiple services. This goes beyond the annotations in a useful way.

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

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

The description is dense but well-structured, using an em dash to separate the main purpose from supporting details. Every clause contributes value, including return fields, ecosystem limitations, and failure behavior. It is somewhat long but each sentence is information-dense enough to warrant inclusion.

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 enumerates the full set of returned fields (summary block, per-advisory detail, links, alternative versions) and explains partial failure scenarios. It covers the tool's complexity, including the composite nature and latency considerations, making it complete for an agent deciding whether to call the tool.

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

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

Schema description coverage is 100%, with both parameters already described in the schema. The description adds minimal extra parameter semantics; it mentions 'package' is npm, but the schema already states that. The version behavior is also explained in the schema. Thus the description does not significantly enrich parameter understanding beyond the schema.

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

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

The description clearly identifies the tool as a composite 'should I add this npm package' check, naming specific upstream data sources (deps.dev and bundlephobia) and distinguishing it from sibling tools. It specifies the exact resource (npm package) and the type of analysis performed.

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

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

Explicitly states when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides an exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', which serves as a clear when-not-to-use guideline and points to an alternative.

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

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

Annotations already declare readOnly and idempotent, so the description adds valuable context beyond structured data: it specifies return contents (per-outcome implied probabilities in both OOM and USDC modes), the default status filter, and notes that no authentication is needed (keyless). These details paint a fuller behavioral picture without contradicting annotations, though pagination or error behavior not mentioned.

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

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

The description is two sentences: the first front-loads the core action, and the second adds key defaults and return details. Every piece of information earns its place, with no redundancy or fluff. It remains compact while covering the essential facts.

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

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

Given the tool complexity (4 params, no output schema, strong annotations), the description adequately covers the main purpose, default behavior, currency modes, and auth. It does not mention return structure in depth or alternatives, but for a read-only search tool with a rich schema, it is sufficiently complete. A minor gap is the lack of note about 'omit to browse' which is left to the schema.

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

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

Schema coverage is 100% (all 4 parameters described), so the description is not required to compensate. It does add context around currency modes ('play-money (OOM) and real-money (USDC)') which ties to 'currency_mode', but it doesn't introduce meaning beyond the schema's own detailed descriptions. Baseline 3 is appropriate.

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

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

The description clearly states a specific verb and resource: 'Search Futuur prediction markets by text', with a defined scope (politics, crypto, sports, science) and a default behavior (open markets). This distinguishes it from siblings like 'get_market' or 'top_markets' which are more specific or ranked, making the search intent explicit.

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

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

The description implies usage via 'Search ... by text' and mentions keyless access and default status, but does not explicitly contrast with alternative tools like 'top_markets' or 'get_market', nor does it state when not to use this tool. For a search tool, the context is clear but exclusions are absent, so it remains at the implied-usage level.

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 reveals substantial behavioral detail beyond annotations: it returns top-N passages with character offsets and similarity scores, uses BGE-base-en embeddings and cosine similarity over 500-char overlapping windows, and has a 200K character cap with truncation flagged. This gives the agent a clear model of what to expect. No contradiction with the readOnly/idempotent annotations.

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

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

The description is three sentences, each earning its place. The first sentence states the core function, the second gives the primary use case and return characteristics, and the third covers technical details and limits. There is no redundancy or fluff; the front-loaded phrase 'Semantic search INSIDE a fetched record' immediately conveys the 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?

The description covers the key aspects an agent needs: what it does, when to use it, what it returns (offsets, scores), how it works (embeddings, window size), and its limits (200K truncation). Since there is no output schema, the description compensates by summarizing the return structure. The guidance on pairing with ask_pipeworx_grounded also rounds out the usage context. This is complete for a tool of this complexity.

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

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

The input schema already provides 100% coverage with descriptions for all three parameters, so the baseline is 3. The description adds value by providing concrete examples of valid inputs (SEC 10-K body, article, natural-language query examples) and framing the text parameter as a 'fetched record,' which enriches the schema's bare description. This extra context justifies a score above baseline.

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

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

The description opens with 'Semantic search INSIDE a fetched record,' clearly specifying the verb (search) and the resource (a fetched record). It distinguishes itself from siblings like search_markets and ask_pipeworx by emphasizing that it operates on text already pulled by the agent, not on external market data or general queries.

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

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

The description explicitly states when to use the tool: 'Use when the record is too big to cram into the prompt.' It also provides a concrete integration pattern with ask_pipeworx_grounded, showing how to fetch then ground over passages, which clarifies the intended workflow relative to siblings.

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

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

Discloses auth requirements (anonymous/BYO cannot persist), per-type examples, SMS verification and cap, webhook signing and auto-disable after 10 failures. This goes well beyond the annotations, which only indicate readOnly=false, openWorld=true, idempotent=true.

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

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

Despite being long, the description is compact and front-loaded with the core purpose. Every clause adds either a requirement, a type example, or a delivery detail; no filler.

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

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

Covers return value, authentication needs, supported types with examples, delivery channels, SMS/email/webhook behavior, and a failure auto-disable rule. The absence of an output schema is sufficiently compensated by the explicit return value statement.

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

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

The input schema already provides 100% coverage of all parameters with detailed descriptions, including type-specific params and delivery formats. The description adds some interpretive value (e.g., 'items:["5.02"] = officer change') but mostly restates schema content, so 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?

Clearly states it creates a proactive monitoring subscription and returns the new subscription id. The description distinguishes it from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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 prerequisites (OAuth account) and mentions the always-on feed as an alternative retrieval mechanism ('pull via recent_alerts'). However, it doesn't explicitly contrast with other subscription management tools in detail, so it's slightly shy of ideal.

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 read-only and idempotent annotations, the description reveals key behavioral details: it returns category-bucketed questions drawn from a live catalog of thousands of tools, and that omitting arguments yields the full spread while passing topic focuses results. This adds meaningful context about output format and call behavior, though it does not describe any edge cases or size limitations.

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 ideal but well-structured: it opens with example queries, defines the output, then explains parameter usage and when to invoke. The list of categories is partially redundant with the schema, but every sentence contributes to understanding. It is not overly verbose and earns a 4.

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

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

For a simple tool with one optional parameter and no output schema, the description is complete: it explains the purpose, the return format, parameter semantics, and usage context. It also names related meta-tools, ensuring the agent knows where this tool fits within the broader tool ecosystem. No gaps remain.

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

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

The schema already provides 100% coverage for the single optional `topic` parameter, including an enumerated list of focus areas and guidance to omit for a cross-category spread. The description repeats this information with examples like 'finance', 'pharma', 'betting', adding minimal value beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states what the tool does: it returns category-bucketed example questions with the exact tool and argument shape needed to answer them. It positions itself as the onboarding entry point for new agents, distinguishing it from sibling tools like discover_tools and ask_pipeworx.

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

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

The description explicitly instructs to 'Use this FIRST' when the agent does not know what Pipeworx can do, and mentions learning to call meta-tools (ask_pipeworx, entity_profile, compare_entities) as a use case. It also explains the optional topic parameter for focusing. However, it does not explicitly state when NOT to use the tool or directly contrast with discover_tools.

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

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

Annotations already declare read-only and idempotent behavior. The description adds 'Keyless' (no authentication needed), which is valuable beyond annotations, and clarifies that both OOM play-money and USDC real-money probabilities are returned. This adds meaningful 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?

Two tightly written sentences: the first names the purpose and ranking, the second summarizes the return values. Every word earns its place, with no redundancy or fluff.

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

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

For a simple read-only list tool with two optional parameters and no output schema, the description adequately covers purpose, ranking logic, returned data (implied probabilities per currency), and authentication requirement. It is complete for the tool's complexity.

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

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

Schema coverage is 100% with descriptive parameter text. The description does not add new parameter-specific semantics beyond what the schema already states (limit, currency_mode). It echoes the ranking and currency emphasis but provides no additional syntax or edge-case details.

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

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

The description clearly states the tool lists most-active open Futuur markets ranked by trading volume and returns per-outcome implied probabilities. It distinguishes itself from siblings like get_market (single market) and search_markets (search) by focusing on the top-list aggregation.

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 that these are 'attention signal' markets, implying use for discovering trending markets. However, it does not explicitly mention alternatives or when-not-to-use scenarios, which prevents a 5.

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

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

The description discloses important behavior beyond annotations: ownership enforcement, row deactivation instead of deletion, and preservation of historical events. This clarifies the non-destructive nature (consistent with destructiveHint=false) and adds operational details that annotations alone do not provide.

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

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

The description is two sentences, starts with the core action, and every phrase adds value. It is appropriately sized for a simple tool with one parameter and no output schema.

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 (1 parameter, no output schema, clear annotations), the description is complete. It explains the action, side effects (deactivation), ownership constraints, and directs to a related tool for historical data, covering all necessary 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?

The schema fully covers the single 'id' parameter with a description noting it's a UUID returned by subscribe. The description merely says 'by id' without adding new details, so it does not enhance the schema's parameter semantics. Baseline 3 is appropriate given full schema coverage.

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

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

The description opens with 'Cancel a subscription by id,' which clearly states the action, resource, and parameter. It distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions' by focusing on the cancellation act, and the title 'Unsubscribe from Alerts' reinforces the scope.

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

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

The description provides clear context: you cancel by ID and ownership is enforced. It also mentions that historical events remain available via recent_alerts, implying an alternative for viewing history, though it does not explicitly state when to use this tool vs. alternatives. This is solid context without explicit exclusions.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses critical output semantics: it lists the verdicts and emphasizes that 'could_not_verify' means the check did not happen and must not be shown as evidence, while 'unsupported' means no source was found. It also reveals the two routing paths and that it replaces multiple sequential calls. This is substantive behavioral context 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 front-loaded with trigger phrases and organized into logical sections (purpose, routing, output, important caveats). It is somewhat lengthy and includes extra elaboration like 'Replaces 4–6 sequential calls' and detailed pipeline steps, which could be trimmed. However, the structure makes important points easy to find and no sentence is entirely wasted.

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

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

Since there is no output schema, the description fully compensates by specifying the return format: verdict options, actual value with pipeworx:// citation, and reasoning. It also covers the two distinct processing paths and clarifies the crucial difference between 'could_not_verify' and 'unsupported'. This is complete enough for an agent to invoke the tool correctly and interpret results.

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

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

The input schema already describes both parameters (claim and tolerance_pct) with 100% coverage. The description does not add additional parameter-level meaning beyond what the schema states, such as the tolerance range or its role in hallucination detection. Since schema coverage is high, the baseline of 3 is appropriate without extra semantic enrichment.

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

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

The description opens with natural-language trigger phrases and explicitly states 'natural-language claim verification against authoritative sources.' It specifies a structured SEC EDGAR path for company-financial claims and a grounded pipeline for any other factual claim, clearly distinguishing it from generic Q&A or research tools. This is a specific verb+resource+scope that differentiates it 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?

The description gives a clear usage condition: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains routing by claim type and notes it replaces 4–6 sequential calls, providing strong context. However, it does not explicitly name alternative tools or state when not to use this tool, so exclusion guidance is missing.

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