randomuser

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

Annotations indicate read-only, open-world, idempotent, non-destructive behavior. The description adds the important cost implication of passing _apiKey (you pay Anthropic directly) and specifies the return structure (per-model score, confidence, signals, raw_response). This goes beyond the annotations, though it doesn't disclose rate limits or potential delays.

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

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

The description is a single, information-dense paragraph that front-loads the core purpose and immediately provides the default behavior and output structure. Every clause adds value: purpose, score range, default model, BYO key, return format, and use cases. No fluff.

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

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

Even without an output schema, the description explains the return shape (per-model {score, confidence, signals, raw_response} + combined view) and typical use cases. It covers the key decisions (which models, how to authenticate) and the cost implication. Minor details like what 'signals' include are omitted but not essential for initial selection.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds valuable context beyond the schema by explaining that the default model is free and that _apiKey is used to enable Anthropic calls with direct billing. This enriches the meaning of the 'models' and '_apiKey' parameters without redundancy.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and scores visibility (0-100). It uses a specific verb ('probe'), names the resource ('LLMs'), and defines the output metric. This distinguishes it from sibling tools like ask_pipeworx or deep_research by focusing on AI visibility scoring.

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

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

The description explicitly lists use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It also explains the default model and the BYO-key option for Anthropic. While it doesn't state when not to use it or name alternatives, the use cases are clear and actionable.

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

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

Adds significant context beyond annotations: routes internally, fills arguments, returns pipeworx:// citation URIs, works on every tier, one fast call. Never contradicts readOnly/openWorld/idempotent hints.

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

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

Long but purposeful; every sentence adds value (use cases, examples, sibling differentiation). Front-loaded with 'PREFER OVER WEB SEARCH' and structured to be scannable.

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

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

Comprehensive for a complex routing tool: covers when to use, what it returns, how it differs from alternatives, and even handles breaking news. No output schema, but description explains return format adequately.

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

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

Input schema has 100% coverage with descriptions for all parameters. The description adds examples of natural language queries but no additional parameter semantics beyond what the schema already documents.

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

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

Clearly states the tool routes questions to 5,564 tools and returns structured answers with citations. Distinguishes itself from web search and sibling tools like ask_pipeworx_grounded and deep_research with explicit comparisons.

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

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

Provides explicit guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and specifies when to escalate to alternatives (grounded for verbatim evidence, deep_research for multi-part questions). Includes triggers and examples.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds crucial context: that this is a beta with candidate routing improvements that change live, and that no candidate is active now so it matches stable. This dynamic behavior is beyond the annotations and fully disclosed.

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

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

The description is a single paragraph of about 150 words with each sentence providing distinct value: beta status, current state, usage instruction, and reassurance of functionality. It's slightly longer than necessary but efficiently front-loaded with the core purpose.

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

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

For a simple tool with one required parameter and no output schema, the description fully covers what the agent needs: what it does, current behavior, when to use, and its relationship to the stable counterpart. It is complete and self-sufficient.

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

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

The schema has 100% coverage of all 6 parameters (all aliases for question) with clear descriptions. The description adds no additional parameter-specific meaning, but since the schema carries the full burden, the baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router that routes questions to 5,564 tools. It explicitly distinguishes itself from the sibling ask_pipeworx by noting it's the experimental edge, and from ask_pipeworx_grounded by referencing only the stable counterpart.

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

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

It provides explicit when-to-use guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also clarifies that it's a full working router, not a fallback, and implies the stable version is preferred for production use by contrasting with the comparative merge process.

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

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

The description goes well beyond the annotations by disclosing the exact output contract ({answer, evidence, confidence, source, fetched_at, refusal_reason}) and enumerating all refusal reasons. It also reveals cost behavior (costs one extra LLM call) and the constraint that answers are derived strictly from tool results. 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 a compact paragraph where every sentence adds functional value: purpose, routing, output format, refusal behavior, usage triggers, and cost comparison. It is front-loaded with the core value proposition and contains zero filler or repetition of schema 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?

Despite lacking an output schema, the description fully explains return values and failure modes, including structured refusal reasons. It also covers routing complexity (5,564 tools), source span, and cost implications, making the tool's behavior predictable in a wide range of scenarios.

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

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

The schema already fully documents the single question parameter and all its aliases (100% coverage), so the description doesn't need to add parameter details. It provides no additional field-level semantics beyond what the schema states, but the context explains how the question is used, keeping it at the baseline 3 for fully-schema-covered params.

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 'hallucination-resistant answer mode' for high-stakes reads, with a specific verb and resource ('EXTRACTS the answer using ONLY what the tool result contains'). It distinguishes itself from sibling ask_pipeworx by highlighting the grounded extraction and explicit refusal behavior, making its unique purpose unmistakable.

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

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

The description explicitly states when to use this tool ('whenever an answer will be quoted, cited, or acted on... must not invent facts') and when not to ('prefer ask_pipeworx for casual lookups'). It also names the direct alternative (ask_pipeworx) and clarifies the trade-off (one extra LLM call), giving the agent clear decision criteria.

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 details fan-out in parallel, response shapes, resolver contract (market_match_confidence, alternatives, suggestions), safety short-circuits (status:"low_confidence_match", "market_closed_or_inactive"), wide-spread tradeability, and resolution-rule risk categories. This goes far beyond 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 long but structured with headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and every section provides operational detail. It is front-loaded with purpose and use cases. Given the tool's complexity, the length is justified.

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

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

No output schema exists, so the description must explain return values — it does so in detail (result.market, result.analysis, result.evidence, parent_event). It also covers edge cases like low-confidence matches, closed markets, wide spreads, and cancellation rules, making it complete for a complex research 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?

Input schema covers 100% of parameters (market, depth, include_raw) with descriptions. The description adds examples of accepted market formats and fan-out examples, but these are already implied by the schema. No major semantic gaps.

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') and lists clear use cases ('should I bet on X'). It distinguishes itself from siblings like polymarket_arbitrage and polymarket_edges by focusing on per-bet research with data fan-out.

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

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

It explicitly states when to use: 'Use for "should I bet on X"...' and provides guidance on inspection ('ALWAYS inspect these before trusting the analysis block'). It lacks explicit exclusions or alternative tool references, so it doesn't reach a 5, but the context is clear.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description discloses data sources (SEC EDGAR/XBRL for company, FAERS/FDA for drug), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs in output. 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 front-loaded with trigger phrases, then details behavior and output. Every sentence adds value—no fluff—and it is well-structured for an agent to parse quickly.

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

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

Given no output schema, the description explains return format (paired data + citation URIs) and sorting behavior. It covers both entity types, data sources, edge cases, and the value proposition (replaces many sequential lookups), making it nearly complete 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 covers 100% of parameters with descriptions, but the description adds significant meaning: type determines which data source is pulled, and values are tickers/CIKs or drug names with examples. It enriches the otherwise minimal schema descriptions.

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

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

The description clearly states the tool compares 2–5 companies or drugs side-by-side in one parallel call, with specific trigger phrases and a clear verb+resource+scope. It distinguishes from siblings by explicitly noting it replaces sequential single-pack lookups, and from entity_profile which is likely a single-entity 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?

Description gives explicit when-to-use triggers ('Compare X and Y', 'X vs Y', 'rank these companies') and states ALWAYS PREFER over sequential single-pack lookups when comparing entities. It lacks an explicit 'do not use for single entity' exclusion, but the context is clear enough.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description discloses account/paywall requirements, parallel routing to 5,564 tools, the findings packet structure (evidence, confidence, source, fetched_at, citations), gaps[] and 'never invented' guarantee, contradictions[] for deeper modes, semantic excerpting, and latency expectations. This is far richer behavioral context than annotations alone.

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

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

The description is long but front-loaded with the critical account prerequisite and core purpose, then organizes details about alternatives, depth modes, citations, and timing in a logical flow. While verbose, every sentence contributes meaningful information for a complex tool; it could be tightened slightly, but it is not wasteful.

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 explains the return packet, gap and contradiction semantics, citation resolvability, and performance trade-offs. It also covers authentication prerequisites, excluded use cases, and the behavior of different depth levels, making it complete for a research 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%, and the schema already documents both parameters thoroughly (question support for broad/multi-part, depth enum with quick/standard/thorough semantics). The description's parameter references essentially mirror the schema without adding new meaning, 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 clearly states the tool performs 'Grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources' in one call, explicitly distinguishing it from open-web search. It also differentiates from sibling ask_pipeworx for single lookups, making the purpose 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 provides explicit when-to-use and when-not-to-use guidance: 'If you are not signed in, use ask_pipeworx instead', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It even explains the failure mode of empty gaps[] for non-structured topics, giving clear 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 mark the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context: it returns top-N tools with names, descriptions, and full input schemas with curated examples, ready to call directly without a second schema lookup, and it emphasizes a first-step workflow. It does not address rate limits or edge cases, but goes 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 four sentences, front-loaded with the primary purpose, and each sentence earns its place: use-case list, return behavior, and workflow guidance. The domain list is long but directly relevant; 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?

There is no output schema, so the description carries the burden of explaining return values—it does so clearly: top-N relevant tools with names, descriptions, full schemas, and examples. The compound parameters are fully covered by the schema, and annotations handle safety. It lacks only explicit ranking/sorting details, but overall it is complete enough for an agent to select and invoke correctly.

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

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

Schema description coverage is 100%, with all params clearly documented including aliases and defaults. The description confirms that 'query' is a natural-language task description but does not add meaning beyond the schema, 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 clearly states a specific verb-resource relationship: 'Find tools by describing the data or task.' It enumerates the domains it covers and explicitly frames the tool as a discovery/browse/search mechanism, distinguishing it from domain-specific sibling tools like search_within or entity_profile.

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

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

The description provides explicit use cases ('browse, search, look up, or discover') and a directive to 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It does not name specific alternative tools or offer a formal when-not-to-use list, 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 readOnly/openWorld/idempotent, so description only needs to add behavioral specifics. It reveals fan-out across multiple sources, output structure, soft-fail behavior for patents, GDELT→GNews fallback, and the unsupported name input. This exceeds 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?

Description is dense but front-loaded with query examples and a one-line core statement. Every sentence adds specification (sources, output fields, fallbacks), though it runs long; still 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?

With no output schema, the description fully enumerates return fields (cik, filings with URIs, fundamentals sorted, patents, news fallback, LEI). It covers edge cases (names not supported) and fallback behavior. Given complexity, description is complete.

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

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

Schema covers both parameters fully (type enum with description, value with ticker/CIK and name caveat). Description largely restates the value parameter's zero-padded CIK and name limitation, adding no new semantics beyond a concrete example. Since coverage is 100%, baseline 3 applies.

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

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

Description begins with concrete user utterances and explicitly states the tool produces a full cross-source profile of a US public company in one parallel call. It distinguishes from sibling tools by instructing to prefer it 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?

Explicitly states when to use: ALWAYS PREFER for holistic views; also directs users to resolve_entity if only a name is provided. Provides clear exclusions (names not supported) 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 destructiveHint=true and readOnlyHint=false, covering the mutation and destructive nature. The description adds minimal behavioral context beyond the literal delete action; it mentions 'previously stored' but no details on irreversible effects or error handling. The low additional value is acceptable given annotation coverage.

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, with two sentences that front-load the purpose and then provide usage guidance. Every sentence contributes meaning, with no filler or repetition.

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

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

For a simple single-parameter destructive tool, the description covers purpose, usage context, and relationships to sibling tools. Annotations provide the destructive and idempotent hints. It lacks details on edge cases (e.g., missing key) but these are not critical given the low 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 schema has 100% coverage with a clear description for the 'key' parameter ('Memory key to delete'), and the example 'user_research_topic' adds concrete meaning. The description's mention of 'by key' is a redundant restatement, adding no significant extra semantic value.

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

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

The description clearly states the tool deletes a previously stored memory by key, using the specific verb 'Delete' and resource 'memory'. It effectively distinguishes from siblings by contrasting deletion with remembering and recalling.

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

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

The description provides explicit use cases ('when context is stale, the task is done, or you want to clear sensitive data') and mentions related tools (remember and recall). However, it stops short of explicit when-not guidance or direct alternative selection.

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

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

With annotations providing readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, the safety profile is already clear. The description adds behavioral context by noting the randomness of profiles and the return payload (names, contact info, photos, demographics), which exceeds the annotations' coverage. No contradiction with annotations; 'generate' here is read-only in the sense of producing fictional data without modifying state.

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

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

The description is two sentences, front-loaded with the main action, and every word adds value. It succinctly covers purpose, return contents, and the multiple-profile option without redundancy.

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

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

The tool is simple, has full schema coverage, an output schema present, and rich annotations. The description sufficiently covers the core behavior, and no additional context (like prerequisites or exceptions) is necessary for an agent to select and invoke this tool correctly.

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

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

The input schema has 100% coverage for both parameters, including default and max for 'count' and allowed values for 'gender'. The description restates the count use case and gender values but adds no new meaning beyond what the schema already specifies, so baseline 3 is appropriate.

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

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

The description uses a specific verb ('Generate') and resource ('random user profiles'), clearly scoped by gender. It distinguishes itself from sibling tool 'generate_users' by explicitly narrowing to gender filtering, 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 clearly indicates usage for generating gender-specific profiles and mentions the count parameter. However, it does not explicitly contrast with sibling tools like 'generate_users' or state when not to use this tool, so it lacks explicit exclusions/alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavior context: it fetches the page, extracts specific elements, and returns a single text blob ready for deployment. 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?

The description is compact and well-structured. The first sentence states the core purpose and audience, the second explains the process and output, and the final clause lists concrete use cases. Every sentence earns its place; there is no redundant or vague 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 tool with only two parameters and no output schema, the description provides sufficient contextual coverage: it explains the input (URL), the optional parameter (max_links is implied by the schema but not described), the transformation process, and the exact output shape ('single text blob'). It also addresses practical use cases. The lack of an output schema is mitigated by the explicit description of the return format.

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

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

Schema description coverage is 100% for both parameters, so the baseline is 3. The description reinforces the 'url' parameter by mentioning 'for any URL' but does not add new semantic details beyond the schema. The 'max_links' parameter is not referenced in the description, but the schema already explains it adequately.

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

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

The description clearly states the tool's specific function: generating an llms.txt file for a given URL. It names the exact output format (standard llms.txt markdown) and the process (fetch, extract, emit). This distinguishes it from all sibling tools, which cover different research or subscription tasks.

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

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

The description provides clear use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'). It does not explicitly mention alternatives or exclusions, but the application contexts are well-defined, satisfying the 'clear context' threshold.

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 behavioral context beyond annotations by stating the profiles are 'random' and that filtering by nationality and specifying count are supported. This complements the readOnlyHint and idempotentHint annotations without contradicting them, though it doesn't detail rate limits or response size.

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

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

The description is a single, efficient sentence that conveys the core functionality, parameters, and examples. Every phrase earns its place with no redundant content.

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

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

With annotations, a complete input schema, and an output schema present, the description covers all necessary operational context. It is sufficient for an agent to select and invoke the tool correctly without exceeding its concise length.

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 count and nationality already fully documented. The description essentially restates what the schema says (e.g., examples like 'US', 'GB', 'AU'), adding no new parameter semantics beyond the schema's own descriptions.

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

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

The description clearly states the tool's purpose: 'Generate random user profiles' with specific data fields (names, addresses, emails, photos). It also specifies the key operations (filter by nationality, specify count), making it distinct from siblings like generate_by_gender.

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

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

The description implies when to use the tool (when random profiles with nationality filters are needed) but provides no explicit exclusions or alternatives. Given the sibling tool generate_by_gender exists, it does not clarify when to choose this over that 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 read-only, idempotent, and non-destructive behavior. The description adds context beyond annotations by scoping to the caller's subscriptions and listing the exact returned fields (id, type, params, created_at, last_fired_at, fire_count). It does not mention pagination or ordering, which are possible minor gaps for a list tool, but the provided information is still valuable.

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 redundancy. The first sentence states the action and return fields, the second provides usage context. It is well-structured, front-loaded, and every phrase earns its place.

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

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

For a simple list tool with one optional parameter, strong annotations, and no output schema, the description covers all key aspects: what it does, what it returns, and when to use it. The listing of return fields compensates for the absence of an output schema, making the tool fully understandable.

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 documents the sole parameter 'include_inactive' with a clear description (100% coverage). The tool description does not add additional meaning to the parameter, and none is needed since the schema already explains the behavior. This aligns with the baseline of 3 for high schema coverage.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource. It distinguishes from sibling tools like 'subscribe' and 'unsubscribe' by focusing on the review/listing use case. The enumerating of return fields further clarifies the tool's purpose.

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

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

The description explicitly provides usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This directly tells the agent when to invoke this tool relative to adding (subscribe) or removing (unsubscribe) subscriptions, making the workflow context 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?

The annotations only indicate non-read-only behavior, but the description adds substantial behavioral context: the claim_token flow for anonymous filing, the need to pass it later as a follow-up, rate limits (5 per identifier per day), free usage, and content policies (don't paste end-user prompt). This goes well beyond what the annotations offer.

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

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

The description is front-loaded with purpose and use cases, and every sentence carries operational information: scope, content guidance, claim_token flow, team digest, rate limit, and free usage. It is longer than minimal but justified by the tool's complexity, though it could be slightly tightened to improve readability.

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 fully covers the asynchronous claim_token follow-up, rate limiting, scope boundaries, and content instructions. It also clarifies the feedback types and alternatives, leaving no critical gaps for an agent to 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?

The schema already covers all 4 parameters with 100% described coverage, providing a solid baseline. The description adds value by explaining how to use claim_token as a standalone follow-up argument and by advising message content (describe in terms of Pipeworx tools/packs), but it does not systematically elaborate on every parameter since the schema already does.

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 ('Tell the Pipeworx team') and enumerates the feedback types (broken, missing, needs to exist). It clearly distinguishes the tool from sibling tools like ask_pipeworx or discover_tools by positioning it as a reporting channel for Pipeworx tool issues.

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 the tool: for bugs (wrong/stale data), feature requests/data gaps, and praise. It also provides a clear exclusion for tools from other MCP servers, instructing the agent to file with that server instead, which prevents misuse.

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, idempotentHint), the description adds valuable behavioral context: it is a 'self-aggregating signal derived from CF analytics-engine', guarantees 'no PII', and discloses caching behavior ('Cached 5min-1h depending on window'). It also clarifies the output structure as '(pack, tool, count)', which is useful given no output schema.

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

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

The description is well-structured and front-loaded: the main purpose is stated in the first sentence, followed by concrete return values, use cases, and then behavior/data provenance. Every sentence earns its place, with no redundancy or fluff. The numbered use-case list is compact and easy to scan.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description is comprehensive. It explains what the tool returns, why it's useful, how it derives data, privacy guarantees, and caching behavior. No critical context is missing for an agent to decide whether and how to invoke it.

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

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

The schema already covers the window parameter at 100% with an enum and description, but the tool description adds extra meaning by linking the window to caching time ('Cached 5min-1h depending on window') and reinforcing the semantic distinction between shorter and longer windows. This goes beyond the schema's generic description.

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

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

The description clearly states the tool's function: 'What other AI agents are calling on Pipeworx right now' and specifies the outputs: 'top tools, top packs, and total call volume'. It distinguishes itself from siblings like discover_tools by focusing on aggregated usage trends rather than tool discovery, making it a specific verb+resource+scope definition.

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: 'discovering what data sources are hot for current events', 'confirming a popular tool is the canonical choice', and 'seeing whether your use case aligns with what most agents need'. While it does not name alternative tools or state when not to use it, the contextual guidance is clear and actionable.

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

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

Annotations already mark the tool as read-only, open-world, and idempotent, but the description goes far beyond them by detailing exact behavioral thresholds (3pp deviation, 0.30 Jaccard, 20% placeholder cutoff), the partition-check logic, placeholder filtering, and the fill-check procedure against live CLOB depth. This is rich, non-obvious behavioral context with no contradiction to annotations.

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

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

The description is long but exceptionally well-organized: it front-loads the core purpose, then uses labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, RESPONSE, FILL CHECK) to pack complex behavioral rules into scannable chunks. Every sentence adds operational value, and the examples make the modes immediately understandable.

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 two optional parameters and no output schema, this description is remarkably complete. It covers all invocation modes, output field names, filtering behavior, failure conditions, fill-check semantics, and even points to a sibling tool for custom sizing. An agent can select and invoke this tool correctly without any additional documentation.

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

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

Although the schema already describes both parameters, the description adds substantial meaning: it explains that no args triggers a trending scan, gives concrete example slugs and seed questions for 'event' and 'topic', and describes what each mode does internally ('walks child markets', 'flattens markets'), which is far beyond the schema's basic field descriptions.

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

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

The description opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes the tool from siblings by describing single-event and cross-event modes, and it even references polymarket_fill_risk for custom sizing, helping separate it from related 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 explicit when-to-use guidance for all invocation patterns: no args ('trending_scan'), 'event' (recommended for a specific market), and 'topic' (for cross-event scanning). It explains when cross-event mode is preferable and even includes a concrete do-not-trade instruction for when realizable edge is non-positive.

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 substantial behavioral detail: the FIVE MODEL FAMILIES and their statistical basis, the 'placeholder-slug filter', the '24h-move warning', diagnostics for why a segment is empty, and KV-level caching ('Cached 1h at the KV level keyed on all knobs'). It also explains why Fed bets are excluded, providing deep insight into the tool's decision-making.

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

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

The description is long but well-structured into segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and top-level categories. It front-loads the core purpose and then packs in necessary detail. A few redundancies with the schema exist, but every sentence carries unique behavioral or usage information; it 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 tool with 9 parameters, no output schema, and rich internal logic, the description is remarkably complete. It specifies the response top-level structure (by_segment, fed_candidates, _diagnostics), explains why segments can be empty, defines all relevant edge metrics (edge_pp_net, kelly_fraction, liquidity), and notes the 1-hour cache. This fully equips an agent to interpret results and adjust behavior.

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

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

The input schema has 100% parameter description coverage with detailed per-parameter explanations (e.g., slippage_pp explains Polymarket fees and spread rationale). The tool description mostly reiterates these in prose (e.g., 'TRADEABLE-EDGE KNOBS') without adding significant new meaning, so it meets the baseline 3 but does not exceed it.

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

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

The description opens with a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also frames the use case as 'what should I bet on today', clearly distinguishing this from sibling tools like polymarket_arbitrage or polymarket_fill_risk by focusing on quick opportunity discovery.

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: 'Built for what should I bet on today — agents discover opportunities without paging hundreds of markets.' It also explains the purpose of adjustable knobs (e.g., min_liquidity, max_spread_pp) and how they filter opportunities, providing clear context. However, it does not explicitly mention alternatives or when NOT to use this tool, so it stops short of a 5.

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

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

The description adds substantial behavioral detail beyond the annotations: snapshots are only written on cache-miss, gaps in snapshot_dates mean no scan occurred, history is bounded by a 60-day TTL, and decay is computed from daily closes (not intraday). It also clarifies that edge_pp_net is signed by trade direction, which is critical for interpretation. These nuances are not captured in the readOnly/openWorld/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 dense but well-organized with ARGS, RESPONSE, and LIMITS sections. Every sentence contributes either to usage, output semantics, or edge cases. The front-loaded purpose sentence immediately communicates the tool's niche. Despite its length, it avoids fluff and uses a clear structure that an agent can parse.

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

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

Given there is no output schema, the description fully compensates by explaining the response structure (tracked, expired, snapshot_dates) and each field's semantic meaning (e.g., trend categories, median lifespan as 'competition clock'). It also covers important context like data gaps and TTL limits. The description is complete enough for an agent to understand what results to expect and how to interpret them.

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 covers both parameters with descriptions (100% coverage), so baseline is 3. The description adds value by giving defaults (days default 14, window default '1wk'), constraints (days max 30, clamp 2-30), and clarifying that window selects the 'snapshot family' from polymarket_edges. This helps the agent choose sensible values without needing external knowledge.

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 resource ('polymarket_edges snapshots') and the specific analytical goal ('edge persistence and decay telemetry'). It answers the exact questions the tool addresses ('how long has this edge existed and is it shrinking?'), which is a sharp contrast to sibling tools like polymarket_edges that likely focus on current edge computation.

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 this tool by framing it around edge age and decay, and explicitly differentiates from fresh edges ('a fresh wide edge and a 3-week-old wide edge are different trades'). It does not explicitly name sibling alternatives, but the context signals (e.g., polymarket_edges sibling) make the use case clear. The LIMITS section also gives practical constraints on when results are valid.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses behavior like walking the order-book ladder, returning a verdict, and identifying thin legs and forced directional risk. It warns of the dominant loss mode (partial basket fills) without prompting, adding significant context.

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

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

The description is a single dense paragraph but logically structured with mode markers (SINGLE-MARKET/BASKET) and uses uppercase for critical usage guidance. It's verbose, but every sentence carries information; only minor trimming could be done without loss.

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 two modes and no output schema, the description thoroughly enumerates return fields (top_of_book, vwap_fill_price, thin_legs, etc.) and explains their meaning. It also covers edge cases like forced directional risk and max_clean_notional_usd, making it complete for an agent invoking 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 documents all parameters, but the description adds deeper semantics: it explains the 'REQUIRES one of market or event' constraint, clarifies side defaults in basket mode, and defines size_usd differently for single-market vs basket (spend vs settlement notional). This goes well beyond the raw 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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes single-market and basket modes, and the call to 'USE THIS before acting on any polymarket_arbitrage...' differentiates it 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?

Explicit when-to-use guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the risk of not using it (partial fills leading to unhedged directional positions), implicitly covering when-not-to-use for smaller trades.

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/idempotent annotations, the description discloses critical limitations: compatibility_warning conditions, temporal_alignment semantics, and skipped_cross_type/subtype counters. It proactively warns that 'most pre-mapped topics return compatibility_warning today,' which is essential context for trusting the output.

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

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

The description is long but well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and every sentence adds value. It could be slightly more concise, but the complexity of the tool justifies the detail.

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

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

With no output schema, the description fully specifies the response shape (leg-by-leg prices, spread[].top_spreads_pp) and explains all warning/counter semantics, including temporal alignment. No important behavior 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?

The schema already covers all parameters with descriptions and examples, but the description adds the mode logic and explicit topic list, reinforcing override semantics. It doesn't add significantly more beyond the schema, yet the two-mode explanation is a helpful synthesis.

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 opening sentence precisely defines the tool: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It names both venues and the core function, and contrasts it with siblings by focusing on cross-venue comparison and bet-shape equivalence.

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

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

The description clearly explains two modes (topic shortcuts vs explicit ticker/slug) and gives strong when-not guidance via compatibility_warning and the final warning 'pre-mapped ≠ tradeable.' However, it does not explicitly name alternative sibling tools for single-venue analysis, 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, idempotentHint, and destructiveHint, covering safety. The description adds meaningful context about scoping ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the dual behavior (retrieve vs list), going beyond the annotations without contradicting them.

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

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

Three sentences with no fluff: the first states the action, the second gives use cases, the third provides scoping and sibling pairing. All content earns its place and the main action is front-loaded.

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

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

For a simple 1-parameter read tool with rich annotations and full schema coverage, the description covers usage, scoping, and relationship to siblings. It does not detail the return format for listing keys or missing-key behavior, but given the tool's simplicity, this is a minor gap rather than a critical omission.

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

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

Schema coverage is 100%, but the description enriches understanding by explaining the key's purpose with concrete examples ('the user's target ticker, an address, prior research notes') and reinforcing the omit-to-list behavior. This adds value beyond the basic schema description.

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

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

The description clearly states the tool retrieves a value saved via remember or lists all keys when the key is omitted. It uses specific verbs ('Retrieve', 'list') and distinguishes from sibling tools like remember and forget, making its role 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?

Explicitly describes when to use the tool ('to look up context the agent stored earlier... without re-deriving it from scratch') and how it relates to siblings ('Pair with remember to save, forget to delete'). This provides clear contextual guidance.

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

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

The description contradicts the annotations: readOnlyHint=true and idempotentHint=true are undermined by mark_read:true, which explicitly modifies state (flags events as read) and makes repeated calls non-idempotent. This is a serious inconsistency.

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, front-loaded with the primary purpose, and every sentence adds meaningful detail. No redundant or vague wording.

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

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

Given no output schema, the description adequately covers return payload structure (source, citation_uri, raw event). It also covers filtering, side-effect, and alternative access. Minor gaps: doesn't mention limit behavior or unread_only explicitly, but those are in the schema.

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

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

Schema coverage is 100%, but description adds valuable semantics: explains filtering with examples (type='sec_8k', ISO timestamp) and clarifies the effect of mark_read. This enriches the parameter documentation beyond the schema.

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

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

The description clearly states the tool pulls fired events from the user's subscription feed, with a specific verb and resource. It distinguishes itself from siblings by focusing on alerts/persisted feed data, which no sibling tool addresses directly.

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: mentions polling suitability and gives an alternative HTTP endpoint for scripts/dashboards. However, it does not explicitly exclude alternative tools or list when-not-to-use scenarios, 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 indicate readOnly/openWorld/idempotent behavior, and the description adds substantial context: fan-out to SEC/GDELT/USPTO, fallback triggers, the USPTO soft-fail due to PatentsView sunset, and the return shape. This goes beyond annotation hints and aligns with them.

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

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

The description is dense but logically organized: query patterns lead off, followed by data sources, parameter formats, return structure, and the alternative tool. Every sentence contributes needed information, and it remains a single focused paragraph.

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 specifies the return structure (changes[], total_changes, citation URIs), covers parameter variations, and addresses edge cases like rate limits and USPTO unavailability. An agent can invoke the tool with confidence.

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

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

Schema coverage is 100%, and the description repeats the same parameter details already present in the schema (ISO/relative formats for since, ticker/CIK for value). No additional parameter-level meaning is introduced, 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 clearly states the tool's purpose: a change feed for a company over a time window, with query examples like 'What's new with X' and 'updates on Acme.' It explicitly differentiates itself from entity_profile by contrasting dynamic changes versus static profile.

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

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

Provides explicit guidance on when to use the tool versus alternatives, naming entity_profile as the static-profile alternative. It also explains fallback behavior (GDELT→GNews) and the 'since' window formats, making usage conditions unambiguous.

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 valuable behavioral context beyond annotations: it explains that memory is scoped by the agent's identifier, and details persistence differences between authenticated (persistent) and anonymous (24-hour) sessions. This complements the idempotentHint and readOnlyHint without contradiction.

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

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

The description is three sentences, with the first sentence front-loading the core action and scope. Every sentence earns its place: purpose, usage examples, and storage/persistence details—no fluff or repetition.

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

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

For a simple two-parameter tool with no output schema, the description fully covers purpose, usage timing, storage model, scoping, retention, and sibling tools. It is complete enough for an agent to select and invoke without additional clarification.

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

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

Even though the input schema has 100% coverage with descriptions for both parameters, the description enriches semantics by providing real-world examples of appropriate keys and values, and the phrase 'scoped by your identifier' clarifies namespacing. This elevates it above the baseline.

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

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

The description clearly states the tool saves data for later reuse across conversations or sessions, using specific verbs and a defined resource (key-value store). It distinguishes itself from sibling tools by explicitly positioning itself as the save counterpart to recall (retrieve) and forget (delete).

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

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

The description explicitly says 'Use when you discover something worth carrying forward' with concrete examples (resolved ticker, target address, user preference). It also names the related tools recall and forget, giving clear when-to-use and pairing 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 declare readOnlyHint, idempotentHint, and destructiveHint=false, which already set expectations. The description goes well beyond this by disclosing that the tool cascades through multiple endpoints internally, degrades gracefully (if GLEIF/OpenFIGI fail, EDGAR identifiers still return), and explicitly mentions that unresolved identifiers are stated under 'unresolved' rather than omitted. These behavioral details are critical for an agent to understand failure modes and result structure, and they do not contradict the annotations.

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

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

The description is front-loaded with relatable examples, which is good. It is relatively long but each sentence adds value (e.g., graceful degradation, source labeling, replacement of manual lookups). Minor redundancy exists (e.g., 'SUPPORTED TYPES' is repeated in the text). Could be slightly trimmed without losing clarity, but overall efficiently packed for the complexity.

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

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

With no output schema, the description bears full responsibility for explaining return values. It does so thoroughly: for company type, it enumerates CIK, ticker, LEI, FIGI with source labels; for drug, RxCUI and ingredient/brand. It also explains the 'unresolved' field and the graceful degradation behavior. The two parameters are fully explained. For a tool that replaces multiple manual lookups, this completeness is excellent and leaves no 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?

Input schema has 100% description coverage, so the baseline is 3. However, the description adds substantial meaning: for the 'company' type, it explains input formats (ticker, CIK, ISIN, company name) and what identifiers are returned (CIK, LEI, FIGI with sources); for 'drug', it specifies RxCUI, ingredient, brand. Concrete examples ('AAPL', '0000320193', 'ozempic') clarify parameter usage beyond the schema's terse descriptions. This extra context greatly aids correct invocation.

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

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

The description starts with concrete user queries ('What's the ticker for…') and states the core purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It explicitly says 'Use FIRST whenever you have a name but need an ID,' which differentiates it from sibling tools like entity_profile that work with existing IDs. The supported types (company, drug) are clearly enumerated, making the tool's scope unmistakable.

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

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

The description provides clear usage guidance: 'Use FIRST whenever you have a name but need an ID.' It gives example queries that signal appropriate scenarios. It does not explicitly state when not to use it (e.g., when you already have an ID), but the phrasing 'Use FIRST' and the nature of the tool implicitly discourage unnecessary use. It also notes that it replaces 2-3 manual lookups, which helps the agent prioritize efficiency.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds meaningful behavioral context beyond annotations: it reveals that the tool internally calls ai_visibility_check per entity, ranks results, and returns a ranked list with score, confidence, and signal density. This is useful procedural 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 three sentences, front-loaded with the core comparison purpose, followed by a concrete use-case example and a clear summary of return contents. No wasted words; every sentence earns its place.

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

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

The tool has moderate complexity (4 params, 1 required) and no output schema, so the description's mention of the ranked list fields (score, confidence, signal density) is sufficient to set expectations. It could further clarify edge cases or error behavior, but the current text is adequate for an agent 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 input schema already documents all parameters (entities, models, _apiKey, context). The description adds no parameter-specific meaning beyond what the schema provides—it mentions entities, competitors, and the first-entity-as-subject convention, but these are already in 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 opens with a specific verb+resource: "Compare AI visibility across multiple entities side-by-side," which clearly distinguishes it from the sibling single-entity tool ai_visibility_check. It also states the outcome (ranks by score, surfaces most/least recognized), fully covering purpose.

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

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

The description provides a clear use case: competitive AI-marketing audits with a concrete example question. It implies this tool is for multi-entity comparisons and mentions probing with ai_visibility_check, but it doesn't explicitly state when NOT to use it or name alternative tools for single-entity checks. Clear context, but no formal 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?

Discloses partial failure degradation, a potential 5-30s latency on first bundlephobia measurement, and the sources_failed field, which enriches the readOnlyHint and idempotentHint annotations with concrete operational behavior 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?

Front-loaded with a concise purpose, then usage, return block fields, ecosystem exclusions, and failure behavior in a dense but well-organized sequence. Every sentence contributes information, with no fluff or redundancy.

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

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

With no output schema, the description enumerates the exact return composition: summary block fields, per-advisory detail, links, and recent alternative versions. It also covers operational caveats, making it complete for an agent to interpret and act on 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%: both package and version have clear descriptions including scoped package acceptance and default-to-latest behavior. The description adds no extra parameter meaning beyond the schema, so the baseline 3 applies.

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

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

The description opens with a specific composite check for npm packages, enumerating deps.dev outputs (license, advisories, version history) and bundlephobia outputs (bundle size, dependency count, ESM/tree-shake support). This verb+resource formulation clearly distinguishes it from siblings like scan_competitor_ai_presence or bet_research.

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

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

It explicitly states when to 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, with PyPI/Maven/Cargo/Go routed directly to deps.dev:version, giving clear selection guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description goes beyond by disclosing specific behaviors: returns character offsets and similarity scores, uses BGE-base-en embeddings with cosine over 500-char overlapping windows, has a 200K char cap, and truncation is flagged. This adds valuable operational context without contradicting any 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 information-dense but well-structured: opening with core purpose, then use case, pairing, and technical details. Every sentence earns its place; there is no redundant or vague filler. Appropriate length 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?

Despite having no output schema, the description fully explains what the caller gets back: top-N passages with offsets and similarity scores. It also covers edge cases (truncation flag) and algorithmic behavior. Combined with sibling context and annotations, 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?

Schema description coverage is 100%, so baseline is 3. The description adds practical semantics: it clarifies what 'text' should be (already-pulled record content), gives example queries for 'query', and contextualizes 'limit' as max passages. It doesn't merely repeat schema but enriches understanding, though the schema already covers the basics.

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

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

The description uses a specific verb ('Semantic search INSIDE a fetched record') and clearly states the resource ('a fetched record', e.g., a SEC 10-K body). It distinguishes itself from siblings by explicitly contrasting with ask_pipeworx_grounded and positioning itself as a tool for searching within already-pulled text rather than fetching or grounding over whole documents.

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

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

Provides explicit when-to-use guidance: 'Use when the record is too big to cram into the prompt.' It also gives a concrete workflow pairing with ask_pipeworx_grounded ('fetch with the gateway, ground over the relevant passages'). This gives clear context for when to choose 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 discloses auth requirements, persistence limitations for anonymous/BYO accounts, the always-on feed retrieval path, and delivery channel constraints like SMS verification and 10/day cap. These go well beyond the sparse annotations, which only indicate read/write, idempotency, and destructiveness.

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 intent and return value, then efficiently covers account requirements, three subscription types, and delivery channels in compact structured sentences. No redundant filler.

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

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

For a 3-parameter tool with nested objects and no output schema, the description covers the necessary context: what it creates, what it returns, who can use it, supported subscription variants, and delivery options. The delivery schema already fills in webhook details, so no critical gap remains.

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

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

Schema description coverage is 100%, so the schema already documents the type enum, params filters, and delivery fields in detail. The description mostly reinforces those examples (e.g., sec_8k items, fred_series series_id) and adds the feed retrieval URL, but not substantially new 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 'Create a proactive monitoring subscription to a live-data event stream' and states it returns the subscription id. This specifies a clear action and resource (subscription) and distinguishes it from sibling tools like list_subscriptions and unsubscribe.

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

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

It clearly frames the tool for proactive, ongoing monitoring and states the account prerequisite ('Requires a Pipeworx OAuth account'). It does not explicitly name alternatives or exclusions, but the context is sufficient to infer when to use it.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds valuable behavioral context: the response contains category-bucketed examples drawn from a live catalog, each with the exact tool and argument shape. It does not describe latency or response size, but the annotated safety profile lowers the bar and this context is sufficient.

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 user queries, making the purpose immediately clear. The remaining sentences are compact and each earned: they describe the return format, the optional topic parameter, and the recommended first-use scenario. No wasted words.

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

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

Given this is a simple tool with one optional parameter and no output schema, the description is complete. It explains what the tool returns (category-bucketed examples with tool/argument shapes), how to use it (no-arg vs topic), and when to use it (onboarding). Nothing essential is missing 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?

The schema already provides 100% coverage of the single optional 'topic' parameter, including the allowed values and the note to omit for a cross-category spread. The description's mention of 'finance', 'pharma', 'betting' is redundant and adds no new semantic meaning beyond what the schema states.

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

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

The description clearly states it returns category-bucketed example questions with exact tool and argument shapes, and explicitly positions itself as the onboarding entry point. It distinguishes from siblings by mentioning meta-tools like ask_pipeworx, entity_profile, and compare_entities, and by focusing on question suggestions rather than direct answers.

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 this FIRST when you do not yet know what Pipeworx can do for you' and explains when to call with no arguments vs. passing a topic. It also names the meta-tools it helps learn, providing clear usage context and alternatives.

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

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

Beyond annotations, it adds important behavioral details: ownership enforcement, deactivation rather than deletion, and that historical events remain accessible. This is exactly the kind of context that helps an agent understand side effects.

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 purpose, and every word adds value. No redundancy or filler.

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

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

For a simple single-parameter tool with good annotations and schema, the description covers purpose, constraints, and data implications. It 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% and the schema already describes the id as 'Subscription id (uuid) returned by subscribe.' The description adds no extra parameter meaning beyond saying 'by id', so the baseline of 3 is appropriate.

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

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

The description clearly states 'Cancel a subscription by id' with a specific verb and resource. It distinguishes from siblings like subscribe and list_subscriptions by describing the inverse operation, and the ownership enforcement adds clarity.

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

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

It explicitly states when to use (cancel by id), includes a restriction (only your own subscriptions), and mentions an alternative (historical events via recent_alerts), providing clear usage context.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, but the description adds crucial behavioral nuance: it clarifies the semantic difference between 'could_not_verify' (verification did not happen, carries an error) and 'unsupported' (no source found), and warns callers not to treat could_not_verify as evidence. It also details the returns (verdict, actual value, citation) and the efficiency claim (replaces 4–6 sequential calls), which goes well beyond the structured hints.

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

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

The description is dense but well-structured: it begins with trigger phrases, then states the use case, routing logic, return format, a critical caller warning, and a strategic note about replacing sequential calls. Each sentence carries distinct information. It is slightly long but avoids redundancy, so it's appropriately concise for the complexity level.

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

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

With no output schema, the description must explain return values and semantics, and it does so thoroughly: verdict enum, citation, reasoning, and the special meanings of could_not_verify and unsupported. It also covers prerequisite nuances (financial vs. general claims) and error semantics. For a two-parameter tool with no output schema, this description leaves no critical gaps.

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

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

The input schema already covers both parameters fully with examples and defaults. The description adds extra value by explaining the tolerance_pct override for hallucination detection (1–2%) and the default cap of 5%, as well as giving concrete example claims. This enriches the schema definition, so it earns above baseline but not top marks since the schema already does much of the 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 opens with concrete trigger phrases ('Is it true that…' / 'fact check' / 'verify the claim…') and clearly states the tool's function: natural-language claim verification against authoritative sources. It distinguishes itself from siblings by naming its specific output (verdict types, citation) and the dual-path approach for financial vs. other claims, which differentiates it from generic search/QA tools.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' giving a clear when-to-use. It also delineates the two routing paths (SEC EDGAR for company-financial claims; grounded pipeline otherwise). However, it does not explicitly mention when not to use it or name alternative sibling tools, so it's strong but not maximal.

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