guif

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 meaningful context beyond that: it names the free default model (Workers AI Llama-3.3-70b), reveals that passing _apiKey triggers external calls to Anthropic with direct cost to the user, and discloses the return structure. This is valuable behavioral transparency not captured in annotations.

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

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

Three sentences, front-loaded with the main purpose, followed by a cost caveat and return format. No filler words, and every sentence earns its place. The structure is ideal for quick parsing by an AI agent.

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

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

Given there is no output schema, the description's mention of per-model {score, confidence, signals, raw_response} and a combined view is essential and complete. It also provides use cases and the cost/API-key note. It could mention error handling or the exact format of 'signals,' but overall it is sufficient for a relatively simple tool with one required parameter.

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

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

The schema already covers all parameters with meaningful descriptions (100% coverage), so the baseline is 3. The description adds value by specifying the default model name (Workers AI Llama-3.3-70b) and clarifying the conditional nature of _apiKey (only needed with 'anthropic' in models). This goes beyond what the schema states.

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

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

The description uses a specific verb ('Probe'), identifies the resource ('one or more LLMs'), and the outcome ('score visibility 0-100 per model'). It clearly distinguishes from siblings like scan_competitor_ai_presence by focusing on LLM knowledge and scoring rather than web presence. The use-case list reinforces its unique role.

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 mentions when this tool is useful: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It provides clear context but does not explicitly name alternatives or state when not to use it. Since sibling tools like ask_pipeworx or deep_research could overlap, a more explicit exclusion would be stronger, but the intended use cases are well-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 declare read-only/open-world/idempotent; the description adds operational context: 'one fast call', 'works on every tier', and 'stable pipeworx:// citation URIs' for the return format. 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 dense and long, listing many domains and examples; while all content is relevant, it could be tightened. It starts with the key guidance but the sheer length reduces exceptional conciseness.

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

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

Despite lacking an output schema, the description covers return format (structured answer with pipeworx:// citations), when to use, alternatives, and examples, making it fully complete for a single-question tool.

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

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

Schema covers all 6 parameters (question plus aliases) at 100% with descriptions; the description's examples clarify question style but don't add parameter semantics beyond schema.

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

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

The description clearly states the tool routes a natural-language question to one of 5,564 tools across 1,462 sources and returns structured answers with citation URIs. It explicitly distinguishes from siblings like ask_pipeworx_grounded and deep_research.

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

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

It explicitly says 'PREFER OVER WEB SEARCH' and lists trigger phrases ('what is', 'look up', 'find'), then provides alternatives: 'step up only when needed' to ask_pipeworx_grounded or deep_research. Includes concrete examples.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds that it 'currently matches ask_pipeworx exactly' when no candidate is active, which is a minor behavioral note but does not disclose any additional side effects or permissions 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 highly repetitive, stating 'identical universal router' and 'matches exactly' multiple times. It is verbose and could be reduced to a single sentence without losing meaning. The structure is redundant.

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 lacks essential context about the tool's purpose beyond being a beta alternative. It does not explain what kind of questions it handles, what the output is, or any domain-specific information. The tool appears to be a placeholder with minimal contextual detail.

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

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

The schema provides a description for the 'question' field and all aliases are simply 'Alias for question.' The tool description text adds no extra meaning about the parameters. Since schema coverage is complete and the description doesn't improve it, it stays at the baseline.

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

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

The description states it is a 'beta version of ask_pipeworx' and an 'identical universal router', but does not explain what the router actually does or what 'ask' entails. It is vague and relies heavily on the sibling tool's name without describing its function.

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

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

It says 'Use it exactly like ask_pipeworx when you want the newest routing' which gives some context, but it does not explicitly state when not to use it or how it compares to other tools beyond the stable router. The guidance is partial.

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 reveals the extra LLM call cost, the exact success/refusal response shapes, and the concrete refusal reasons. This gives the agent a detailed behavioral contract 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, front-loading the core purpose and then enumerating return/refusal formats and use cases. Some verbosity in listing every refusal reason is justified because there is no output schema to convey that 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?

With no output schema, the description fully compensates by explaining the return envelope, refusal pathways, routing behavior, and cost tradeoff. It is complete for an AI agent to decide when to invoke this tool and what to expect from it.

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

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

Schema description coverage is 100%, with all six parameters documented as aliases for 'question.' The description adds no new parameter-level detail beyond restating that the input is a natural-language question, so the schema carries the semantic burden and the baseline score 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 this as a 'hallucination-resistant answer mode' that routes like ask_pipeworx but extracts answers from tool results. It uses specific language about high-stakes reads and distinguishes itself from the sibling by emphasizing evidence-grounded answers and refusals when data is missing.

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: 'whenever an answer will be quoted, cited, or acted on' and 'must not invent facts.' It also names the alternative, ask_pipeworx, and advises preferring it for casual lookups, making the selection decision clear.

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

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

The description goes far beyond the readOnly/idempotent annotations. It details resolver behavior (market_match_confidence, alternatives, suggestions), safety short-circuits (low_confidence_match, market_closed_or_inactive), tradeability warnings, news fallback mechanisms, and resolution-rule risk (cancellation_rule) with EV impact. This is exceptional behavioral disclosure.

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

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

The description is long but well-structured with clear uppercase section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). Each section earns its place by explaining behavior or response contracts. However, the length is considerable and could be trimmed without losing critical 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?

With no output schema, the description carries the full burden of explaining return shapes. It does so thoroughly: result.market, result.analysis, result.evidence, parent_event, news fields, and status codes. It also covers edge cases like closed markets and wide spreads. This is a complete and contextual description 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 description coverage is 100% as indicated, so the baseline is 3. The description does not add new parameter semantics beyond what the schema already provides (e.g., market formats, depth options, include_raw behavior). It does provide contextual examples that reinforce the schema, but no additional detail.

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

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

The description opens with a specific verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly states the tool's scope (Polymarket bets) and distinguishes it from siblings by focusing on bet-specific research with fan-out to data packs. The 'Use for' examples reinforce the purpose.

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

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

The description explicitly states when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides clear context for Polymarket bet research, but does not explicitly name alternatives or exclusions (e.g., 'for general research use ask_pipeworx'), so it falls short of the 'when-not' criterion.

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 it read-only/idempotent, and description adds behavioral detail: data sources (SEC EDGAR/XBRL, FAERS/FDA), sort order by primary metric, citation URIs, and off-calendar fiscal year handling. 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?

Description is front-loaded with purpose and trigger phrases, and the additional details (data sources, sorting, citations) earn their keep. It is longer than necessary but each sentence provides actionable context.

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 2-parameter tool with no output schema, the description fully specifies inputs, outputs, data provenance, sorting, and citation format. It also addresses edge cases like off-calendar fiscal years, making it self-sufficient despite missing 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 covers both parameters (100%), but description enriches semantics by explaining what each type pulls (10-K metrics vs FAERS/FDA/trial counts) and value constraints (2–5 tickers/names). This goes beyond schema's basic descriptions.

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

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

The description opens with explicit trigger phrases and states 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It clearly distinguishes the tool from siblings by noting it replaces sequential single-pack lookups and is preferred for comparisons.

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

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

Description includes explicit 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides type-specific contexts (company vs drug). This is direct guidance on when to choose this tool over alternatives.

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

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

Annotations already declare readOnly/idempotent/non-destructive. The description adds substantial behavioral context: account/paywall, parallel decomposition across 5,564 tools, findings packet with gaps[] and contradictions[], never-invent policy, hop semantics, time expectations, excerpting behavior, and citation fetchability. 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 (~250 words) but densely packed with essential information, front-loaded with account prerequisites and usage alternatives. Every sentence adds value, though some redundancy exists between the depth descriptions in the text and the schema. Given the tool's complexity, the length is justified.

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

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

There is no output schema, so the description must explain return values. It fully describes the findings packet: verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], hop field, and time expectations. All critical behavioral aspects for an agent are covered.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds context for question (decomposition is the point) and depth (time expectations, paid thorough) but does not fundamentally change parameter understanding. Since the schema already documents parameters well and description adds useful nuance, 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?

Description clearly states the tool's purpose: 'Grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources' and explicitly distinguishes it from siblings: 'For a single lookup use ask_pipeworx' and 'For BREAKING... prefer ask_pipeworx'. The verb 'research' plus the specific resource make the purpose unambiguous.

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

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

Explicit usage guidance is provided: 'Best for broad/multi-part questions over structured data' with named alternatives for single lookups and breaking news. It also warns about account requirements and suggests ask_pipeworx for unauthenticated users. This is exemplary guidance for tool selection.

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

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

Despite strong annotations (readOnly, idempotent, non-destructive), the description adds valuable behavioral detail: returns top-N relevant tools with names, descriptions, and full input schemas with curated examples, and that results are ready to call directly without a second lookup. This goes beyond annotations and enriches the agent's understanding of the tool's behavior.

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 and entirely purposeful. The first sentence states the core function, and the second covers usage, return format, and actionability. No wasted words, and the most critical information is front-loaded.

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

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

The description fully covers what an agent needs: when to use it, what it returns, and why it's beneficial (no second schema lookup). There is no output schema, but the description compensates by explaining the result format in sufficient detail. The tool is simple enough that this is complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds no parameter-specific semantics beyond what the schema already provides (e.g., aliases, default limit). It mentions example queries but doesn't explain parameter behavior beyond the schema. Thus, it meets the baseline but doesn't exceed it.

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

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

The description clearly states the tool's function: 'Find tools by describing the data or task.' It distinguishes itself from sibling tools by being a discovery/browsing tool rather than a domain-specific search (e.g., search_species, search_within). The verb 'find' is specific and the resource ('tools') is unambiguous.

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

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

The description provides explicit usage context: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' It clearly indicates when to use it 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?

The description adds significant behavioral detail beyond annotations: it discloses the fan-out across multiple sources, the soft-fail for the patents API ('USPTO PatentsView API sunset May 2025 — soft-fails until reactivated'), and the GDELT→GNews fallback chain. This goes far beyond the readOnly/openWorld hints.

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

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

The description is longer than average but every sentence carries useful information, from example utterances to data sources and return fields. It is front-loaded with the core purpose and usage, though some detail (e.g., specific return field names) could be seen as slightly dense.

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

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

Despite no output schema, the description fully enumerates the return fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI) and important behavioral caveats. For a complex fan-out tool, this is remarkably 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?

The input schema already provides 100% coverage for both parameters. The description adds practical examples ('AAPL', '0000320193') and reinforces the zero-padded CIK requirement, which is helpful but not strictly new semantic info.

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: 'full cross-source profile of a US public company in ONE parallel call.' It provides concrete example queries and distinguishes itself from siblings like resolve_entity and compare_entities by specifying its holistic, cross-source nature.

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 instructs when to prefer this tool ('ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view') and when not to use it ('names not supported — use resolve_entity first if you only have a name'). This is outstanding 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 destructiveHint=true and idempotentHint=true. The description confirms destructive behavior ('Delete... clear sensitive data') but adds minimal extra context beyond the annotations. It doesn't discuss edge cases like missing keys or irreversibility, though annotations cover the core safety profile.

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

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

Two sentences, front-loaded with the primary action, no wasted words. The conditional usage guidance and pairing note are concise and add value without clutter.

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 deletion tool with strong annotations, the description covers the essential context: what it does, when to use it, and how it relates to sibling tools. No output schema is needed for a delete operation, and the schema fully documents the parameter.

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

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

The input schema has 100% coverage, with the parameter 'key' described as 'Memory key to delete.' The description does not add further semantic detail about the parameter, but the schema is already clear, so a baseline score of 3 applies.

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

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

The description clearly states the tool's function: 'Delete a previously stored memory by key.' It uses a specific verb (delete) and resource (memory), distinguishing it from siblings like 'remember' (store) and 'recall' (retrieve).

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 provides usage context: 'Use when context is stale, the task is done, or you want to clear sensitive data.' Also names related tools to pair with ('Pair with remember and recall'), offering practical guidance for when to use this tool versus alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds process transparency by stating it fetches the page, extracts metadata, and emits a text blob, including the output format and destination. 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 compact yet complete: three sentences covering what, how, and when to use. It is front-loaded with the primary action and includes no redundant phrases.

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 states the return format ('single text blob ready to drop at site-root/llms.txt') and explains the workflow. With only two parameters and clear annotations, this is fully complete for an agent to invoke correctly.

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

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

Schema description coverage is 100% for both parameters (url and max_links), each with clear descriptions. The description does not add parameter-level detail beyond that, 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 opens with a specific verb+resource: 'Generate a production-ready llms.txt file for any URL', immediately clarifying the tool's unique function. It further details the process ('Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format') and distinguishes it from siblings, which range across research, entity, and subscription tools.

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

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

Explicit use cases are listed: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' This provides clear context for when to use the tool, though it does not mention exclusions or alternative tools.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds useful behavioral context beyond that, such as automatic name resolution and the ability to narrow results geographically. It does not contradict any annotations.

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

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

The description is concise and front-loaded: the first sentence states the primary purpose, the second explains the alternative identifier inputs, and the third covers the optional filter. No unnecessary words or redundant 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?

With a rich output schema and annotations, the description covers the essential usage aspects. However, it does not specify what happens if neither `name` nor `key` is provided, which could be ambiguous given that no parameters are required. This minor gap prevents a perfect score.

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

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

The schema already provides 100% description coverage for all parameters, giving a baseline of 3. The description adds value by clarifying the either/or relationship between `name` and `key` and illustrating usage with examples, which goes beyond the individual parameter descriptions.

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

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

The description clearly states the tool's function: retrieving georeferenced observation records for a species, including coordinates, dates, and sources. This distinguishes it from sibling tools like get_species (taxon info) and occurrences_near (spatial proximity) by specifying the resource and data type.

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

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

The description provides clear usage context: it explains the two alternative input modes (`name` or `key`) and the optional country filter. However, it does not explicitly mention when to prefer this tool over siblings or any exclusions, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds value by promising 'Returns all ranks and accepted name status', giving the agent concrete behavioral expectations 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?

Two sentences, no fluff. The first sentence states the core function, the second adds the prerequisite and return content. Entirely front-loaded and every word 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?

With an output schema present and only one simple parameter, the description fully covers the tool's purpose, prerequisite, and return characteristics. No necessary context is missing for correct invocation.

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

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

Schema coverage is 100% (key described as 'GBIF taxon key'). The description adds meaning by stating the key comes from search_species, which is crucial for the agent to know how to obtain the parameter value.

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

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

The description uses a specific verb and resource: 'Get complete taxonomic classification for a species (kingdom through subspecies).' It clearly distinguishes this from sibling tools like get_occurrences and search_species by focusing on taxonomy ranks and accepted name status.

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 a prerequisite: 'Requires taxon key from search_species', which tells the agent when this tool is relevant (after obtaining a key). However, it does not explicitly exclude alternatives or mention when not to use it, so it's clear context without 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that it returns the caller's subscriptions and lists specific fields, providing context about scope and response beyond the annotations.

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

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

Three sentences, each with a distinct purpose: the first states the action, the second lists the return payload, and the third gives usage guidance. No wasted words or redundancy.

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

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

For a simple read-only list tool with well-covered schema and annotations, the description provides all essential context: what it returns, scope, and when to use it. It is fully adequate for an agent to select and invoke the tool correctly.

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

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

The schema provides 100% coverage for the single optional parameter include_inactive, clearly describing its meaning and default. The description does not add parameter-specific details, but none are needed given the schema's completeness.

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

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

Clearly states 'List the caller's active subscriptions' with a specific verb and resource. Distinguishes from sibling subscribe/unsubscribe tools by being a read-only listing operation, and enumerates the returned fields for full clarity.

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

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

Provides explicit use cases: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This gives actionable guidance and implicitly contrasts with subscribe/unsubscribe, making the tool's role clear.

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

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

Annotations already declare readOnlyHint and idempotentHint, and describe returns georeferenced records with fields (species name, date, locality, source), adding value beyond the schema. The openWorldHint suggests non-exhaustive results, but the description does not explicitly address that nuance; still, it adds meaningful context for a read-only tool.

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

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

The description is three sentences, front-loaded with the core purpose, then usage guidance, then return details. Every sentence earns its place with no filler or repetition, making it highly scannable.

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

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

For a 6-parameter tool with no output schema, the description covers purpose, preferred queries, filtering via taxon_key, and return contents. It could explicitly acknowledge the openWorldHint (e.g., that results may not be comprehensive) but overall it is 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?

Schema description coverage is 100%, so the baseline is 3. The description adds examples for taxon_key (212=birds) and mentions the taxon_name alternative indirectly via 'from search_species', but these details are also present in the schema. It reinforces semantics without adding substantial new meaning beyond the schema.

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

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

The description opens with a specific verb and resource: 'Find species occurrence records NEAR a location (latitude/longitude + radius).' It distinguishes the tool from siblings by using 'PREFER' and giving representative queries ('what species/wildlife are found near here'), which differentiates it from tools like get_occurrences or search_species.

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 names preferred use cases ('PREFER for...') and even gives example phrasings. It also hints at the relationship to search_species ('from search_species') for obtaining a taxon key. It stops short of explicitly naming competing tools or stating when not to use it, but the guidance is clear and actionable.

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

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

Although annotations only provide negative hints, the description discloses rate limiting ('5 per identifier per day'), free/no-quota behavior, daily digest reading, and the conditional claim_token return. It also reveals dual-mode behavior (filing vs. reading status via claim_token) and warns not to paste end-user prompts, adding substantial behavioral context beyond annotations.

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

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

The description is long but information-dense and front-loaded with the core action. Most sentences add unique value (rate limit, server boundary, claim_token workflow, team usage); no redundant filler. Slightly verbose but appropriate for the tool's dual write/read behavior and multiple constraints.

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 compensates by explaining the claim_token return path and how to query resolution status. It also covers the main context an agent needs: scope restriction, rate limits, and message content guidance. It does not detail the full response shape when an account is present, but is otherwise sufficiently complete for this low-complexity 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 all four parameters at 100%, so baseline is 3. Description adds operational semantics: message should specify tool/error and avoid pasted prompts; claim_token must be passed alone with no other arguments; context fields are for pack/tool/vertical. This extra guidance justifies above schema alone.

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

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

Description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' clearly identifying the tool's action and resource. It further distinguishes it from sibling tools by restricting to Pipeworx-owned tools and explaining the claim_token lookup mode, so the purpose is both specific and differentiated.

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

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

Description explicitly maps when to use: bug for wrong/stale data, feature/data_gap for missing tools, praise for success. It also gives a clear exclusion: do not report issues from a different MCP server, and directs users to file with that server instead, which is strong 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?

The annotations already establish read-only, idempotent, non-destructive safety. The description adds valuable context about the data being aggregated (from CF analytics-engine), the absence of PII, and caching behavior (5min-1h). This goes beyond what annotations provide, though it doesn't detail the exact response shape or potential edge cases.

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 efficiently organized: a one-line summary, a bullet-style list of use cases, and a concise behavioral note. Every sentence serves a purpose and there is 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 simple read-only tool with one optional parameter and no output schema, the description adequately explains the return values (top tools, packs, counts), data source, and freshness. It leaves no critical gaps for an agent to misuse the tool.

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

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

The schema covers 100% of the parameter information, including enum values and their semantics. The description only echoes the window values without adding new detail, so it meets the baseline but doesn't exceed it.

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

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

The description uses a specific verb 'Returns' and clearly identifies the resource (Pipeworx trending data). It distinguishes itself from sibling tools like discover_tools by focusing on what agents are currently calling rather than a general directory. The phrase 'What other AI agents are calling on Pipeworx right now' immediately clarifies the tool's unique niche.

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 enumerates three concrete use cases, giving clear context on when to leverage this tool. However, it does not explicitly mention exclusions or name alternative tools for cases where this tool would not be appropriate.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses many behavioral details: >3pp threshold emits a BUY/SELL EVERY LEG signal, >20% placeholder fraction returns null arb signal, skipped_low_similarity surfaces rejected pair count, and fill_check prices against live CLOB depth with a 'do not trade it' condition when 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 front-loaded with purpose and mode selection, then uses uppercase labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) to organize dense details. It's long, but each section adds essential information for this complex tool; no wasted sentences.

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 steps up by documenting the response shape: opportunities[] fields, partition_check object, and fill_check results. It covers mode-specific behavior, failure conditions (placeholder count, zero realizable edge), and recommends a sibling tool for custom sizing, making it highly complete for the tool's complexity.

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

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

Schema coverage is 100%, but the description adds significant meaning: it provides concrete slug examples ('fed-decision-may-2026'), explains what each mode does ('walks child markets, checks date-axis / threshold-axis ordering'), and reveals the no-args 'trending_scan' behavior. This exceeds the schema descriptions.

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

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

The description opens with a specific verb-resource pairing: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes three invocation modes (trending_scan, event, topic) and references sibling tools like polymarket_fill_risk for custom sizing, so the purpose is 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 explicitly instructs when to call with no args ('trending_scan'), when to pass `event` ('recommended for a specific market'), and when to pass `topic` ('for cross-event scanning'). It also points to polymarket_fill_risk for custom sizing, but doesn't explicitly enumerate when not to use this tool versus other siblings, so it's just short of a 5.

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

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

The description goes far beyond annotations (readOnly, idempotent, non-destructive) by detailing response segments, model families, Kelly caps, slippage handling, 24h-move warnings, caching behavior, diagnostics, and even the unreliability of Fed signals. This gives an agent deep insight into what the tool actually does and what to expect, with no contradiction to annotations.

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

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

The description is long and dense, but well-structured with sections for model families, segments, knobs, and response format. It is front-loaded with the core purpose and then provides necessary detail for a complex tool. While some redundancy exists (e.g., by_segment repeated), the complexity justifies the length. Still, it could be tightened.

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

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

Given no output schema, the description fully explains the return values: by_segment contents, per-opportunity fields (edge_pp_net, kelly_fraction, liquidity, spread_pp, volume), diagnostics, and fed_candidates/fed_note. It also covers caching, filter behavior, and how knobs affect output. This is comprehensive coverage for an agent to understand 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?

Schema coverage is 100%, but the description adds critical non-obvious semantics. It explains the tradeable-edge knobs (min_liquidity, max_spread_pp), why min_kelly does not filter partition arbs (they return kelly_fraction_half=0 at parent level), and that min_partition_leg_kelly applies per-leg. This interplay is not visible in the schema descriptions and is essential for correct parameter usage.

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

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

The description opens with a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly states the tool's purpose and output. However, it does not explicitly distinguish itself from sibling tools like polymarket_arbitrage or polymarket_edge_tracker by name, though the unique model families and 'what should I bet on today' imply a discovery use case.

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

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

Provides an explicit when-to-use statement: "Built for 'what should I bet on today' — agents discover opportunities without paging hundreds of markets." It also explains exclusions (e.g., placeholder-slug filters, Fed bets excluded from ranking) and why segments might be empty. However, it never names alternative tools or says 'use X instead,' so it stops short of full alternative guidance.

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

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

Beyond the read-only and idempotent annotations, the description discloses important limitations: 60-day snapshot TTL, snapshot start date, daily close data (not intraday), and gaps in snapshots due to cache-miss writes. This goes well beyond the annotations and clarifies behavioral nuances.

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

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

The description is well-structured with front-loaded purpose followed by Args, RESPONSE, and LIMITS sections. It is lengthy but necessary due to the complex response format and constraints; every sentence adds value, though it could be slightly tightened.

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 thoroughly details the response structure: tracked[], expired[], and snapshot_dates[], including trend categories, decay calculation, and edge direction semantics. It also covers data freshness and computational caveats, making it highly complete for a tool of this complexity.

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

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

The input schema already provides full descriptions for both parameters (days and window) with defaults and ranges. The description merely repeats the default values and adds 'snapshot family' context, providing minimal additional meaning beyond the schema.

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

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

The description clearly states the tool tracks edge persistence and decay from daily snapshots, answering 'how long has this edge existed and is it shrinking?'. It distinguishes itself from sibling tools like polymarket_edges by emphasizing historical time-series behavior rather than current edges.

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 strong context for when to use the tool (to compare fresh vs. old edges and assess decay), and implies it is an alternative to polymarket_edges for historical analysis. However, it does not explicitly name alternative tools or state when not to use it, so it falls just 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?

Beyond the annotations (read-only, idempotent), the description discloses extensive behavior: how it walks the ladder, what outputs to expect, the verdicts (clean|degraded|cannot_fill), and the critical nuance that partial basket fills convert an arb into an unhedged directional position. It also details per-mode semantics for size_usd, which is not in 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 long but dense, with each sentence adding technical or usage value. It is structured into single-market and basket sections, with a final usage directive. However, a visual break or bulleted list would improve scannability, and some repetition (e.g., explaining size_usd twice) could be trimmed.

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

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

Given no output schema, the description fully lists the returned fields for both modes, including edge cases like thin_legs[], forced_directional_risk, and max_clean_notional_usd. It also covers the tool's role in the broader workflow (pre-trade risk check for arbitrage and edge signals), making it self-contained 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?

Even though schema coverage is 100%, the description adds semantic depth by explaining how size_usd is interpreted differently across modes ('max spend on buys, target proceeds on sells' vs 'settlement notional S (shares per leg)'). It also clarifies the auto-default behavior for side in basket mode, which enriches the schema 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 opens with a specific verb and resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes this from siblings by defining two modes (single-market and basket) and naming the exact outputs, making the tool's function unmistakable.

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

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

The description explicitly states when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It names sibling tools, gives a threshold, and explains why (theoretical overround on thin books is not capturable), providing both positive and negative usage context.

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

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

Annotations only state readOnly, openWorld, idempotent, and non-destructive hints. The description adds extensive behavioral detail: response structure (leg-by-leg prices, top_spreads_pp), safety fields (compatibility_warning, matched_pairs, temporal_alignment), and skipped_cross_type/subtype counters. It even notes that 'most pre-mapped topics return compatibility_warning today,' providing crucial operational insight 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 well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS). Each sentence carries operational information, and the density is justified by the tool's complexity and absence of an output schema. It could be trimmed slightly, but the organization prevents it from feeling bloated.

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 response structure and all edge cases, including temporal alignment, matched pairs, and skipped cross-type/subtype. It also covers limitations of pre-mapped topics. This is a complete usage guide for a complex comparison 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%, with each parameter described in the schema, so baseline is 3. The description adds value by explaining the relationship between parameters: explicit tickers override the topic-mapped side, and topic provides pre-mapped shortcuts. This combinational semantics is not stated in the schema alone.

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

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

The description opens with a specific statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This clearly identifies the tool's function and distinguishes it from sibling tools like polymarket_arbitrage. It further elaborates on two modes, making the purpose unambiguous.

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

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

The description explains two operation modes (topic shortcuts vs. explicit tickers) and when each is appropriate. It explicitly warns that most pre-mapped topics return compatibility_warning and that 'pre-mapped ≠ tradeable,' guiding the user on when the tool may not be useful. It does not name alternative tools, but it clearly delineates usage boundaries.

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

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

Annotations already establish the read-only, idempotent, non-destructive safety profile. The description adds valuable behavioral context by explaining scoping ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the listing behavior, going beyond what annotations provide. Minor gap: does not specify behavior on missing keys, but that's not essential given the lack of output schema.

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

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

Three sentences deliver the core action, usage guidance, scope, and companion tools without fluff. The most important information is front-loaded, making it easy for an agent to skim and decide.

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, no output schema, and strong annotations, the description fully covers the necessary context: what it does, when to use it, how it scopes data, and how it relates to siblings. No critical information is missing for 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 already documents the sole parameter 'key' with a description that includes the omit-to-list-all behavior (100% coverage). The description restates 'omit the key argument' but adds no new parameter meaning beyond the schema, so the baseline of 3 applies.

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

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

The description uses a specific verb ('retrieve') and names the resource ('a value previously saved via remember'), and explicitly mentions the ability to list all saved keys. It clearly distinguishes itself from sibling tools like remember and forget by positioning itself as the lookup counterpart.

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

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

Provides concrete use cases ('the user's target ticker, an address, prior research notes') and explicitly states when to use it ('without re-deriving it from scratch'). It also names companion tools for related operations ('Pair with remember to save, forget to delete'), effectively framing the when-to-use 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?

The description states 'Set mark_read:true to flag returned events read so the next call only shows newer ones,' which is a persistent state change. This directly contradicts the annotation readOnlyHint: true, making this an annotation contradiction. Despite other helpful details, the contradiction requires a score of 1.

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

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

The description is reasonably compact: four sentences, each serving a purpose (what it returns, how to filter, mark_read behavior, alternate access). It is front-loaded with the primary action and avoids filler, though slightly longer than the most concise 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?

For a read-oriented tool with no output schema, the description adequately covers return fields, filter options, read state management, and alternate access. It doesn't repeat schema details about limit/unread_only but is complete enough. The annotation contradiction slightly undermines completeness, but the functional description remains solid.

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

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

The schema already provides 100% parameter coverage with clear descriptions. The description adds extra value by giving a concrete example for type ('sec_8k'), clarifying since as ISO timestamp, and explaining the cross-call effect of mark_read. This goes beyond the schema's individual parameter descriptions, so it earns above baseline.

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

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

The description opens with a specific verb+resource combination: 'Pull fired events from your subscription feed.' It clearly differentiates from sibling tools like list_subscriptions (which lists subscriptions themselves) and other query tools by focusing on recent alerts from a persisted 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?

The description provides clear usage context: filtering by type and since, using mark_read to advance the feed, and polling. It also mentions an alternative HTTP endpoint for scripts/dashboards. It does not explicitly exclude other tool alternatives, but the context is sufficient for an agent to know when to call 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?

The description goes far beyond the annotations (readOnly, idempotent) by exposing fallback behavior (GDELT preferred, GNews on rate-limit/5xx), a known API sunset (USPTO PatentsView soft-fail), and return structure (changes[] grouped by source, total_changes count, citation URIs). This gives the agent crucial behavioral expectations without any ambiguity.

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 earns its place. It opens with natural language queries, then lists sources, parameter behavior, return shape, and an alternative tool, all without redundancy. Despite its length, it is tightly structured and front-loaded with the most important usage cues.

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, time window parsing) and the absence of an output schema, the description provides a complete mental model. It explains the input formats, the output structure, source-specific caveats, and when to choose a different tool. No critical information is missing for 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?

Even though the schema already covers all parameters (100% coverage), the description adds valuable context beyond the schema: it explains `since` accepts ISO or relative shorthand with concrete examples and recommends "30d" or "1m" for typical monitoring. It also clarifies that `value` can be a ticker or zero-padded CIK. This enriches the parameter semantics meaningfully.

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

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

The description clearly states the tool's purpose: a change feed for a company in the last N days/weeks/months. It uses multiple natural language triggers ("What's new", "latest", "updates") and specifies the scope (companies, time window). It distinguishes itself from entity_profile by explicitly noting that entity_profile provides the static profile.

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

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

The description provides explicit usage context with query examples and states when to use an alternative: "Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window." It also highlights the benefit of one parallel call, making it clear this is for dynamic changes over a time window.

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 mutability, idempotency, and non-destructiveness. The description adds meaningful context: key-value pairs scoped by identifier, persistence for authenticated users, and 24-hour retention for anonymous sessions. This goes beyond annotations without contradicting them.

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

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

The description is front-loaded with the primary purpose and uses several sentences, but each sentence adds distinct value (use cases, persistence behavior, companion tools). It could be slightly tightened, but there is no fluff.

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

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

For a simple two-parameter tool with no output schema, the description covers purpose, usage context, persistence semantics, and related tools. It is complete enough for an agent to select and invoke correctly, though it omits explicit overwrite behavior, which is partially covered by the idempotent hint.

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 includes example keys and values. The description only reinforces the key-value pairing and adds the 'scoped by identifier' detail, but it does not significantly enhance parameter semantics beyond what the schema already provides.

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

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

The description opens with a specific verb and resource: 'Save data the agent will need to reuse later.' It clearly states the tool's role as the write counterpart to recall and forget, and includes concrete examples of what to store, distinguishing it from sibling tools.

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

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

It provides explicit when-to-use guidance with examples ('a resolved ticker, a target address, a user preference, a research subject') and explicitly mentions paired tools recall and forget for retrieve/delete, guiding the agent on the full workflow.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds substantial value beyond those: graceful degradation if GLEIF/OpenFIGI are unavailable, internal cascading through multiple endpoints, explicit labeling of identifier sources, and an 'unresolved' field for identifiers that could not be resolved. This provides rich 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 front-loaded with practical example queries, making the purpose immediately clear. It is somewhat verbose but every sentence adds meaningful detail. A slightly more concise version could remove some redundant phrasing 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?

There is no output schema, so the description must explain return values. It does so thoroughly: for company, it lists CIK, ticker, company_name, LEI, FIGI with labeling and unresolved handling; for drug, it lists RxCUI, ingredient, brand, and citation. This fully covers what the agent can expect, making the tool usage unambiguous.

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

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

Schema coverage is 100%, but the description significantly enriches parameter meaning with examples (e.g., 'AAPL', '0000320193', 'ozempic'), specific format notes (ISIN like 'CH0038863350' resolves to legal entity), and clarifies acceptable input types (ticker, CIK, ISIN, or company name for company; brand or generic name for drug). This exceeds the schema's basic descriptions.

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

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

The description opens with clear example queries like 'What's the ticker for...' and explicitly states the purpose: resolve a user-spoken name to canonical/official identifiers required by other tools. It details the two supported entity types (company, drug) with specific outputs, making it distinct from siblings like compare_entities or entity_profile.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' providing clear guidance on when to use the tool. It does not list specific when-not-to-use scenarios or alternative tools, but the sibling context and the tool's role as a resolver imply it's the first step before deeper actions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description goes beyond annotations by explaining the probing workflow (per-entity calls to ai_visibility_check), the external API call to api.anthropic.com per probe when _apiKey is provided, and the ranked list output with score, confidence, and signal density. This adds meaningful behavior 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 concise and front-loaded with the primary action. It uses a short example in quotes and has no filler. Every sentence contributes to understanding purpose, usage, or output.

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 not having an output schema, the description enumerates the return fields (score, confidence, signal density) and outlines the internal process. It covers the key behavioral context, including the _apiKey prerequisite and the entity count range (2-8) in the schema. For a tool of this complexity, the description is sufficiently complete.

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

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

Schema covers 100% of parameters with detailed descriptions. The description adds semantic value by noting that the first entity is treated as the 'subject' for the narrative and the rest as competitors, which is not in the schema. It also explains the relationship between models and _apiKey, and that context is shared across all probes.

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

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

Description uses specific verb 'Compare' + resource 'AI presence', states that it probes multiple entities, ranks by score, and surfaces most/least recognized. Provides a concrete example ('does Claude know about us as well as our competitors?'). This clearly distinguishes it from sibling tools like ai_visibility_check (likely single-entity) and compare_entities (generic comparison).

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

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

Explicitly frames the tool for 'competitive AI-marketing audits' and shows a realistic use case. It also reveals that the tool internally calls ai_visibility_check per entity, implying that ai_visibility_check is for single-entity checks. This gives clear context on when 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?

Beyond the readOnly/idempotent annotations, the description discloses latency behavior ('bundlephobia's first measurement ... can take 5-30s'), partial failure degradation ('sources_failed will list it if it times out, the rest still returns'), and return structure. It also reveals the fan-out architecture across two services, which annotations alone don't convey.

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

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

Every sentence carries functional value: purpose, usage, return fields, ecosystem scope, and error handling are all covered without redundancy. The dashes and semicolons create a scannable structure despite the density.

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 to lean on, the description fully inventories returned data (summary fields, advisory details, links, alternative versions). It covers ecosystem constraints, failure modes, and timeout behavior, making it a complete guide for an agent calling this tool.

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

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

Schema coverage is 100% with the package and version params already fully described. The description adds no new parameter-level detail—the ecosystem limitation and scoped-package support are already in the schema—so the baseline 3 is appropriate.

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

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

The description opens with 'Composite ... check in ONE call' and clearly specifies the resource (npm package) and the two data sources (deps.dev and bundlephobia). It distinguishes itself by noting 'NPM ecosystem only in v1' and pointing to deps.dev:version for other ecosystems, making its scope obvious.

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

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

Explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also gives an exclusion: for PyPI/Maven/Cargo/Go, fall under deps.dev:version directly. 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 declare readOnly, openWorld, idempotent, and non-destructive behavior, lowering the bar. The description adds useful context beyond the annotations by explaining what the search returns (rank, classification status, taxonomic hierarchy) and the name-matching behavior. This extra behavioral detail justifies a score above 3, though it stops short of a 5 by not addressing pagination or edge cases.

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 purpose, and every sentence earns its place. It includes the input type, return value, and a follow-up recommendation 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?

Given the tool's simplicity (2 params, output schema present, strong annotations), the description is complete. It covers purpose, input semantics, output highlights, and the recommended next step, leaving no critical gaps. The output schema handles detailed return structure, so the description need not elaborate further.

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

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

Schema description coverage is 100%, with both 'query' and 'limit' fully described in the schema. The description adds no new parameter-specific semantics; it only restates that search is by name. Therefore, the baseline score of 3 is appropriate since the schema does all the heavy lifting.

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

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

The description uses a specific verb ('Search for species') and specifies the resource ('species by common or scientific name'), clearly distinguishing this tool from siblings like get_species. It also states the return value (matched taxa with rank, classification status, and taxonomic hierarchy) and names get_species as the follow-up for full details.

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 guides the user to 'Use get_species with the taxon key for full details,' providing a clear next step and alternative. This differentiates when to use this search tool versus a more detailed lookup tool, satisfying the when-to-use/alternative requirement.

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?

Goes far beyond annotations by disclosing implementation details: 'BGE-base-en embeddings + cosine over 500-char overlapping windows; cap is 200K chars (longer inputs are truncated and flagged).' Also explains output structure includes character offsets and similarity scores. 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?

Three sentences, each earning its place: purpose, usage scenario, and technical details. Front-loaded with the core function, followed by when-to-use and operational specifics. No superfluous wording.

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

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

Despite no output schema, the description explains return values ('top-N passages with character offsets and similarity scores'), operational limits, and integration with ask_pipeworx_grounded. Covers all major aspects needed 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?

Schema coverage is 100%, so baseline is 3. The description adds meaningful context beyond schema by emphasizing 'text you already pulled' (clarifying it's not a URL) and providing natural-language query examples like 'supply-chain risk'. The 200K cap is in schema, but truncation behavior adds value.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' with a specific verb and resource. It distinguishes itself from siblings by emphasizing operation on already-fetched text, not external sources. Examples like SEC 10-K body and article further clarify 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?

Explicitly states when to use: 'Use when the record is too big to cram into the prompt' and pairs with ask_pipeworx_grounded, explaining the workflow: 'fetch with the gateway, ground over the relevant passages instead of the whole document.' This provides clear context and alternatives.

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

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

Adds valuable behavioral context beyond annotations: account requirement, feed always on, phone verification, SMS cap. It does not contradict the annotations (readOnly=false, idempotent=true, destructive=false) and enriches them with operational 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 well-structured, leading with purpose, then return, requirements, types, and delivery. Every sentence adds specific, non-redundant value, and it remains readable despite its length.

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 (3 params, nested objects, no output schema), the description covers return value, prerequisites, supported types, and delivery options. The schema fills in remaining param details, making this description complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds concrete examples (e.g., items:["5.02"] = officer change, params:{topic:"fed"}) and clarifies delivery behavior (phone verification, cap), going beyond the schema's basic descriptions.

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

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

The description opens with a specific verb+resource: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly distinguishes this from sibling tools like list_subscriptions and unsubscribe, and states the return value (new subscription id).

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 usage context, including a required OAuth account, supported subscription types, and delivery channel options. It does not explicitly name alternative tools (e.g., use list_subscriptions to view existing), but the context is sufficient for selecting this tool over siblings.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context about the output (category-bucketed examples with tool shapes) and the two modes (no arguments for full spread, or a topic for focus), and mentions data is drawn from the live catalog. 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 longer than strictly necessary but well-structured: it opens with example queries, explains the return value, then parameter options, and ends with usage guidance. Every sentence contributes useful information, though the front-loaded list of example queries adds length without affecting clarity.

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 purpose, output content, parameter behavior, and when to use it. With no output schema, it carries the burden of describing the return format and does so clearly, mentioning category-bucketed examples, tool+argument shapes, and the live catalog source. It is complete for a tool of this complexity.

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

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

The only parameter `topic` is fully described in the schema with all allowed categories and the default behavior. The description also mentions topic examples ('finance', 'pharma', 'betting'), but these are redundant with the schema description. Since schema coverage is 100%, the description adds no new semantic meaning, giving a baseline 3.

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

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

The description clearly states the tool returns category-bucketed example questions, each with the exact tool and argument shape that answers it, drawn from the live catalog. It also identifies itself as the 'onboarding entry point', distinguishing it from sibling tools like discover_tools by focusing on what to ask rather than 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', providing strong usage context. It names meta-tools as the learning target, but does not explicitly exclude alternatives like discover_tools, so it falls just short of a 5.

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

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

The description adds significant behavioral context beyond annotations: ownership is enforced, and the operation deactivates rather than deletes, preserving historical events. This clarifies the soft-delete behavior and the ownership precondition, which are not fully inferable from the annotations alone.

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

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

The description is concise, with two sentences. The core action is front-loaded ('Cancel a subscription by id'), and the second sentence efficiently conveys important caveats 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 one-parameter mutation, the description covers the action, ownership enforcement, and the post-condition (deactivation, events preserved). It also ties to recent_alerts, providing a complete picture despite lacking an output schema or return type.

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

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

The schema already fully describes the id parameter, and the description adds a usage constraint (ownership) that affects parameter validity. While the baseline is 3 due to 100% schema coverage, the ownership note provides added semantic value beyond the schema.

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

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

The description clearly states the tool's purpose: 'Cancel a subscription by id.' It uses a specific verb and resource, and distinguishes itself from siblings by noting ownership enforcement and the deactivation (not deletion) behavior, which sets it apart from 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 description provides clear context for when to use the tool ('Cancel a subscription by id') and notes ownership constraints, implying that only the owner can use it. It does not explicitly name alternatives or when-not scenarios, but the reference to recent_alerts and the deactivation behavior gives useful guidance on the tool's effect.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds critical behavioral context beyond this: the structured vs. grounded pipeline distinction, the exact meaning of 'could_not_verify' (check did not happen) versus 'unsupported' (no source), and the explicit warning that could_not_verify must not be treated as evidence. This is valuable error semantic disclosure.

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: triggers, routing, return values, and a crucial error-handling caveat. It is longer than minimal, but every sentence contributes meaningful operational detail. It earns a 4 for high information density without excessive verbosity.

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 takes on the burden of explaining return values—it does so clearly, listing the possible verdicts, the grounded/structured actual value with pipeworx:// citation, and reasoning. It also covers the dual-pipeline behavior and error distinctions, making it complete for a tool of this complexity.

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

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

Schema already covers both parameters (100% coverage), so the baseline is 3. The description enriches understanding by explaining that tolerance_pct defaults to the tolerance implied by the claim wording (capped at 5) and suggesting values 1–2 for hallucination detection. This adds practical meaning beyond the raw schema.

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

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

The description clearly identifies the tool as a natural-language claim verifier with a specific verb+resource: 'claim verification against authoritative sources.' It includes query examples and distinguishes itself from siblings by noting it replaces 4–6 sequential calls (NL parsing → entity resolution → data lookup → comparison).

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

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

Explicit usage guidance is given: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also describes the routing logic (SEC EDGAR fast path vs. grounded pipeline) and notes it replaces multiple sequential calls, effectively stating when to choose this tool over chaining others.

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