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 already mark the tool read-only, open-world, idempotent, and non-destructive, lowering the burden. The description adds the key behavior that it is a router over 5,798 tools, auto-fills arguments, and returns stable citation URIs. No contradiction with annotations, though it does not disclose failure modes or latency, so it is a 4 rather than a 5.

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

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

The description is long but front-loaded with 'PREFER OVER WEB SEARCH' and organized into scope, mechanism, triggers, examples, and a final coverage note. Some repetition exists (e.g., the long domain list plus the catch-all clause), but each section supports correct selection and invocation, so it remains appropriately sized.

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

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

Even without an output schema, the description states the return format (structured answer with pipeworx:// URIs), the problem it solves, and how an agent should phrase queries. It could mention latency or explicitly contrast sibling tools, but for a single-question router it gives enough context to select and invoke it correctly.

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

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

Schema coverage is 100%, with the question parameter and aliases fully described. The description goes beyond the schema by giving trigger phrases and example questions, which clarify what kind of natural-language input is expected. This extra guidance justifies a 4 rather than the baseline 3.

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

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

The description clearly states the tool's action: routing a natural-language question to one of 5,798 tools, filling arguments, and returning a structured answer with pipeworx:// citation URIs. The scope (factual, current or historical data) is explicit with many examples. However, it never names or differentiates sibling tools like ask_pipeworx_beta or deep_research, so it stops short of a 5.

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

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

The description is emphatic about when to use it: 'PREFER OVER WEB SEARCH', 'Use whenever the user asks...', and 'START HERE for most questions', with concrete example queries. It also notes that breaking-news questions are covered. It misses an explicit when-not-to-use section, such as directing complex synthesis to deep_research or experimental alternatives, so it scores 4.

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

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

The description discloses live experimental behavior, notes that no candidate is currently active, states the current exact match to ask_pipeworx, and explains that results are compared against the stable router for merge decisions. This is substantial context beyond the readOnly/idempotent annotations and does not contradict them.

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

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

Three dense sentences front-load the beta relationship and current status, then provide usage, telemetry, and fallback behavior. Every sentence adds necessary context with no filler.

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

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

Given full schema coverage, rich annotations, and a statement that the response shape matches ask_pipeworx, the description gives an agent everything needed to invoke it correctly. The only minor omission is an explicit 'do not use' condition, but the stable sibling is already referenced.

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

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

Schema coverage is 100% and all parameters are documented as aliases for `question`, so the schema already carries the semantic load. The description adds only a generic statement about same arguments as ask_pipeworx, not enough to raise the score above baseline.

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

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

The description states a specific role: a beta universal router identical to ask_pipeworx but with candidate routing improvements. It also explicitly distinguishes itself from the stable sibling and clarifies it is a full working router, not a fallback stub.

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 to use it exactly like ask_pipeworx when you want the newest routing, and names the stable router as the comparison baseline. It does not explicitly say when not to use it, but the stable alternative is clearly implied and named.

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

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

The description goes well beyond the annotations by detailing return shapes, evidence extraction as a verbatim quote, confidence, source, fetched_at, and explicit refusal reasons. It also discloses the extra LLM call cost. No contradiction with the readOnlyHint, openWorldHint, or idempotentHint annotations.

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

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

The description is dense but well-organized: it leads with the core value proposition, explains the mechanism, gives return/refusal formats, provides usage guidance, and closes with a cost-based alternative. Each sentence carries useful information, and the length is justified by the complexity of the tool.

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

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

For a grounded answering tool with no output schema, the description covers the essential contract: what it does, how it works, what it returns, when it refuses, and when to use a cheaper alternative. It is sufficiently complete for an agent to select and invoke it correctly.

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

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

The schema already documents the question parameter with 100% coverage, including natural-language input and aliases. The description does not add parameter-specific meaning beyond usage context, so the baseline of 3 is appropriate.

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

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

The description defines the tool as a hallucination-resistant answer mode that routes to the appropriate source, fetches data, and extracts the answer strictly from the tool result. It names the exact behavior (grounded answering) and implicitly differentiates itself from ask_pipeworx by mentioning the same routing but a stricter extraction mechanism.

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

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

It explicitly states when to use the tool: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' and gives concrete examples of high-stakes domains. It also provides a clear alternative and when to prefer it: 'prefer ask_pipeworx for casual lookups.'

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

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

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?

Beyond the read-only/idempotent annotations, the description discloses account requirements, GitHub signup, paid depth tier, parallel routing to 5,798 tools, the findings-packet format with gaps[] and contradictions[], citation_uri behavior, semantic excerpting, and expected latency. This gives a full picture of what happens when the tool is invoked.

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; nearly every sentence earns its place given the tool's complexity. It is front-loaded with the most critical caveats (account requirement, alternative tool), though the transition into 'Second iteration:' is awkward and the single-paragraph wall of text could be better structured.

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

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

For a tool with no output schema, the description thoroughly covers return contents (verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[]), depth-specific behavior, latency, and alternative routing. An agent has everything needed to decide and call it correctly.

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

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

Schema description coverage is 100%, so the schema already fully documents both 'question' and 'depth' parameters. The tool description reiterates depth behaviors but does not add meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources ... in ONE call.' It also actively distinguishes itself from open-web search and from ask_pipeworx, making its identity 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 guidance is given: use ask_pipeworx when not signed in or for a single lookup, and use deep_research for broad/multi-part questions over structured data. The paid-tier constraint on 'thorough' depth is also clearly called out, so an agent knows exactly when this tool is the right choice.

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 substantial behavioral context beyond the readOnly/openWorld/idempotent annotations: it explains fan-out across sources, soft-failure for the PatentsView API sunset, empty sections as real 'no data' rather than bugs, and the resolved:false path for private companies. No contradiction with annotations exists.

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

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

The description is long but densely informative, and the length is largely justified by the tool's many output sections and failure modes. It is front-loaded with user intents and the primary usage rule. It could be tightened with structured formatting, but every major sentence contributes operational guidance.

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

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

There is no output schema, so the description carries the full burden of explaining return values. It does so thoroughly: cik/company_name, resolved_from/to, recent_filings, fundamentals, patents, contracts, FDA products, hiring, news, LEI, and sources_used/sources_failed. Edge cases like private companies and empty sections are explicitly covered, making the description complete 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 coverage is 100%, so the baseline is 3, but the description adds meaningful semantics: both type values behave identically, value accepts ticker/CIK/name, and names resolve via EDGAR company-name match. This goes beyond the schema's own parameter descriptions, earning a 4.

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

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

The description clearly states this is a full cross-source profile tool for US public companies, with a specific verb ('brief', 'profile', 'research') and resource. It distinguishes itself from single-pack lookups and chaining by emphasizing ONE parallel call. Examples of user intents make its purpose immediately recognizable.

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 to use this tool when the user asks for a holistic view and to ALWAYS PREFER it over chaining single-pack SEC/XBRL/news lookups. It also clarifies accepted input shapes and the expected behavior for private companies, giving the agent clear decision rules.

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?

The description discloses far beyond annotations: token-overlap matching, compatibility_codes semantics, unclassified legs never paired, null temporal_alignment not meaning aligned, fees not modeled, and pairing_unverified. These details add substantial behavioral context without contradicting the readOnly/idempotent annotations.

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

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

The description is long but well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded purpose. While somewhat dense, nearly every sentence contributes operational context; minor redundancy exists in repeated caveats about pre-mapped topics and compatibility warnings.

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

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

Despite having no output schema, the description thoroughly documents the response shape including spread[], top_spreads_pp, flags, temporal_alignment, fees_note, skipped counters, and low_confidence_pairs. It also covers edge cases and interpretation pitfalls, making the tool actionable for an agent.

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

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

Although schema coverage is 100%, the description adds meaning beyond the schema: both modes run the identical matcher, explicit parameters override the topic-mapped side, and the topic list is accompanied by caveats about real tradeability. It also explains how parameter combinations affect the response, which the schema alone does not convey.

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 computes a cross-venue spread between Kalshi and Polymarket for the same resolving question, and specifies two modes for achieving that. It distinguishes itself from sibling tools by focusing specifically on cross-venue comparisons and naming the core matching mechanism.

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

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

It explicitly describes when to use the `topic` mode versus explicit `kalshi_event_ticker` + `polymarket_event_slug` mode, and warns that pre-mapped topics are not guaranteed tradeable. It does not explicitly name alternative sibling tools, but provides clear contextual guidance for selecting between the two invocation modes.

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 readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description goes well beyond that: it explains the internal cascade ('cascades through several lookup endpoints internally'), the graceful degradation when GLEIF/OpenFIGI is unavailable, the behavior of returning figi_candidates when ambiguous, and the explicit listing of unresolved identifiers. It also notes that it replaces 2-3 manual lookups, giving agents a mental model of the operation's cost and behavior. No contradiction with annotations.

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

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

The description is long but every sentence earns its place. It front-loads the purpose with concrete examples, then dives into type-specific details. The structure uses clear enumerations ('SUPPORTED TYPES') and explicit warnings. It is not excessively verbose for the complexity it covers, though it could arguably be tightened. A 4 reflects that it is appropriately sized for the tool's richness.

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 must explain what the agent gets back. It does: identifiers labelled by source, unresolved items listed under 'unresolved', figi_candidates for ambiguity, and the fallback behavior when enrichment services fail. It also covers edge cases like ISIN resolving to the issuer and non-equity instruments. Nothing an agent needs to decide when to call and what to expect is missing.

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

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

Schema coverage is 100% for both parameters, but the description adds extensive meaning beyond the schema. For 'type', it enumerates the two enum values and what each resolves (company: CIK/ticker/LEI/FIGI; drug: RxCUI/ingredient/brand). For 'value', it explains accepted formats (ticker, CIK, ISIN, name) and explicitly warns about passing only the entity name, not the question's full noun phrase. This is far more than the schema's terse 'For company: ticker (AAPL), CIK (0000320193), or name.'

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

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

The description opens with concrete example queries ('What's the ticker for…' / 'find the CIK for…') and then states the verb-resource: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It also lists supported types ('company' and 'drug') and what each resolves. This is specific, unambiguous, and clearly distinct from siblings like entity_profile or compare_entities.

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

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

The description gives a strong directive: 'Use FIRST whenever you have a name but need an ID.' It also explains when the tool is applicable across types and warns against passing full noun phrases, giving concrete examples ('NEW YORK ST DORM AUTH' vs. adding 'revenue bonds'). It does not explicitly name alternative tools for other cases, but the 'Use FIRST' guidance plus the detailed scope makes usage clear. A 4 is warranted because it lacks explicit 'when not to use' wording.

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.