words

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

Annotations already declare readOnly/idempotent/destructive hints, so the bar is to add context beyond that. The description adds meaningful behavioral details: the default free model, and that providing _apiKey triggers external calls to Anthropic with direct billing ('you pay Anthropic directly'). This enriches the agent's understanding of side effects and cost.

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

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

Four sentences, front-loaded with the core function and scoring output, then return format and use cases. Every sentence adds value: purpose, default/cost, return shape, and applicability. No redundancy.

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

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

The description fully explains the tool's behavior, return shape, defaults, costs, and use cases. Annotations cover safety. No output schema exists, but the per-model return structure is explicitly described. This is more than sufficient for an agent to decide when 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 coverage is 100%, so baseline is 3. The description adds practical semantics beyond schema: it explains the default model behavior, clarifies that _apiKey enables Anthropic probing and costs the user, and states that context 'helps disambiguate common names'. This is a useful supplement.

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 ('Probe') and resource ('one or more LLMs'), then clarifies the output ('score visibility (0-100) per model'). It clearly differentiates from sibling tools by focusing on AI-model knowledge about an entity, distinct from entity_profile or 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?

Provides explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and defaults ('Default model is Workers AI Llama-3.3-70b (free)'). However, it doesn't mention when not to use it or contrast with similar siblings like scan_competitor_ai_presence, so it falls short of full exclusions.

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

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

Beyond the read-only/idempotent annotations, the description reveals that the tool fills arguments, returns stable pipeworx:// citation URIs, works on every tier, and makes one fast call. There is no contradiction with annotations; this adds meaningful behavioral context.

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

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

The description is long but dense and front-loaded with the most important directive. Each section—preference, examples, alternatives—earns its place; only minor redundancy prevents a 5.

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

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

Despite having no output schema, the description explains the return format (structured answer with stable citation URIs), the scope (5,521 tools/1,452 sources), cost/speed (one fast call, every tier), and routes to siblings. This is more than enough for the agent to invoke and trust 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 schema covers 100% of parameters, but the description adds value by specifying the types of natural-language questions to supply and providing domain examples. It doesn't elaborate on the alias parameters because the schema already lists them, so the baseline is slightly exceeded.

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 action: routes the user's question to one of 5,521 tools across 1,452 sources and returns a structured, cited answer. It clearly distinguishes itself from siblings by naming ask_pipeworx_grounded and deep_research as alternatives for different needs.

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 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', gives concrete trigger phrases and examples, and states when to step up to ask_pipeworx_grounded or deep_research. This is exceptionally clear guidance on when vs. 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 (readOnly, idempotent, etc.), the description discloses that it is an experimental beta with candidate routing improvements enabled live, that no candidate is currently active so it matches ask_pipeworx exactly, and that it is a full working router rather than a fallback. This provides valuable behavioral context beyond the structured 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 somewhat verbose with repetitions like 'identical universal router' plus 'same 5,521 tools, same arguments, same response shape', but every sentence contributes meaningful context about beta status, current behavior, usage, and fallback semantics. It is front-loaded with the core definition and is not excessively long.

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

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

The description covers the tool's relationship to ask_pipeworx, its experimental nature, current inactive candidate status, and its full functionality. It references 'same response shape' for return values, which is sufficient given no output schema and the high complexity of a 5,521-tool router, but doesn't independently describe the response 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?

The input schema has 100% coverage with all six parameters documented as aliases for 'question'. The description mentions 'same arguments' but adds no parameter-specific semantics. Since the schema already fully explains the parameters, 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 identifies the tool as a beta version of ask_pipeworx, an identical universal router with the same 5,521 tools, arguments, and response shape. It explicitly distinguishes it from stable siblings by its experimental routing improvements, making the purpose unmistakable.

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

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

The description states 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router. It provides clear when-to-use context and names the alternative (ask_pipeworx), though it doesn't explicitly state when NOT to use it (e.g., for production stability).

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description thoroughly discloses behavioral traits: it uses only tool-result content, returns an exact structured response with evidence and refusal reasons, and explicitly lists all refusal reason values. It also discloses the additional LLM call cost, making the agent fully aware of the tool's operational characteristics.

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 and well-structured, leading with the core value proposition, then explaining the mechanism, the exact return format, and the usage guidance. Every sentence contributes meaningful detail—like the refusal reasons and cost comparison—without 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?

With no output schema, the description fully compensates by detailing the success response shape ({answer, evidence, confidence, source, fetched_at, refusal_reason}) and all failure modes. It also covers the tool's routing behavior, use cases, and cost, providing a complete picture for an agent to invoke 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?

The input schema already provides 100% coverage with descriptions for all six aliases (q, text, input, query, prompt, question) that all map to the natural-language question. The description does not add further parameter-level detail, but it also does not need to because the schema fully documents the parameter semantics, so the baseline score of 3 is appropriate.

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

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

The description clearly defines the tool as a 'hallucination-resistant answer mode for high-stakes reads' and distinguishes it from the sibling tool ask_pipeworx by emphasizing grounded, evidence-backed answers. It specifies the exact behavior of extracting answers only from tool results and returning refusals when data is insufficient, making its purpose unmistakable.

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

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

The description provides explicit usage guidance: use this tool when an answer will be quoted, cited, or acted on and the agent must not invent facts, and explicitly says to 'prefer ask_pipeworx for casual lookups.' It also names the alternative tool and explains the cost trade-off of one extra LLM call, giving clear when-to-use and when-not-to-use criteria.

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

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

The description adds context beyond annotations by naming the Datamuse suggestion endpoint and explaining that results are 'ranked by score'. While annotations already declare readOnlyHint and idempotentHint, the description enriches understanding of the data source and output ordering without repeating annotation details.

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

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

The description is exactly two sentences, with the verb and resource front-loaded. It includes a concrete example, and every sentence adds value with no fluff. Perfectly concise and well-structured.

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

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

Given the tool's simplicity (2 params, output schema present, strong annotations), the description adequately covers what the tool does and how it behaves. It could mention overlap with sibling tools, but the description is sufficient for a straightforward autocomplete operation.

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

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

Schema description coverage is 100%, so the schema already documents both prefix and limit parameters with descriptions and examples. The tool description does not add significant extra meaning beyond the schema's own examples, hence baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Return word completions for a given prefix string' using the Datamuse suggestion endpoint. It provides specific examples ('hel' returns 'hello', 'help') that illustrate the behavior and distinguish it from sibling tools like find_synonyms or find_rhymes.

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

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

The description implies usage by showing a prefix example, but it does not explicitly state when to prefer this tool over alternatives such as find_words or explore for related terms. There is no mention of when not to use it, leaving room for ambiguity.

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, openWorldHint, idempotentHint) by detailing the resolver contract (confidence levels, match score, alternatives), parent_event extractor, news fallback fields, low-confidence blocking behavior, closed-market handling, wide-spread tradeability flags, and cancellation-rule risk. This is rich behavioral context that annotations alone cannot convey. 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 extremely long—essentially a full spec with multiple labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.). It is well-structured and front-loaded with purpose, but it is not concise; many sentences could be tightened or moved to an expanded reference. It earns 'structured but verbose' rather than high conciseness.

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

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

With no output schema, the description fully carries the burden of explaining return shapes and edge cases. It covers result.market, result.analysis, result.evidence, resolver match fields, parent_event, news fallback attributes, status codes, and cancellation risk. For a tool of this complexity, it is exceptionally complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful nuance: it clarifies the 'market' param accepts slug/URL/question, describes what 'quick' vs 'thorough' actually entail, and explains include_raw's size trade-off (20KB vs 50-500KB). This is beyond the schema's own property descriptions, so a 4 is warranted.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly explains inputs (slug/URL/question), the fan-out process, and the returned evidence packet + market-vs-model comparison. This fully distinguishes it from siblings like polymarket_edges or validate_claim.

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 intended use cases are given: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. The fan-out examples also demonstrate category-specific contexts. However, it does not explicitly name alternative tools or state when NOT to use this tool, so it misses the top bar for 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?

Beyond the annotations (readOnlyHint, openWorldHint, etc.), the description reveals data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and output includes citation URIs. This is rich behavioral context that helps the agent understand what the tool does internally.

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 efficient. Every sentence provides actionable detail: trigger examples, entity count, data sources, fiscal-year handling, sorting, output, and efficiency gains. 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?

With no output schema, the description compensates by explaining return structure (paired data + citation URIs). It also covers not just 'what' but 'why' (replaces 8-15 lookups) and 'how' (parallel call, sorting). Given the tool's scope, the description is fully sufficient 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?

Although schema coverage is 100%, the description adds important semantics: type='company' pulls 10-K metrics, type='drug' pulls FAERS counts. It also clarifies the format of 'values' with examples (tickers vs drug names) and reinforces the 2-5 limit, going beyond the schema's basic type definitions.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs in a single parallel call. It explicitly distinguishes from siblings by mentioning it replaces sequential single-pack lookups and names the entity types and data sources.

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 trigger phrases like 'Compare X and Y' and 'X vs Y' as well as a strong directive: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' This tells the agent exactly when to use this tool and implies the alternative (sequential lookups) is inferior.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description adds auth requirements (free sign-in, paid 'thorough'), latency (15-60s, up to ~90s), citation semantics (stable pipeworx:// URI always fetchable), explicit gaps[] 'never invented', contradictions[] for standard/thorough, and semantic excerpting. This is rich behavioral disclosure well beyond structured 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 carries distinct value: auth, scope, alternatives, depth behavior, citation guarantees, gap handling, and latency. It is front-loaded with the most critical operational constraint (account requirement) and uses clear formatting with concrete examples.

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

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

Given the tool's complexity, no output schema, and two parameters, the description is thorough: it covers input expectations, output shape (findings packet, gaps[], contradictions[], hop field), auth, timing, exclusions (breaking news), and second-hop iteration. An agent has enough information 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 description coverage is 100% and the depth enum already fully explains quick/standard/thorough with hop details and paid status. The description repeats this information and adds only tool-level context like latency and 'multi-step questions resolve in one call', not per-parameter semantics. 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 states a specific verb+resource+scope: 'Grounded multi-source research across Pipeworx's 1452 STRUCTURED data sources ... in ONE call' and immediately distinguishes itself from open-web search and from ask_pipeworx with concrete examples. This uniquely identifies the tool among siblings.

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

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

It explicitly states when to use: 'Best for broad/multi-part questions over structured data', and when not to: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'. It also names the alternative and covers the account-required fallback: 'If you are not signed in, use ask_pipeworx instead'.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds meaningful behavioral context about the output: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This explains return format and direct callability, going beyond the structured annotations.

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

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

Three concise sentences with front-loaded core purpose: 'Find tools by describing the data or task.' Each sentence contributes distinct information (what, when, return format), with 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?

As a discovery tool with no output schema, the description covers all essential aspects: purpose, when to use, return value (top-N tools with schemas), and note that results are directly callable. Given the moderate complexity and rich annotations, this is fully complete.

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

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

Input schema covers 100% of parameters with descriptions, including the main 'query' field and all aliases. The description only mentions 'top-N' which is already detailed in the limit parameter ('default 20, max 50'). Thus, the description adds little value beyond the schema, warranting the baseline 3.

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

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

Description begins with 'Find tools by describing the data or task', clearly identifying the verb (find) and resource (tools). It distinguishes itself from domain-specific siblings by explicitly positioning itself as a discovery meta-tool ('Call this FIRST when you have many tools available').

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: 'Use when you need to browse, search, look up, or discover what tools exist' and instructs to 'Call this FIRST when you have many tools available and want to see the option set'. However, it does not explicitly state when NOT to use it or name alternative discovery/retrieval tools, 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 this as read-only, idempotent, and non-destructive. The description adds substantial behavioral context beyond annotations: the parallel fan-out across multiple sources, specific return fields (filings, fundamentals, patents, news, LEI), the USPTO API sunset and soft-fail behavior, GDELT→GNews fallback, and the zero-padded CIK requirement. This enriches the agent's understanding of execution and output.

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

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

The description is long but densely packed with useful information: example queries, data sources, return fields, caveats, and parameter guidance. It is structured with clauses and semicolons, and every sentence contributes value. While not as lean as some, the length is justified by the tool's complexity.

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

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

Given the tool's complexity (multiple sources, fallbacks, specific output fields), the description is exceptionally complete. It documents return structure (cik, filings with URIs, fundamentals, patents, news, LEI), input constraints, API sunset, and fallback behavior. With no output schema, the description fully compensates, leaving no major gaps.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by providing concrete examples ('AAPL', '0000320193'), explaining the zero-padding requirement, and clarifying the 'company' enum limitation. This goes beyond the schema's field descriptions, justifying a 4.

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

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

The description explicitly states the tool's function: 'full cross-source profile of a US public company in ONE parallel call.' It provides clear example user intents and lists specific data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and return fields, making the purpose unmistakable. It also distinguishes from siblings via the 'ALWAYS PREFER over chaining single-pack lookups' directive.

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

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

Usage guidance is explicit: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also states when not to use (names not supported) and directs to resolve_entity first if only a name is available. This provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate a safe read-only, idempotent operation. The description adds meaningful behavioral context by explaining what each relation type returns (e.g., 'adjectives for a noun'), which is beyond what annotations provide. No contradiction with annotations.

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

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

Two concise sentences, front-loaded with the core purpose, and compactly lists relation types. Every sentence contributes value without redundancy.

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

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

For a simple lookup tool with complete schema annotations, an output schema, and a clear description of relation types, coverage is sufficient. It could mention the return format, but the output schema covers that.

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 repeats parameter meanings already present in the schema (e.g., relation types, default limit/relation) without adding new semantic details beyond what the schema provides.

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

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

The description uses a specific verb 'Find words related to a given word by a specific relation type' and explicitly lists the supported relation types, distinguishing it from siblings like find_rhymes and find_synonyms which handle only one relation each.

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

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

The description implies usage (for any of the listed relation types) but does not explicitly state when to prefer this over specialized siblings like find_synonyms or find_rhymes. It provides clear context but no exclusions or alternative guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds the behavioral detail that results are 'ranked by score', which is not present in annotations. No contradictions.

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

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

The description is a single, front-loaded sentence with no wasted words. It states the core action and key output ordering, earning its place entirely.

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

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

For a simple tool with an output schema and rich annotations, the description is complete. It conveys the essential purpose and behavior without needing to explain return formats or edge cases, which the output schema covers.

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 both parameters (word and limit) sufficiently. The description only mentions 'given word' and does not add further parameter detail, leaving the schema to carry the semantic load.

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

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

The description clearly states the tool's function: finding words that rhyme with a given word, ranked by score. This distinguishes it from sibling tools like find_synonyms or find_words, which address different lexical relations.

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

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

The description provides clear context that this tool is for rhyming words, implying it should be used when rhyme matches are needed. It does not explicitly mention alternatives or when not to use it, but the context is 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, safely covering the operation type. The description adds behavioral context beyond annotations by revealing it uses an external API (Datamuse), ranks results by similarity score, and applies a default limit. This is useful information about data source and result behavior that annotations do not provide.

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

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

The description is three sentences and every sentence adds value: it names the API and relation, explains scoring and limit, states the return format, and gives the use case. It is front-loaded with the core purpose and contains no fluff or repetition of schema fields.

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 an output schema, so return structure is already documented. The description explains the result content (candidate word with score) and the default behavior. For a simple lookup tool with strong annotations and schema coverage, this is complete enough for an agent to select and invoke correctly. No critical missing information is evident.

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, with word and limit already described in the schema. The description mentions the default limit for 'limit' but adds no additional semantic meaning beyond what the schema provides. Baseline 3 is appropriate because the schema does the heavy lifting and the description does not compensate further.

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

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

The description clearly states the tool finds synonyms for an English word, specifies the Datamuse API and rel_syn relation, and explains ranking by similarity score. It distinguishes itself from sibling tools like find_rhymes and find_words by focusing specifically on synonyms. The verb 'find' and resource 'synonyms' are explicit.

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

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

The description gives context for when to use it: 'when writing, editing, or paraphrasing English prose.' It does not explicitly mention alternatives or exclusions, but the mention of 'synonyms' and the API relation clearly signal its use case relative to sibling tools. The context is clear, though it lacks an explicit 'use this instead of X' statement.

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. The description adds only that constraints can be combined, but does not detail actual behavior like AND semantics, default limits, or result ordering. No contradiction with annotations.

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

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

The description is two sentences, front-loaded with 'Advanced word search' and immediately followed by the core functionality. Every word earns its place with no redundancy or fluff.

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

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

Given the tool's complexity (7 optional parameters, aliases, wildcards), the description is minimal. It does not explain how multiple constraints are combined (AND vs OR) or that all constraints are optional. The schema and annotations fill some gaps, but the description alone is only adequate for basic 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?

The input schema covers all 7 parameters with descriptions (100% coverage), and the description adds no extra parameter semantics beyond vaguely referencing meaning, pronunciation, and spelling. With full schema coverage, 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 states 'Advanced word search. Find words matching a combination of meaning, pronunciation, and spelling constraints.' This clearly specifies the tool's function, and the mention of combined constraints distinguishes it from siblings like find_rhymes, find_synonyms, and find_related.

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 this tool is for advanced searches that combine multiple constraint types, but it does not explicitly state when to prefer it over simpler alternatives or provide any exclusions. The usage context is implied rather than directly stated.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the agent knows it is a destructive write operation. The description adds valuable context about what kind of data to clear (sensitive data, stale context) and that it removes saved memories. This goes beyond the structured annotation hints 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 two sentences, front-loaded with the primary action, followed by usage guidance and related tools. Every word earns its place 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 one-parameter tool with a complete schema and annotations, the description covers what the tool does, when to use it, and how it relates to siblings. No output schema is present, but a simple deletion tool does not require return-value details. The description is fully adequate for tool selection and invocation.

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

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

Schema coverage is 100% with the 'key' property described as 'Memory key to delete'. The description's phrase 'by key' adds little beyond the schema. Baseline score of 3 is appropriate because the schema fully documents the parameter, and the description does not need to compensate.

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 ('Delete') and resource ('previously stored memory by key'), clearly distinguishing it from sibling tools like 'remember' and 'recall'. It exactly states the core function without ambiguity.

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'. It also mentions pairing with 'remember and recall', giving relational context. However, it does not explicitly state when NOT to use the tool, which would make it 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?

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses the tool's internal behavior: it fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. This adds meaningful procedural context without contradicting the annotations.

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

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

The description is concise—two sentences—with the primary action front-loaded. The 'Useful for' clause adds practical context without redundancy. Every sentence earns its place, and the structure is 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 tool with two well-documented parameters and no output schema, the description sufficiently explains the process, output format, and primary use cases. It could mention potential error conditions (e.g., unreachable URL) but is otherwise complete enough 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?

Both parameters are already fully described in the input schema (url and max_links), so schema coverage is 100%. The description reinforces that the URL can be any site and that the output is a text blob, but it does not add significant semantic detail beyond the schema for the parameters.

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

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

The description opens with a specific verb+resource pairing: 'Generate a production-ready llms.txt file for any URL.' It clearly explains the tool's core function, including what it fetches, extracts, and emits, and differentiates it from sibling tools by focusing specifically on llms.txt generation rather than broader AI visibility scanning.

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

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

The description provides explicit 'Useful for' scenarios: getting a client's site indexed, drafting llms.txt for a project, and auditing a competitor's AI-crawler view. This gives clear context for when to use the tool, though it does not explicitly name alternatives or state when not to use it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds behavioral context by listing the exact fields returned (id, type, params, created_at, last_fired_at, fire_count), which is not present in annotations. It does not contradict annotations.

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

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

The description is concise: two sentences that front-load the purpose and return fields, then provide a usage note. Every word earns its place with 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 list tool with one optional parameter and no output schema, the description is complete. It states what the tool returns, when to use it, and the annotations cover safety. No significant gaps exist.

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 full description coverage for the only parameter (include_inactive) with a clear explanation. The description does not add any parameter-specific semantics, but with 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description uses the specific verb 'List' with the resource 'the caller's active subscriptions', clearly distinguishing it from sibling tools like subscribe and unsubscribe. It also enumerates the fields returned, making the tool's function unambiguous.

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

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

The description provides clear use cases: 'review what you're monitoring before adding more' and 'find an id to cancel'. This implies when to use the tool relative to subscribe/unsubscribe, though it does not explicitly name the alternative tools. This is strong guidance without being overly verbose.

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 rate limiting (5 per identifier per day), free usage, and the claim_token mechanism for later reads. Annotations are all false and the description adds significant behavioral context beyond them, without contradicting anything.

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?

Longer than typical but every sentence carries operational weight. It is front-loaded with the main purpose and usage triggers, and the rest covers important exclusions, limits, and token behavior. No filler, though slightly verbose.

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

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

Covers core usage, exclusions, rate limits, and the follow-up token mechanism. Since there is no output schema, it sufficiently explains the return token behavior. The distinction between account vs. no-account filing is only implied, leaving minor ambiguity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining how to use claim_token (passing it back to read status) and advising not to paste end-user prompts, enriching the meaning of the message and claim_token parameters.

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

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

The description clearly states the tool's purpose: telling the Pipeworx team about something broken, missing, or needing to exist. It distinguishes itself from siblings like ask_pipeworx by focusing on feedback reporting rather than questions, and explicitly scopes to Pipeworx-served tools.

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

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

Provides explicit when-to-use guidance: bug, feature/data_gap, praise. Also gives exclusions (tools from other MCP servers) and directs users to file elsewhere. Explains the claim_token flow for checking resolution status.

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, covering the safety profile. The description adds valuable behavioral context beyond these: data provenance ('derived from CF analytics-engine'), privacy guarantee ('no PII'), output shape ('just (pack, tool, count)'), and caching behavior ('Cached 5min-1h depending on window'). No contradictions with annotations.

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

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

The description is three sentences with zero waste: the first sentence states purpose and output, the second lists use cases, the third gives data provenance, privacy, and caching. It is front-loaded with the main purpose and 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?

Given the tool's low complexity (one optional parameter, no output schema, no nested objects), the description provides adequate context: what is returned, the data source, privacy implications, and caching behavior. It is sufficient for an agent to decide whether to invoke the tool and what to expect from the response, though it does not precisely define the output schema.

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

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

Schema coverage is 100%: the only parameter 'window' is fully described with an enum and detailed semantics ('24h (default) | 7d | 30d. Shorter windows surface what's hot right now; longer windows show steady-state demand.'). The description references the window in prose but adds no additional parameter-level meaning, so the baseline of 3 applies.

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

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

The description opens with a specific question ('What other AI agents are calling on Pipeworx right now') and immediately states what it returns: 'top tools, top packs, and total call volume' over a recent window (24h, 7d, or 30d). This clearly distinguishes it from sibling tools like discover_tools or recent_alerts, which serve different purposes.

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

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

The 'Useful for' section lists three explicit, concrete scenarios for when to use this tool: discovering hot data sources, confirming canonical tool choices, and checking alignment with other agents' needs. It provides clear context but does not explicitly state when not to use it or name alternative tools, 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?

Given annotations already signal read-only, idempotent, non-destructive behavior, the description adds meaningful operational context: partition thresholds (>3pp), placeholder filters (20%), semantic anchor similarity (≥0.30 Jaccard), and the fill-check logic against live CLOB depth. It also warns when not to trade (realizable_edge_pp ≤ 0). 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 carries operational weight—covering detection modes, filters, thresholds, output shape, and fill-risk caveats. It is well-organized into logical segments (modes, semantic anchor, partition filter, response, fill check) and front-loaded with the core purpose.

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

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

For a complex tool with no output schema, the description compensates thoroughly by enumerating response fields (gap_pp, suggested_trade, reasoning, monotonicity context, partition_check) and explaining the fill-check pipeline. All critical user decisions (which mode, how to interpret deviations, when to avoid trading) are covered.

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

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

Although the schema already describes both parameters (event and topic) with examples, the description goes further by explaining the no-args default (trending_scan), providing detailed slug examples ('fed-decision-may-2026'), and clarifying that full URLs are accepted. It also connected each parameter to the detection mode and explained the trade-offs.

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

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

The description opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket' and immediately distinguishes the detection methods (monotonicity violations, partition-sum checks) from sibling tools like polymarket_edges and polymarket_fill_risk. It clearly defines the tool's unique capability and 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?

Explicit guidance is provided for every mode: no args for trending_scan, event slug for single-event, and topic for cross-event scanning. It includes recommendations when to use each and points users to polymarket_fill_risk for custom sizing, effectively explaining alternatives.

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

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

Annotations already indicate read-only/idempotent, but the description adds substantial behavioral detail: caching ('Cached 1h at the KV level keyed on all knobs'), the 24h-move warning, model gate relaxations ('gates relaxed Run 8 from prior 85%/5%/50:1'), unreliability of Fed signal, and diagnostics for empty segments. This goes far beyond the annotations.

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

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

The description is excessively long and dense with all-caps section labels. While front-loaded with purpose, it packs many details (model family specifications, gate numbers, diagnostics structure) that could be trimmed. It is structured but not concise.

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

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

No output schema exists, so the description carries full burden for return values. It fully specifies response top-level fields (by_segment, fed_candidates/fed_note, _diagnostics with funnel counters) and per-opportunity fields. It also explains caching and failed-gate behavior, making the tool self-contained.

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 adds extra semantics via the 'TRADEABLE-EDGE KNOBS' section, explaining how min_liquidity/max_spread_pp drop un-realizable edges and how min_partition_leg_kelly applies to per-leg Kelly. It also explains slippage_pp's effect on edge netting, providing value beyond the schema.

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

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

Clear specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' The description also outlines the output structure. However, it does not explicitly differentiate from sibling tools like polymarket_arbitrage, so it doesn't fully earn a 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?

Includes explicit use case: 'Built for "what should I bet on today"' and mentions avoiding paging hundreds of markets. It also gives guidance on knob usage but does not mention alternatives or when not to use this tool.

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

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

Beyond the annotations (readOnly, idempotent), the description discloses key behavioral traits: history depth is bounded by a 60-day snapshot TTL, snapshots are written on cache-miss so gaps mean no scan, and decay is computed from daily closes of edge_pp_net. This adds rich context about data freshness, limitations, and computation method.

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 carries information. It is well-structured with labels like 'RESPONSE:' and 'LIMITS:' to separate concepts. It avoids redundancy and justifies its length by covering multiple aspects (purpose, response schema, data caveats) in a compact, organized manner.

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 details the response format (tracked[], expired[], snapshot_dates[]) and explains each field. It also covers limitations, default parameter behavior, and how to interpret gaps. This is complete for a read-only telemetry tool with 2 optional parameters.

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 is already descriptive (100% coverage), but the description adds value by explaining the default lookback (14, max 30) and the window family (default '1wk'), and by linking parameters to the response structure (e.g., snapshot_dates reflecting days with data). This exceeds the schema's 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's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question ('how long has this edge existed and is it shrinking?') and distinguishes itself from sibling tools like polymarket_edges by focusing on edge history rather than current edge values.

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

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

The description provides clear context on when to use this tool (to assess edge decay/persistence) and includes exclusions like 'not intraday' (based on daily closes). It implies alternatives (polymarket_edges for current snapshots) but does not explicitly name them or provide a when-not-to-use list for each sibling. Overall, usage guidance is strong but could be more explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds significant behavioral context by detailing the output fields (top_of_book, vwap_fill_price, slippage_pp, verdict), explaining the ladder walk, and warning about partial basket fills converting arbitrage into unhedged directional positions. It could mention error handling or rate limits, but it adds substantial value beyond annotations.

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

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

The description is long but every sentence carries functional detail. It is well-structured with explicit mode labels and ALL CAPS keywords, making it scannable. The length is justified by the tool's dual-mode complexity, though it could be slightly tightened without losing information.

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

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

Despite having no output schema, the description fully enumerates the return fields for both modes, including edge cases like thin_legs[] and forced_directional_risk. It also provides usage thresholds and risk warnings, making it complete for an AI agent to decide and invoke the tool appropriately.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful interpretation: size_usd is 'max spend on buys, target proceeds on sells' in single-market mode and 'settlement notional S (shares per leg)' in basket mode. It also clarifies side defaults and auto behavior in basket mode, which enriches the 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 opens with 'Realizable-vs-theoretical edge check against live CLOB order-book depth', which precisely defines the tool's purpose. It further distinguishes itself from sibling tools by explicitly referencing polymarket_arbitrage and polymarket_edges, making its unique role clear.

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

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

The description provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the two modes and their triggers, giving clear alternatives and 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?

With readOnlyHint=true and destructiveHint=false, annotations already cover safety, but the description goes far beyond by explaining the compatibility_warning logic, temporal_alignment meaning, and skipped_cross_type/subtype counters. It transparently discloses when results are meaningless (aligned:false) and warns that pre-mapped does not guarantee tradeability. This is rich behavioral context that annotations alone cannot provide, and there is 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?

The description is long but well-structured, starting with a one-sentence purpose, then breaking into modes, response, safety fields, and warnings. Every sentence carries substantive information, especially the detailed compatibility logic and field explanations. It is slightly verbose but appropriate given the tool's complexity and absence of an output schema.

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

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

Without an output schema, the description fully compensates by explaining the response structure (leg-by-leg prices, spread[].top_spreads_pp), safety fields (compatibility_warning, temporal_alignment, skipped_* counters), and edge cases (non-equivalent bet shapes, semantically unrelated topics). It also addresses limitations (pre-mapped ≠ tradeable) and temporal validity, making it complete for an agent to invoke 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% with each parameter described, so baseline is 3. The description adds value by explaining the two modes that tie parameters together (topic vs explicit override) and provides a full list of topic shortcuts. While the schema already includes override details, the description's 'TWO MODES' framing gives contextual meaning beyond each parameter's isolated 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 opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' which clearly states the tool's specific function and distinguishes it from sibling tools like single-venue arbitrage or edge tracking. It names the exact resources (Kalshi and Polymarket) and the action (computing spread), satisfying the 'specific verb+resource' criterion.

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 thoroughly explains the two usage modes (topic shortcuts vs explicit ticker+slug) and provides guidance on interpreting results, including when spreads are real signals versus when compatibility warnings indicate no arb exists. It also cautions that most pre-mapped topics are not tradeable, which helps set expectations. However, it does not explicitly mention alternative sibling tools for different use cases, so it stops short of full when-to-use vs alternatives 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 and destructiveHint=false, so the safety profile is known. The description adds important behavioral context, such as scoping to the user's identifier (anonymous IP, BYO key hash, or account ID) and the ability to list keys by omitting the argument. No contradictions.

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

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

The description is three sentences, front-loaded with the primary action, and every sentence adds value. It covers retrieval, listing, usage context, scoping, and related tools without unnecessary detail.

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

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

For a simple tool with one optional parameter and no output schema, the description is sufficiently complete. It explains the two modes (retrieve/list), scoping, and relationships to remember/forget, fully preparing an agent to invoke it correctly.

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

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

The input schema has 100% coverage for the 'key' parameter. The description adds meaning by explaining the omission behavior (list all keys) and providing examples of what values might be stored (ticker, address, research notes), going beyond the schema's basic definition.

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

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

The description clearly states the tool's function: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It uses a specific verb and resource, and distinguishes from sibling tools by explicitly naming remember and forget.

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

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

It explains when to use the tool: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also provides alternatives: 'Pair with remember to save, forget to delete.' This gives clear usage and relationship to sibling tools.

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

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

Beyond annotations, the description explains the mark_read side effect (flags events as read, affecting future calls), the persisted feed nature, and the return payload structure. This adds valuable behavioral context without contradicting the readOnlyHint/idempotentHint annotations.

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

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

The description is compact yet information-dense, front-loaded with the core purpose, then details each key aspect in separate sentences. Every sentence earns its place, and the alternate endpoint is tacked on without bloating the core message.

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

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

With no output schema, the description compensates by listing the return payload fields. It covers filtering, mark_read side effects, polling, and an alternative access method, making it complete for a read-only list tool with 5 parameters.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning with a concrete type example (sec_8k) and explains the semantic effect of mark_read, which is not fully captured in the schema. However, it does not elaborate on limit or unread_only, so it stops short of a 5.

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

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

The description clearly states the tool pulls fired events from the subscription feed, with specific return details (source, citation_uri, raw payload). It distinguishes itself from siblings like list_subscriptions and recent_changes by focusing on the alert feed.

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 usage context: filtering by type and since, mark_read behavior, and an alternative endpoint for scripts/dashboards. The phrase 'Polls work fine' directly addresses polling, and the mention of the HTTP endpoint gives a clear 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 signal read-only, idempotent, and non-destructive behavior. The description adds substantial behavioral context: fan-out to SEC EDGAR, GDELT→GNews fallback logic, USPTO soft-fail due to PatentsView sunset, and the exact return shape (changes[], total_changes, pipeworx citation URIs). This goes well beyond the annotations.

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

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

The description is dense with value and front-loaded with the core purpose. The run-on sentence style is slightly heavy, but every clause contributes information about sources, fallbacks, or return structure, making the length justified for a multi-source tool.

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

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

Given the absence of an output schema, the description compensates by naming the return fields (changes[], total_changes, pipeworx:// URIs). It covers source routing, failure modes, input formats, and points to entity_profile as an alternative. This is a complete context package for a complex tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description enhances `since` with concrete formats ('2026-04-01', '7d', '30d', '3m', '1y') and suggests '30d' or '1m' for typical monitoring. It also clarifies `value` as ticker or CIK, adding meaning beyond the schema's terse 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 defines the tool as a 'change feed for a company in the last N days/weeks/months' with specific sources (SEC EDGAR, GDELT→GNews, USPTO), and explicitly distinguishes it from entity_profile. The verb+resource+scope is precise and leaves no ambiguity.

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

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

It provides explicit usage guidance: for 'What's new' / 'latest on Y' queries with a time window. It also names an alternative (entity_profile) and explains when NOT to use this tool (static profile needs regardless of window). Additionally it describes fallback behavior (GDELT preferred, GNews on rate limits/5xx), setting clear expectations.

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

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

Adds behavior beyond annotations: scoped by identifier, persistent vs 24-hour retention. Does not mention overwrite semantics, but annotations already indicate idempotency. Consistent 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?

Four sentences, every one earning its place: action, use case, storage mechanics, companion tools. Front-loaded with the core purpose.

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

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

For a simple 2-parameter tool with no output schema, the description covers purpose, when to use, storage semantics, and companion tools. Minor gap: overwrite/update behavior isn't stated, but overall adequate.

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

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

Schema covers both parameters at 100% and includes examples for key and value; description adds value examples but not additional parameter details. Baseline of 3 is appropriate given full schema coverage.

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

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

The description uses a specific verb and resource ('Save data the agent will need to reuse later') and clarifies scope across conversations/sessions. It distinguishes from siblings by naming recall and forget and by describing the key-value store mechanism.

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

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

Explicitly states when to use ('Use when you discover something worth carrying forward') with concrete examples (ticker, address, user preference). It also clarifies persistence differences for authenticated vs anonymous sessions and points to companion tools for retrieval/deletion.

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

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

Annotations already cover read-only, idempotent, and non-destructive. The description adds behavioral context: 'Each call cascades through several lookup endpoints internally,' and it discloses auto-disambiguation for company inputs and the citation URIs returned. This is valuable beyond annotations, though it omits error handling or latency details.

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 efficient, front-loading with examples and purpose. Each section (usage trigger, supported types, return details, internal behavior) earns its place. It is well-structured with clear type breakdowns and no redundancy.

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

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

For a tool with 2 parameters and no output schema, the description is remarkably complete. It explains what each type returns (ticker, CIK, RxCUI, etc.), input variants, citation URIs, and even the underlying multi-endpoint behavior. There is little ambiguity left for the agent.

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

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

While schema coverage is 100%, the description enriches parameter meaning significantly. It explains that 'company' accepts ticker, CIK, or name with auto-disambiguation, and that 'drug' accepts brand or generic name. It provides over-the-top examples like 'AAPL' and 'ozempic', which are not in the schema.

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

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

The description clearly states the tool's verb ('resolve') and resource ('user-spoken NAME to canonical/official identifier'), with concrete example queries. It also distinguishes itself as the go-to tool when a name needs to become an ID, which separates it from siblings like entity_profile or 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?

Explicit guidance is given: 'Use FIRST whenever you have a name but need an ID.' It also notes that it replaces 2-3 manual lookups, implying when it's more efficient. However, it does not explicitly mention when not to use it or name alternative tools for different 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 provide read-only/idempotent hints. The description adds valuable process details: calls ai_visibility_check internally for each entity, ranks by score, treats the first entity as the subject, and returns specific fields (score, confidence, signal density). This goes beyond the structured annotations but doesn't cover all edge cases like rate limits.

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

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

Two sentences plus an illustrative quote. The main verb appears immediately, and every clause adds information: mechanism, ranking, return fields, use case. No tautology or fluff.

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

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

Given no output schema, the description clearly states return format ('ranked list with score, confidence, signal density per entity'), internal mechanism, and the special treatment of the first entity. Complexity is moderate and all key aspects are covered. The example query further contextualizes when to use 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 coverage is 100% with descriptive parameter texts, so the baseline is 3. The description doesn't add significant meaning beyond the schema beyond framing entities as 'your brand + N competitors,' which is already implied by the schema's mention of 'subject.' No extra semantics for models, _apiKey, or context.

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 action 'Compare AI visibility across multiple entities side-by-side,' identifies the internal mechanism (probes with ai_visibility_check), and differentiates from siblings like ai_visibility_check (single-entity vs multi-entity). It names the output type and ranking 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 identifies a clear use case ('competitive AI-marketing audits') with an example query, and implies comparison-oriented usage distinct from single-entity checks. However, it doesn't explicitly state exclusions or when not to use this tool vs 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?

Description adds behavioral context beyond annotations: composite fan-out architecture, partial failure degradation with timing ('bundlephobia's first measurement... can take 5-30s'), and the sources_failed field. No contradiction with readOnly/idempotent/destructive 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 every sentence contributes: purpose, use cases, return fields, ecosystem limitation, and failure behavior. It is front-loaded and achieves high information density 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?

Given the tool's complexity (composite check across two services) and absence of an output schema, the description compensates by listing return fields (is_latest, license, advisory_count, bundle_kb_min, etc.), links, alternative versions, and graceful degradation behavior. This is sufficient for an agent to invoke and interpret results.

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

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

Schema covers 100% of parameters with descriptions for 'package' (npm name, scoped accepted) and 'version' (specific, defaults to latest). The description does not add new parameter-level meaning beyond the schema, so baseline 3 applies.

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

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

The description clearly states a specific verb+resource: 'Composite "should I add this npm package to my project" check in ONE call' and enumerates the data sources (deps.dev, bundlephobia). It distinguishes from siblings like scan_competitor_ai_presence by focusing exclusively on npm package analysis.

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

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

Explicit usage triggers: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides an exclusion/alternative: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.'

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

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

Annotations already mark the tool read-only, idempotent, and non-destructive. The description goes beyond this by disclosing the retrieval mechanism (BGE-base-en embeddings, 500-char overlapping windows), the hard 200K character limit with truncation and flagging, and that returned passages include character offsets for verbatim quote verification. 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 dense but well-organized, front-loading the core action and then layering usage guidance and technical constraints. Every sentence earns its place, though it is slightly long and could be trimmed without losing value; still, structure is effective.

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 wisely explains return values (passages, offsets, similarity scores, truncation flag) and gives input constraints. It also covers integration with a sibling tool, making it self-sufficient for an agent to decide, invoke, 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%, so baseline is 3. The description adds meaningful context: it clarifies 'text' is a previously pulled record (e.g., SEC 10-K), gives concrete query examples, and reinforces that 'limit' controls the number of returned passages. This adds value beyond the schema's minimal descriptions.

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

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

Description opens with 'Semantic search INSIDE a fetched record' and specifies both inputs (text + natural-language query) and outputs (top-N passages with character offsets and similarity scores). It clearly distinguishes itself from sibling tools like ask_pipeworx_grounded by stating it operates inside a single already-fetched record, not over a broader corpus.

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 it: 'Use when the record is too big to cram into the prompt' and contrasts with ask_pipeworx_grounded, saying to 'fetch with the gateway, ground over the relevant passages instead of the whole document.' This gives the agent clear decision criteria and names the complementary 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?

The description contradicts the idempotentHint annotation. It states 'Returns the new subscription id,' implying each invocation creates a new subscription, whereas idempotentHint: true indicates repeated calls should not have additional unintended side effects. This conflict is a clear annotation 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?

Despite being long, the description is dense with essential information. Every sentence covers a distinct aspect: purpose, auth, types, delivery, restrictions, and webhook behavior. It is well-structured and front-loaded with the core purpose.

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

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

The description covers all key aspects: return value (subscription id), authentication requirements, supported types with examples, delivery options, verification steps, rate limits, and webhook failure auto-disable. There is no output schema, but the description provides sufficient information for an agent to use the tool effectively.

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

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

The description goes far beyond the schema by providing concrete examples for each subscription type (e.g., sec_8k with items, polymarket_edge with topic, fred_series with series_id) and detailing delivery channel constraints (verified phone, 10/day cap, webhook signing secret). This adds substantial meaning beyond the property descriptions.

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

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

The description explicitly states 'Create a proactive monitoring subscription to a live-data event stream,' which is a specific verb (create) and resource (subscription). It clearly differentiates from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by focusing on the creation of new monitoring subscriptions.

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

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

The description provides clear context for when to use the tool (proactive monitoring) and details supported subscription types and delivery channels. It does not explicitly name alternatives or when not to use it, but sibling context and the description's scope make the intended usage obvious.

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, open-world, idempotent, and non-destructive behavior. The description adds value beyond that by specifying the output structure (category-bucketed example questions, exact tool + argument shape) and the two calling modes (no args vs. with topic), without contradicting the annotations.

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

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

The description is a dense paragraph, but every sentence earns its place: trigger phrases, output content, calling modes, and usage context. It could be improved by breaking into bullets for readability, but it is concise and free of 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 tool with one optional parameter and no output schema, the description is remarkably complete. It explains the output format (categories, example questions, tool/argument shape), how to call with or without `topic`, and when to use it first, making it fully self-contained for an agent.

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

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

The schema already covers the `topic` parameter with 100% description coverage (explicit list of allowed values). The description augments this with concrete examples ('finance', 'pharma', 'betting') and explains the behavioral difference between omitting and providing the parameter, which goes beyond the schema.

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

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

The description clearly identifies the tool as the 'onboarding entry point' for discovering what Pipeworx can answer, and specifies it returns category-bucketed example questions with the exact tool + argument shape. This verb+resource+scope clearly distinguishes it from sibling tools like ask_pipeworx (for actual questions) and discover_tools (for tool 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 says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools', which provides clear when-to-use guidance and mentions alternatives. However, it does not explicitly state when NOT to use it, so it stops short of full exclusion 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 discloses important behavioral traits beyond the annotations: ownership is enforced (you can only cancel your own subscriptions), the row is deactivated not deleted, and historical events remain available via recent_alerts. These details add significant value beyond the annotations' readOnlyHint, idempotentHint, and destructiveHint, with no contradictions.

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

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

The description is highly concise, front-loaded with the primary verb and object ('Cancel a subscription by id'), followed by two short sentences that add essential behavioral context. Every sentence earns its place, with 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?

Given the low complexity (single parameter, no output schema), the description is nearly complete. It covers the action, ownership constraint, deactivation behavior, and impact on historical data. The only minor gap is the lack of explicit mention of what the tool returns (e.g., confirmation or the deactivated record), but this is not critical for a simple unsubscribe operation.

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

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

The input schema fully describes the single id parameter, including that it is a subscription id returned by subscribe. The description adds minimal parameter-specific meaning, only 'by id' and ownership context. Since schema coverage is 100%, the baseline of 3 is appropriate; the description does not need to compensate.

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: 'Cancel a subscription by id.' It identifies the specific resource (subscriptions) and action (cancel), and the additional context about deactivation distinguishes it from deletion-based alternatives. This is further differentiated from siblings like subscribe and list_subscriptions.

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

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

The usage context is clear: it is the tool for canceling subscriptions. The description implies when to use it via ownership enforcement and deactivation behavior, but it does not explicitly mention alternative tools or when not to use it. However, the implied context is strong enough for an agent to select it correctly.

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, open-world, idempotent, and non-destructive. The description adds substantial behavioral detail beyond these: the structured SEC EDGAR + XBRL fast path with exact percent-delta math, fallback to a grounded pipeline, and the specific verdict types returned. It also notes that it replaces multiple sequential calls, providing useful context without contradicting annotations.

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

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

The description is dense but well-structured: it starts with usage examples, states the core purpose, then details routing and output. Every sentence contributes functional information, with no filler. It is on the longer side but appropriate 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 lacking an output schema, the description clearly communicates return values (verdict types, actual value with citation, reasoning), routing logic, and parameter usage. It covers edge cases like hallucination detection and the default tolerance cap. This makes it complete for a read-only verification 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 with descriptions, so baseline is 3. The description augments schema by explaining tolerance_pct semantics (overrides implied tolerance, capped at 5, useful for hallucination detection) and gives concrete claim examples. This adds meaningful guidance beyond the schema, so a 4 is appropriate.

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

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

Description opens with natural-language query examples and explicitly states 'natural-language claim verification against authoritative sources.' It identifies a specific verb (verify/validate) and resource (claims), and distinguishes itself from siblings by noting it replaces 4–6 sequential calls and handles both financial and non-financial claims.

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

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

Provides explicit when-to-use guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' Also distinguishes between company-financial claims (SEC EDGAR fast path) and other claims (grounded pipeline), giving clear context. However, it does not explicitly name alternative tools to use when not to use this one.

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