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?

Annotations already establish read-only, open-world, idempotent, non-destructive behavior. The description adds useful non-obvious behavioral context: automatic routing across 5,798 tools, filling arguments, and returning structured answers with stable pipeworx:// citation URIs. There is no contradiction with 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 longer than average, but it is front-loaded with the most important directive and each sentence contributes distinct value: domain scope, routing behavior, trigger phrases, examples, and alternative tool. The example list is somewhat redundant with the trigger phrases, but it clarifies the expected input format.

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

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

For a one-parameter router tool with no output schema, the description covers the operation, return shape (structured answer + citations), when to use it, how to phrase the input, and the main alternative. Nothing critical 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?

Schema description coverage is 100%, with the primary parameter 'question' documented as natural language and all aliases explicitly listed. The description adds illustrative examples and trigger phrases, but no additional semantic constraints, so it stays at the high-coverage baseline.

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

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

The description opens with a clear, specific directive: prefer this tool over web search for current or historical factual questions, then enumerates concrete domains (SEC filings, FDA drug data, FRED/BLS statistics, patents, weather, news, etc.). It also states the core mechanism—routing questions to a large toolset and returning cited structured answers—making the tool's purpose immediately identifiable.

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 trigger phrases: 'what is', 'look up', 'find', 'get the latest', 'how much', 'current', and says to use it even when web search could answer. It also gives a when-not-to-use alternative: for deep multi-source analysis, use deep_research. This is strong routing guidance.

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

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

Beyond annotations, the description discloses the live candidate-routing mechanism, the fact that no candidate is currently active so behavior matches ask_pipeworx exactly, and the fallback guarantee that it remains a full working router. This gives a complete picture of the experimental behavioral 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 packs essential context into five purposeful sentences without fluff. It front-loads the beta identity and current state, then provides usage guidance, comparison intent, and a fallback guarantee.

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

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

Given the simple one-required-parameter schema and rich annotations, the description fully covers beta status, behavioral equivalence, usage conditions, and fallback behavior. The response shape is handled by referencing ask_pipeworx's identical response shape, so nothing critical is missing.

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

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

Schema description coverage is 100%, and the schema thoroughly documents 'question' and its five aliases. The description adds no parameter-level detail beyond referencing that arguments are identical to ask_pipeworx, so it remains at 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 identifies the tool as the beta version of ask_pipeworx, a universal router with the same 5,798 tools, same arguments, and same response shape. It explicitly differentiates it from the stable sibling by explaining that it exists for testing candidate routing improvements.

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

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

The description provides an explicit usage condition: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also states that results are compared against the stable router to decide merges, which clarifies the experimental context and implies ask_pipeworx is the stable 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, and the description adds substantial context beyond those: answers are extracted only from tool results, refusal reasons are enumerated, and success returns a specific evidence-backed shape. It also discloses the extra LLM call cost, which is valuable behavioral information for an agent weighing tool choices.

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 dense and each sentence earns its place: mode, routing, extraction constraint, exact return shape, refusal reasons, use cases, and cost trade-off are all packed efficiently. It is well-organized and front-loads the most important distinguishing information.

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

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

Even though there is no output schema, the description fully compensates by providing the exact success response structure and all possible refusal reasons. Combined with read-only and idempotent annotations, the agent has everything it needs to decide whether to invoke this tool and what to expect.

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 input schema already documents the question field and its aliases. The description adds no parameter-level detail, which is acceptable because the schema carries the full semantic burden.

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

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

The description clearly defines this as a hallucination-resistant answer mode for high-stakes reads and explains the full pipeline: routing, fetching, then extracting answers only from tool results. It explicitly distinguishes itself from ask_pipeworx, its closest sibling, by emphasizing grounded extraction and refusal behavior.

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

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

It gives explicit when-to-use guidance: use whenever an answer will be quoted, cited, or acted on and facts must not be invented. It also names the alternative ask_pipeworx and states the trade-off — extra LLM call — and directs casual lookups to the cheaper sibling.

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

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

The description 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?

Annotations already establish readOnly, openWorld, and idempotent hints, and the description adds substantial behavioral context: account/paid-tier requirements, parallel decomposition, findings packet fields, gaps[] for unanswered facets, never-invented behavior, hop semantics, contradiction scans, citation fetchability, and latency expectations. 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 long and dense, but it is front-loaded with the critical account constraint and every sentence carries operational value. It could be better organized into cleaner sections, but there is little filler or redundancy.

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

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

Even without an output schema, the description thoroughly explains return contents (evidence, confidence, source, fetched_at, citation_uri), gap/contradiction behavior, depth-mode effects, account restrictions, and expected latency. An agent has enough context to select the tool, set parameters, and interpret results correctly.

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

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

Schema coverage is 100%: both question and depth have descriptions, and depth has an enum. The tool description reinforces that broad/multi-part questions are acceptable and ties depth modes to hop behavior, but it does not materially add semantics beyond what the schema already provides.

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

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

The description clearly states the tool performs grounded multi-source research across Pipeworx's 1517 structured data sources in one call, and explicitly contrasts itself with open-web search. It provides concrete example questions and distinguishes itself from ask_pipeworx, giving an agent a specific verb+resource+scope.

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

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

It gives explicit when-to-use guidance: broad/multi-part questions over structured data, and explicit alternatives: use ask_pipeworx if not signed in or for a single lookup. This is actionable routing guidance, not just vague 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 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 mark the tool readOnly, openWorld, and idempotent; the description adds substantial behavior beyond that: parallel fan-out across sources, USPTO PatentsView soft-fail due to sunset, empty sections meaning real 'no data,' and private-company resolution behavior. 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 long, but every sentence earns its place by covering a distinct source, return field, or edge case. It is front-loaded with examples and the core purpose, making the structure effective despite being verbose.

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

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

With no output schema, the description must explain return values, and it does thoroughly: CIK/company_name, recent_filings with URIs, fundamentals, patents, federal_contracts, fda_products, hiring, news, and LEI—plus sources_used/sources_failed semantics. It also covers input variants and error behavior, leaving no critical gap for correct invocation.

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

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

The input schema already provides 100% parameter descriptions, so the baseline is 3. The description adds value by reinforcing that 'company' and 'ticker' are interchangeable and explaining resolution details (zero-padded CIK, name matching via SEC EDGAR, private-company outcome), which enriches parameter understanding beyond the schema.

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

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

The description leads with concrete user intents and defines the tool as a 'full cross-source profile of a US public company in ONE parallel call.' It explicitly contrasts with chaining single-pack lookups, making it easy to distinguish from siblings like resolve_entity and compare_entities.

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

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

It gives an explicit usage directive: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also covers edge cases like private companies returning resolved:false and notes that person/place support is coming soon, clarifying when not to use it.

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

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

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?

The description goes far beyond the annotations' readOnlyHint and idempotentHint. It discloses the token-overlap matcher's limitations, the meaning of null in temporal_alignment, the fee schedule gap, and the fact that spreads are gross not net tradeable. No contradiction with annotations is present.

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

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

The description is long but densely packed with purposeful details. Casing labels like SAFETY FIELDS, RESPONSE, and the sorted code list improve scannability. A slightly tighter version could earn a 5, but the length is justified by the number of critical caveats an agent must know.

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

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

Without an output schema, the description fully compensates by explaining the response structure, safety fields, compatibility codes, per-entry flags, skipped counters, and fee treatment. An agent has enough context to invoke the tool correctly and interpret ambiguous 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?

Even though schema coverage is 100%, the description adds essential semantics: the 'topic' parameter's accepted shortcuts, the override behavior of explicit tickers, and the distinction between the two modes. This meaningfully extends beyond the raw 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 first sentence states a specific verb and resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It immediately differentiates itself from sibling tools like polymarket_arbitrage and polymarket_edges by scoping to cross-venue spread comparison.

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

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

Explains TWO MODES explicitly: the pre-mapped 'topic' shortcuts and the explicit 'kalshi_event_ticker' + 'polymarket_event_slug' pairing. It also warns that pre-mapped does not mean tradeable and that compatibility warnings can be non-empty even when matched_pairs>0, giving agents clear guidance on when the tool is and is not reliable.

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?

The description discloses rich behavioral details beyond the annotations: it cascades through multiple lookup endpoints, degrades gracefully when GLEIF or OpenFIGI is unavailable, returns figi_candidates when a name is ambiguous, and explicitly lists unresolved identifiers rather than omitting them. It also explains that identifiers are labelled with their source. This far exceeds what readOnlyHint and idempotentHint already convey, with no contradiction.

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

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

Although the description is long, it is densely packed with useful information and front-loaded with the most important directive: 'Use FIRST whenever you have a name but need an ID.' Every sentence adds either a behavioral nuance, a supported-type detail, or a parameter edge case, so the length is justified rather than padded.

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

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

With no output schema, the description carries the burden of explaining return values, and it does so: it lists the exact identifiers returned per type (CIK, ticker, company_name, LEI plus ownership, FIGI, RxCUI, ingredient, brand), mentions source labelling, and explains the unresolved case. An agent has enough context to call the tool and interpret its response correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds substantial meaning beyond the schema. It tells the agent exactly how to format the `value` parameter, including the crucial warning to pass only the entity name and not the full noun phrase, with a concrete example ('NEW YORK ST DORM AUTH' vs 'NEW YORK ST DORM AUTH revenue bonds'). This is genuinely actionable parameter guidance.

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

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

The description clearly states a specific action—resolving a user-spoken name to canonical/official identifiers—and enumerates the exact resources and identifiers involved (CIK, ticker, LEI, FIGI, RxCUI). It is not simply restating the title, and the examples make the purpose unambiguous. However, it does not explicitly contrast itself with sibling tools like entity_profile or compare_entities, so it falls short of a perfect 5.

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

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

It gives an explicit directive: 'Use FIRST whenever you have a name but need an ID.' It also explains when the tool will return candidates instead of asserting a single answer, and it clarifies that non-equity instruments without tickers still resolve here. It does not explicitly name alternative tools or say when not to use this tool, so it is slightly shy of full usage-guideline coverage.

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.