Tarot Draw

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

The description complements annotations (readOnlyHint, idempotentHint, etc.) by disclosing that the default model is free and that providing an API key enables Anthropic probing (with cost implications). It also describes the return structure (per-model {score, confidence, signals, raw_response} + combined view), adding behavioral context beyond the annotations.

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

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

The description is three sentences long, front-loaded with the core purpose, and each sentence adds essential information (purpose, configuration, returns and use cases). No redundancy or fluff.

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

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

The tool has no output schema, but the description explains the return format. With 4 well-documented parameters, clear use cases, and no nested objects or enums, the description is sufficiently complete for an agent to understand inputs, outputs, and invocation context.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining the default model for 'models' (free Workers AI Llama-3.3-70b) and clarifying that '_apiKey' is passed directly to Anthropic. This provides semantic context not fully captured in the schema.

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

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

The description clearly states the tool probes LLMs for knowledge about a business/brand/product/topic and scores visibility (0-100) per model. It uses specific verbs and resources ('probe', 'score visibility') and distinguishes from siblings like 'scan_competitor_ai_presence' by highlighting the multi-model probing and scoring aspect.

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 context on when to use the tool ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to provide the optional '_apiKey' parameter. It does not explicitly compare with sibling tools like 'scan_competitor_ai_presence', but the use cases are 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 mark the tool as read-only, open-world, idempotent, and non-destructive. The description adds useful behavioral detail beyond those annotations: it routes to 5,798 tools across 1,517 verified sources, fills arguments automatically, and returns structured answers with stable pipeworx:// citation URIs. No contradiction with the annotations.

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

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

The description is longer than average, but it is front-loaded with the core preference and purpose, then gives trigger phrases and examples. Each section earns its place, though the exhaustive domain list could be tightened without losing meaning.

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 single-required-parameter router tool, the description covers purpose, trigger conditions, examples, and output format (structured answer with citations), and the annotations cover safety and side effects. However, it omits guidance for selecting among the similar siblings ask_pipeworx_beta and ask_pipeworx_grounded, which is a meaningful gap for an agent choosing the right tool.

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

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

The input schema already documents all six parameters as aliases of the natural-language 'question' at 100% coverage, so the schema carries the parameter documentation burden. The description adds no parameter-specific details beyond reinforcing that the input is a natural-language factual question, which is acceptable but not additive.

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 factual-query router that should be preferred over web search for authoritative data, listing specific domains and examples. It states a specific action—routing the question, filling arguments, and returning cited answers—but it does not differentiate it from similarly named siblings like ask_pipeworx_beta or ask_pipeworx_grounded.

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?

Gives explicit trigger conditions: use whenever the user asks 'what is', 'look up', 'find', 'get the latest', 'how much', 'current', or any factual question, and says to prefer it over web search. It includes concrete examples of appropriate questions. It does not, however, state when not to use it or when a sibling variant would be a better 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?

Annotations already cover read-only/idempotent safety, so the description's job is to add context, and it does: the beta status, the fact that routing candidates can be enabled live, the current absence of a candidate, and that it is a full working router rather than a degraded fallback. This gives an agent an accurate model of the experimental risk without contradicting the annotations.

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

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

The description is longer than average but each sentence earns its place: beta definition, current status, usage instruction, and assurance that it is fully functional. The front-loaded 'Beta version of ask_pipeworx' makes the key distinction immediately visible, though '5,798 tools' and the exact retirement date are more detail than strictly necessary.

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-argument tool with rich annotations, the description is complete enough to invoke safely: it accepts a question, behaves identically to ask_pipeworx today, and may differ when a candidate is under test. It does not spell out the response format, but it explicitly says the response shape is the same as ask_pipeworx, which is sufficient given the sibling exists.

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 every parameter is documented as an alias for 'question', so the schema already carries the meaning. The description only says 'same arguments' and does not add format, length, or example guidance, so a 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 identifies this as the beta variant of ask_pipeworx and states it is an identical universal router over 5,798 tools, which makes the resource and action clear. It distinguishes itself from the stable ask_pipeworx sibling by emphasizing experimental routing candidates. It relies somewhat on ask_pipeworx for the full meaning of 'ask'/'router', so it is clear but not maximally standalone.

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?

'Use it exactly like ask_pipeworx when you want the newest routing' gives a direct when-to-use condition and names the alternative. It also clarifies current state ('matches ask_pipeworx exactly') so an agent knows the behavior is unchanged today, though it does not give explicit when-not-to-use guidance for the stable sibling.

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

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

The description goes well beyond the annotations, detailing the success response shape ({answer, evidence, confidence, source, fetched_at, refusal_reason:null}) and the explicit refusal path with specific refusal_reason values. It also discloses the internal behavior of extracting only from tool results and the extra LLM call, which is highly relevant for agent behavior. No contradiction with readOnlyHint, openWorldHint, idempotentHint, or destructiveHint.

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 detailed yet disciplined: it front-loads the core value proposition, gives the key behavioral guarantee, provides the structured return/refusal contracts, and closes with a cost-conscious routing note. Every sentence earns its place and no information is redundant with the schema.

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

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

Given the tool's complexity and high-stakes context, the description is exceptionally complete. It covers behavior, return shapes, refusal reasons, comparison to the sibling, cost tradeoff, and appropriate usage. The lack of an output schema is mitigated by the explicit response contract in the description.

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

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

Schema description coverage is 100% and the schema already fully documents the question parameter and its aliases. The description does not add parameter-level detail, but none is needed given the schema's clarity. A baseline of 3 is appropriate because the schema carries the parameter documentation burden.

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

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

The description clearly identifies this as a hallucination-resistant, grounded answer mode for high-stakes reads, with a specific verb ('EXTRACTS the answer using ONLY what the tool result contains'). It explicitly distinguishes itself from ask_pipeworx by the grounded, non-inventing behavior, making the differentiation from siblings immediate.

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

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

The description provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also names the alternative for casual lookups, ask_pipeworx, and warns about the extra LLM call cost, giving the agent a clear decision rule.

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 annotations: it explains low-confidence resolution short-circuiting, closed market handling, wide spread warnings, cancellation rules, and news fallback mechanisms. Annotations only indicate read-only and idempotent.

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 contains very detailed information but is presented as a long paragraph without formatting (e.g., bullet points). Every sentence adds value, but readability suffers from 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?

Given the tool's complexity (multiple fan-out paths, error states, result shapes), the description covers most scenarios. It explains resolver contracts, parent event extraction, and safety mechanisms. No output schema exists, but the description outlines result fields.

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 descriptions for each parameter. The description adds practical examples and clarifies the behavior of 'depth' and 'include_raw', enhancing understanding beyond the schema.

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

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

The description states a specific verb ('Research') and resource ('Polymarket bet') and provides examples of inputs and outputs. It clearly distinguishes from sibling tools like polymarket_edges or arbitrage by focusing on comprehensive data pulling.

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

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

The description explicitly lists use cases ('should I bet on X', etc.) and includes detailed examples of fan-outs for different bet types. However, it does not explicitly state when not to use the tool or name alternatives.

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

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

Annotations declare non-destructive, read-only, idempotent behavior. The description adds details like data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs. 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 example queries and well-structured, but slightly verbose. Every sentence adds value, though a few words could be trimmed without loss.

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

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

Given the tool's complexity (two entity types, multiple metrics, citations), the description fully explains what it returns and how it works. No output schema exists, but the description adequately covers return format and behavior.

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

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

Schema covers 100% of parameters with clear descriptions. The description adds practical context: explains the format of values (tickers for company, drug names), item constraints (2-5), and that output is paired data with citations and sorted.

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

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

The description clearly states the tool compares 2-5 entities (companies or drugs) in one parallel call, pulling specific financial metrics for companies and adverse-event/FDA/trial data for drugs. It is distinct from sibling tools like entity_profile which handles single 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?

Explicitly advises to prefer this over sequential lookups when comparing entities, provides example natural language queries, and specifies the entity count range and types. It effectively communicates when and why to use this tool.

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

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

Annotations already declare readOnly/openWorld/idempotent behavior, but the description adds substantial context beyond them: account and paid-plan requirements, parallel decomposition across 5,798 tools, output shape with gaps[] and contradictions[], citation_uri fetchability, semantic excerpting, and latency expectations. This fully discloses what the agent should expect.

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

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

The description is long but every sentence carries distinct information: auth, alternatives, data scope, decomposition behavior, output packet, gap handling, contradictions, citation fetchability, excerpting, and latency. Critical constraints are front-loaded at the beginning, so an agent sees the most decision-relevant facts immediately.

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 carries the burden of explaining return values and does so thoroughly: verbatim evidence, confidence, source, fetched_at, stable citations, gaps[], contradictions[], hop field, and citation_uri. It also covers authentication, pricing, latency, exclusions, and alternatives, making it complete for a complex tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes further by clarifying that depth:'thorough' needs a paid plan, that standard/thorough add gap-recovery and contradictions[], and that the question can be broad/multi-part. This adds real 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 names a specific verb and resource: grounded multi-source research across Pipeworx's 1517 structured data sources, including SEC, FRED, FDA, USPTO, and more. It clearly distinguishes itself from open-web search and from single-lookup siblings by naming what it is not and what it is best at.

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 explicit when-to-use guidance: best for broad/multi-part questions over structured data, with concrete examples. It also names the alternative explicitly for two exclusion cases: use ask_pipeworx if not signed in, and use ask_pipeworx for a single lookup. The depth tiers are also tied to usage scenarios.

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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by explaining the return format: 'top-N most relevant tools with names, descriptions, and full input schemas... each result is ready to call directly.' There is no contradiction with annotations.

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

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

The description is a single paragraph that efficiently front-loads the purpose, then lists domains, return content, and usage advice. It is concise and well-structured but could be slightly more 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?

Given the tool's simplicity, annotations, and full schema coverage, the description covers all necessary context: what it does, what it returns, and when to use it. No output schema exists, but the description explains the return format adequately.

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

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

Schema description coverage is 100%, so the description does not need to add much. The description mentions aliases for the query parameter, but this is already implied in the schema. The baseline score is 3 due to high coverage.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains and distinguishes itself from sibling tools by being the discovery gateway. The verb 'discover' and resource 'tools' are explicit.

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

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

The description provides explicit when-to-use advice: 'Call this FIRST when you have many tools available and want to see the option set.' It does not give explicit when-not-to-use scenarios, but the positive guidance is strong.

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 by disclosing the parallel fan-out across sources, the USPTO soft-fail behavior, the meaning of sources_used/sources_failed, and the explicit statement that an empty fda_products section is expected for non-biologic companies. It even explains resolved:false returns for private companies with a notes line. This gives the agent strong behavioral expectations that annotations alone could not 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?

The description is long, but dense with purpose-built information. It front-loads examples and the core directive, then uses a structured list for return fields and a clear statement about sources_used/failed. No sentence is filler; the length is justified because there is no output schema and this tool aggregates many distinct data sources. It could be tightened slightly, but it earns most of 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 (many fan-out sources, no output schema, only 2 params), the description is remarkably complete. It enumerates all return fields (cik, recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI), explains edge cases (private companies, patent API sunset, empty fda_products), and covers input variants. An agent has everything needed to decide when and how to invoke it.

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

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

Schema coverage is already 100%, so the schema fully documents the two parameters. The description adds value by clarifying that type's enum values are interchangeable ('both are accepted and behave identically') and by giving concrete, varied examples of acceptable value formats (ticker, zero-padded CIK, name). It also explains name resolution via SEC EDGAR and the private-company failure mode, which the schema does not.

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 query examples ('Tell me about X', 'research Acme', 'brief me on Tesla') and then states the exact function: 'full cross-source profile of a US public company in ONE parallel call.' It clearly distinguishes itself from chaining single-pack lookups and from siblings like resolve_entity or compare_entities by emphasizing the holistic, multi-source nature.

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

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

The description explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' providing clear conditions for use. It also explains valid input forms and the expected behavior for private companies. However, it does not explicitly contrast with sibling tools like compare_entities or resolve_entity, leaving some routing decisions to the agent.

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 destructiveHint=true. Description adds context about clearing sensitive data but doesn't disclose further behavioral details beyond what annotations provide.

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

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

Two sentences, every word adds value, no fluff. Front-loaded with core action.

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?

Completely adequate for a simple single-parameter tool with clear annotations. No missing context needed 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% and description of parameter 'key' ('Memory key to delete') already sufficient. Description adds no additional meaning.

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 'Delete a previously stored memory by key', providing specific verb and resource, and distinguishes from siblings like 'remember' and 'recall'.

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

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

Explicitly describes when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also suggests pairing with 'remember' and 'recall'.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral details: fetches page, extracts title/description/key links, and emits standard markdown format. No contradictions and adds value beyond annotations.

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

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

Description is a single focused paragraph, front-loaded with purpose, followed by behavioral details and use cases. No wasted words, though could be slightly more concise by removing redundancy.

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

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

Given no output schema, the description adequately explains the output format (single text blob) and the extraction process. Use cases are provided. The tool is simple and fully described for selection and invocation.

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

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

Schema coverage is 100%, so parameter descriptions are already provided. The description mentions 'max_links' and 'url' but adds little new semantic meaning beyond the schema, earning baseline score for high coverage.

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

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

The description clearly states the tool generates a production-ready llms.txt file for a URL, specifying the exact purpose and output format. It distinguishes itself from sibling tools by focusing on this specific task.

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

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

The description provides explicit use cases (getting client's site indexed, drafting for own project, auditing competitor) but does not mention when not to use this tool or explicitly exclude alternatives. Sibling tools are sufficiently different to make usage 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 read-only, idempotent, non-destructive behavior. Description adds value by listing exact return fields, further clarifying the output 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?

Two sentences, front-loaded with core purpose, no fluff. Every sentence adds necessary 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?

For a simple tool with one optional parameter and no output schema, the description fully explains what it returns and when to use it, covering all needed context.

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 includes a description for the single parameter. The tool description does not add extra parameter semantics, so 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 it lists the caller's active subscriptions and specifies the returned fields, distinguishing it from sibling tools like subscribe and unsubscribe.

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

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

Provides explicit use cases: review before adding more subscriptions or find an id to cancel. Does not explicitly state when not to use, but the context is clear.

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

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

Annotations are minimal (no readOnly/destructive hints), so the description carries the burden. It discloses the two-step flow (filing returns a claim_token, which can be passed back later to read resolution), rate limiting (5 per identifier per day), and that it doesn't count against tool-call quota. 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 dense; every sentence adds value—purpose, use cases, exclusions, usage pattern, rate limit, and expectations. It's front-loaded with the primary action and has 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?

For a tool with two distinct modes (reporting and checking), the description explains both, including the return value (claim_token) absent from schema, and sets expectations (daily reads, roadmap impact). It's fully adequate without an 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 already covers all four parameters with rich descriptions (enum meanings, claim_token usage), providing baseline 3. The description adds extra context: how to use claim_token as a follow-up call and guidance to describe issues in terms of Pipeworx tools/packs, enhancing parameter understanding.

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

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

The description opens with a clear verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It distinguishes from siblings by explicitly limiting scope to tools served by this Pipeworx connection, so the agent knows exactly what the tool does.

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 lists trigger conditions (bug, feature/data_gap, praise) and provides an exclusion: do not report issues for tools from other MCP servers. It also says 'Not sure?' and tells agent to check which connection lists it. This is strong guidance with clear alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds valuable context beyond annotations: data source ('CF analytics-engine'), privacy guarantee ('no PII'), caching details ('cached 5min-1h depending on window'). No contradictions.

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

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

The description is concise, well-structured, and front-loaded with the primary purpose. Each sentence adds value, and the use-case list is easy to scan. No redundant or filler text.

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 (1 optional param, no output schema), the description covers the key aspects: what it returns, use cases, data source, and caching. However, the exact return format (e.g., data structure) is not specified, but it's inferable from use-case context.

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 one optional enum parameter. The description adds interpretative guidance: 'shorter windows surface what's hot right now; longer windows show steady-state demand.' This enhances the schema's description of the enum values.

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 'top tools, top packs, and total call volume' for a given time window. It emphasizes the social signal ('what other AI agents are calling on Pipeworx right now'), making the purpose highly specific and distinguishable 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?

Three explicit use cases are listed (discovering hot data sources, confirming canonical tool, aligning use case). The description also explains the trade-off between window sizes. However, it does not mention when NOT to use this tool or suggest 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 indicate readOnly, openWorld, idempotent, and non-destructive. The description adds extensive behavioral context: explains monotonicity and partition-sum checks, Jaccard similarity for cross-event pairing, placeholder slug filtering, fill check against live CLOB depth, and conditions for not trading. 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 somewhat long but well-structured: summary sentence, mode details, cross-event specifics, partition filter, response format, fill check. It is front-loaded with the core purpose. Could be slightly more concise, but each sentence adds value for the tool's complexity.

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

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

Despite no output schema, the description thoroughly explains the response structure (opportunities array with fields, partition_check object) and fill check results. It covers modes, filtering, and limitations. For a scanning/analysis tool, this provides complete context for an AI agent to use 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 both parameters described. The description adds value by providing real-world examples (e.g., event slug 'fed-decision-may-2026', topic 'Fed rate decision') and clarifying that full Polymarket URLs are accepted for the event parameter. This enriches 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 clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It specifies the verb (find), resource (arbitrage opportunities), and methodology. It distinguishes between event and topic modes, and provides examples. It differentiates from sibling tools by focusing on specific arbitrage detection methods.

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 guidance: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It recommends event mode for specific markets and topic for cross-event scanning. It also advises against trading when realizable_edge_pp <= 0 and directs to polymarket_fill_risk for custom sizing.

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

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

Discloses three model families, response structure, tradeable-edge knobs, and diagnostic information. Adds significant context beyond annotations (e.g., caching, Fed data caveat). Consistent with readOnlyHint and idempotentHint.

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 very long and dense, mixing high-level purpose with detailed technical explanations of model families. While informative, it could be more concise and structured for 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 the complexity (9 parameters, no output schema), the description thoroughly covers response structure, segments, diagnostics, and edge cases like empty segments. It is exceptionally complete.

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

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

Schema coverage is 100% with detailed parameter descriptions. The description provides overarching context for some parameters (e.g., tradeable-edge knobs), but does not add 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?

Description starts with 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price', which is a specific verb+resource. It clearly distinguishes from siblings like polymarket_arbitrage by focusing on data disagreement and providing a high-level usage scenario.

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 'Built for "what should I bet on today"' and mentions agents can discover opportunities without paging hundreds of markets. Provides context about when to use, but does not list exclusions or 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?

Behavior is fully disclosed: reading snapshots, computing trend and decay from time-series, handling expired opportunities, and noting gaps in snapshot dates. Annotations already indicate read-only, idempotent, and non-destructive, and the description adds valuable 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 verbose but every sentence adds value, covering purpose, args, response structure, and limitations. It is front-loaded with the core question it answers. Some technical details could be compressed, but overall it is well-organized.

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 exhaustively explains the response fields (tracked, expired, snapshot_dates), including sub-fields like trend, decay_pp_per_day, and lifespan_days. Data gaps and computational details are covered, making the tool fully understandable.

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

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

Both parameters (days, window) are well-described in the input schema with clear defaults and valid ranges. The description adds minimal extra meaning, essentially restating schema info. Given 100% schema coverage, a score of 3 is appropriate.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' from polymarket_edges snapshots, answering a specific question about edge age vs. width. It distinguishes from sibling tool 'polymarket_edges' which likely gives current snapshot data.

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

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

The description explains the tool is for assessing edge persistence over time, with a concrete example of why a fresh wide edge differs from an old one. It mentions data limitations (60-day TTL, daily closes) but does not explicitly state when to prefer alternatives or when not to use it.

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

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

Annotations provide readOnlyHint:true, idempotentHint:true, destructiveHint:false. The description adds substantial behavioral context: walks the order book ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and warns about forced directional risk and partial basket fill consequences. 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 somewhat lengthy but well-structured with clear sections for single-market and basket modes. It is front-loaded with the core purpose. Every sentence adds value, including output details and warnings. Minor deduction for length; however, given complexity, the structure is effective.

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

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

No output schema, but the description lists many output fields (top_of_book, vwap_fill_price, slippage_pp, etc.) and covers both modes thoroughly. It explains edge cases like thin legs, forced directional risk, and partial fills. Given the tool's complexity (two modes, parameter interactions), the description is fully complete.

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

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

Schema description coverage is 100%. The description adds meaning beyond schema: for size_usd it explains default and clamp range (10–1,000,000), for side it explains default auto behavior in basket mode, and for event/market it clarifies single-market vs basket modes. This adds significant value beyond 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 clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes, specifies inputs and outputs, and explicitly ties its use to arb signals and edge trades. This is a specific verb+resource with clear differentiation from siblings like polymarket_arbitrage and polymarket_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?

The description explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why with warnings about theoretical overround not being capturable and partial basket fills converting arb into unhedged directional positions. This provides excellent usage guidance with exclusions and alternatives.

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

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

Annotations only say readOnly/openWorld/idempotent/non-destructive. The description adds substantial behavioral context: compatibility_warning can be non-empty even when matched_pairs>0, null temporal_alignment means 'could not compute', Kalshi fees are not modeled so spreads are gross not net, and unclassified legs are never paired. It also enumerates machine-readable codes and per-entry flags. 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 almost every sentence carries unique caveats or disclosures (fees note, skipped counters, 'pre-mapped ≠ tradeable'), and the first sentence nails the core purpose. It loses a point because it's an unstructured wall of text—section headers or bullet lists would make the safety-field semantics easier to scan.

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

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

Given the tool's complexity and the absence of an output schema, the description is remarkably complete: it covers response structure (leg-by-leg prices, top_spreads_pp, skipped counts), every safety field and code, temporal alignment semantics, and the fee caveat. An agent can determine call semantics, interpretation, and failure modes from the description alone.

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%—each parameter has a description and lists the topic options. The tool description goes beyond by explaining that both modes run the identical token-overlap matcher, that explicit tickers override the topic-mapped side, and that custom pairings are for cases where no pre-map exists. This adds interaction-level meaning not present in the schema.

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

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

Opens with a specific declarative: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It identifies the resource (the two venues, same question), the metric (spread in pp), and even explains why the spread can be a real signal, separating it from sibling tools like polymarket_arbitrage or polymarket_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?

Clearly distinguishes TWO MODES—pre-mapped topic shortcuts versus explicit kalshi_event_ticker+polymarket_event_slug pairings—and explains when each is appropriate. It also warns that pre-mapped does not equal tradeable, but it does not name sibling tools or explicitly state when to prefer them over 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to restate these. However, the description adds valuable behavioral context: scoping to the agent's identifier (anonymous IP, BYO key hash, account ID), which is not in annotations. No contradictions.

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

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

The description is two sentences: the first states the core function, the second adds context and links to siblings. Every sentence adds value, with no filler or repetition. It is front-loaded and efficient.

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 (one optional parameter, no output schema, comprehensive annotations), the description covers all necessary aspects: main behavior, parameter semantics, scoping, and relationship to sibling tools. Nothing 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% with the 'key' parameter documented. The description goes beyond the schema by clarifying that omitting the key lists all keys, adding meaningful usage nuance. This justifies a score above the baseline of 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 opens with a specific verb ('Retrieve'/'list') and resource ('value previously saved via remember'), and explicitly distinguishes from sibling tools 'remember' and 'forget'. It states the exact verb and resource, making the tool's purpose crystal clear.

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

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

The description provides explicit context for when to use the tool: 'look up context the agent stored earlier'. It names partner tools ('remember' and 'forget') implicitly guiding selection, but does not explicitly state when not to use it or list alternative tools. Still, the guidance is clear and sufficient.

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

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

Beyond annotations (read-only, idempotent), the description discloses key behaviors: the mark_read effect on subsequent calls, filter options, and persistent feed nature. This adds meaningful context not captured by structured fields.

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

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

The description is three sentences with front-loaded purpose, clear structure, and no wasted words. Each sentence adds essential 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?

Without an output schema, the description covers return fields, filtering, mark_read behavior, and an alternative access method. It omits explicit mention of limit and unread_only behaviors but these are in the schema. Overall, it is comprehensive 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% with descriptions. The description adds marginal value by explaining mark_read behavior and providing a filter example, but does not significantly extend parameter understanding beyond the schema.

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

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

The description clearly states the tool pulls fired events from the subscription feed and specifies the returned data (source, citation_uri, raw payload). It distinguishes itself from sibling tools like list_subscriptions by focusing on event retrieval rather than subscription management.

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 mentions polling suitability and an alternative REST endpoint, but does not explicitly compare this tool to siblings or provide guidance on when not to use it. Usage context is implied rather than explicit.

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

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

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds rich behavioral details: fan-out to multiple APIs, fallback mechanism (GDELT→GNews on rate limits/5xx), soft-fail for USPTO due to PatentsView sunset, and return format (structured changes grouped by source with total_changes and citation URIs). 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 comprehensive yet efficient. It front-loads with representative queries, then systematically covers each data source, parameter details, and return format. Every sentence serves a purpose without redundancy.

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

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

Given the tool's complexity (multi-source aggregation, fallbacks, sunsetting API) and the absence of an output schema, the description fully covers input parameters and return structure. It addresses edge cases (PatentsView sunset, rate limiting) and provides guidance on window selection.

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

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

The input schema has 100% coverage, but the description adds valuable context: 'since' accepts ISO dates or relative shorthand with specific recommendations ('30d' or '1m'), 'type' only supports 'company', and 'value' accepts ticker or CIK. This meaningfully enhances the bare 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 explicitly states it provides a change feed for a company with concrete query examples. It specifies the underlying data sources (SEC EDGAR, GDELT/GNews, USPTO) and clearly distinguishes from sibling entity_profile by contrasting static vs. windowed data.

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 clear usage examples ('What's new with X', 'latest on Y') and explicitly recommends entity_profile when static profile is needed regardless of window. However, it does not explicitly state when not to use it, such as for non-company entities or when specific source exclusion is required.

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

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

Annotations already provide idempotentHint and destructiveHint. The description adds critical context: key-value pairs are scoped by identifier, persistence differs for authenticated (permanent) vs anonymous (24 hours) users. This goes 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?

Two sentences: first defines purpose and examples, second covers usage and persistence. Efficient, front-loaded, no wasted words.

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

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

Given simple schema (2 strings), no output schema, and safety annotations present, the description fully covers the tool's behavior, usage, and persistence rules. Nothing essential 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% with clear descriptions. The description further enriches by suggesting key naming conventions ('subject_property') and stating value is 'any text', adding 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 'Save data the agent will need to reuse later' and provides concrete examples (ticker, address, preference). It distinguishes from sibling tools 'recall' and 'forget' by explicitly mentioning them as partners.

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 advises using this tool 'when you discover something worth carrying forward' and explains that it avoids needing to look up again. It does not explicitly state when not to use, but the context is clear.

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

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

The description richly discloses behavior beyond the annotations: cascading internal lookups, graceful degradation when GLEIF/OpenFIGI are unavailable, explicit `unresolved` reporting, `figi_candidates` on ambiguous matches, and source-labeling of every identifier. This is exactly the kind of behavioral context annotations alone do not provide.

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

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

The description is dense and every sentence carries useful information, but it is a long, nearly unbroken block. It is front-loaded with the core purpose and usage guidance, yet could be better structured with clear separation of company vs. drug behavior.

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 supported types, and absence of an output schema, the description is exceptionally complete: it covers ambiguity, failure behavior, fallback semantics, input forms, and the scope of identifiers returned. An agent has everything needed 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?

Although schema coverage is 100%, the description adds substantial meaning: accepted input kinds (ticker, CIK, ISIN, name), ISIN-to-LEI resolution semantics, and the critical caveat to pass only the issuer name for bonds. This goes well beyond the schema's field descriptions.

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

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

The description opens with concrete user phrasings and a crisp verb+resource statement: resolve a user-spoken NAME to canonical/official identifiers. It clearly distinguishes itself from siblings by positioning it as the first stop when a name needs to become an 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?

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' giving clear usage context. It does not, however, name any specific sibling tool as the alternative for other cases, so it falls just short of a fully explicit when-not-to-use guideline.

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, destructiveHint=false, and openWorldHint. Description adds context: probes each entity with ai_visibility_check, ranks by score, and returns ranked list. No contradictions; description adds behavioral details 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?

Two well-structured sentences. First sentence explains core function and behavior; second gives use case and output. No wasted words, efficient yet informative.

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 output schema, description specifies return fields (score, confidence, signal density per entity). Combined with rich annotations and schema, it provides all necessary information 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 covers all 4 parameters with descriptions (100% coverage). Description reinforces meaning by noting entities array size constraint and first entry as 'subject', and provides example usage for context and models. Adds value beyond schema.

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

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

Description clearly states the tool compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks scores, and identifies most/least recognized. It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities by focusing on competitive AI marketing audits.

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 usefulness for competitive AI-marketing audits with an example question. Implies when to use (multiple entities) vs when not (single entity, use ai_visibility_check). Does not explicitly list exclusions or alternatives but provides strong contextual guidance.

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

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

Annotations already mark the tool as read-only and idempotent. The description adds critical behavioral details: composite fan-out, partial failure handling (bundlephobia first measurement 5-30s, sources_failed field), and graceful degradation. No contradiction with annotations.

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

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

The description is a single, well-structured paragraph. It front-loads the core purpose, then covers usage, return details, ecosystem scope, and failure behavior. Every sentence provides unique information with 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?

Although there is no output schema, the description fully enumerates the return fields (summary block with 8 fields, per-advisory detail, links, alternative versions). It also explains failure modes. For a tool with 2 parameters, this is exceptionally complete.

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

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

Schema coverage is 100% with descriptions. The description adds value beyond the schema by explaining the version default ('latest published version when omitted') and confirming scoped packages are accepted. This provides useful context for 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 precisely states the tool's purpose: a composite check for npm packages across deps.dev and bundlephobia. It clearly identifies the resource (npm package) and action (scan for safety, popularity, size). This distinguishes it from sibling tools like scan_competitor_ai_presence.

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: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also specifies scope ('NPM ecosystem only in v1') and points to alternatives for other ecosystems (deps.dev:version directly).

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

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

The description adds significant behavioral context beyond annotations: it specifies the embedding model (BGE-base-en), similarity metric (cosine), window size (500-char overlapping), and character limit (200K chars with truncation flag). Annotations already indicate read-only, idempotent, non-destructive behavior, and the description complements these without contradiction.

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

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

The description is four sentences, each serving a purpose: purpose, usage advice, return value details, and technical details. It is front-loaded with the core function and efficiently structured.

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

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

Given the absence of an output schema, the description adequately describes the return (passages with character offsets and similarity scores) and mentions verification of verbatim quotes. It covers all necessary aspects for agent decision-making.

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

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

The input schema covers all parameters with descriptions. The description adds value by providing example queries for the 'query' parameter and clarifying the numeric range for 'limit' (1-20, default 5). This enhances the schema's information.

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

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

The description clearly states it is a semantic search inside a fetched record, using specific verbs like 'search' and resource like 'record'. It distinguishes itself from sibling tools like 'ask_pipeworx_grounded' by noting their pairing.

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 advises using this tool when a record is too large for the prompt, providing clear context. However, it does not explicitly state when not to use it or provide alternative tools beyond mentioning the pairing with ask_pipeworx_grounded.

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

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

The description discloses important behaviors: OAuth requirement, SMS cap (10/day), webhook auto-disable after 10 failures, and verification steps. Annotations provide idempotentHint and readOnlyHint, but the description adds context not 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?

The description is front-loaded with the core purpose and returns value. It then logically progresses to requirements, types, and delivery channels. Every sentence adds value without redundancy.

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

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

Given the tool has 3 parameters with nested objects and no output schema, the description is complete. It explains all parameters, mentions the return value (subscription id), and covers edge cases like verification and limits.

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?

With 100% schema description coverage, the baseline is 3. However, the description adds extensive meaning: detailed type examples (e.g., sec_8k items, polymarket_edge topic), delivery channel nuances (feed always on, webhook HMAC signing), and parameter usage guidance.

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

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

The description clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This uses a specific verb and resource, and distinguishes it from sibling tools like list_subscriptions and unsubscribe.

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

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

The description specifies requirements (OAuth account), supported types, and delivery channels. While it doesn't explicitly state when not to use this tool, the context implies it's for creating subscriptions, and siblings cover listing and unsubscribing.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the bar for extra behavioral context is lower. The description adds value by explaining that the tool returns category-bucketed example questions with exact tool names and argument shapes drawn from a live catalog of thousands of tools. This is beyond what annotations 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?

The description is a single long sentence that begins with a list of example queries and then explains output. While it packs useful information, it's somewhat run-on and could be better structured (e.g., separate sentences for purpose, usage, output format). Still, it avoids non-essential words.

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

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

Given the tool is simple (0 required parameters, no output schema), the description covers what the tool returns (category-bucketed examples with tool shapes) and when to use it. This is sufficient for an onboarding tool, though it could mention that the examples are dynamic and updated in real-time.

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 the single parameter topic, but the description adds meaningful context: it lists the specific focus areas (e.g., finance, pharma) and clarifies that omitting the argument returns a cross-category spread. This goes beyond the schema's generic description.

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

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

The description clearly states the tool's purpose as the onboarding entry point for a new agent, listing example queries (e.g., 'what can you do?') and what it returns (category-bucketed example questions with tool shapes). It distinguishes itself from sibling tools like ask_pipeworx and entity_profile by positioning itself as the first tool to use when exploring capabilities.

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 this tool ('first when you do not yet know what Pipeworx can do') and when to pass the optional topic argument to focus results. It also provides guidance on learning how to call meta-tools, helping the agent decide to use this before others.

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 nature. The description adds valuable behavioral context: 'Accuracy not guaranteed. Refunds not available.' and mentions the 78-card deck. No contradictions with annotations.

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

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

Two sentences, front-loaded with purpose, followed by necessary disclaimers. Zero fluff; every sentence earns its place.

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

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

Given full annotation coverage, a complete parameter schema, and the presence of an output schema (not shown but signaled), the description sufficiently covers all needed context for a simple tarot draw 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% for both parameters. The description does not add significant new meaning beyond the schema's parameter descriptions; it only adds a touch of character ('The cards do not care'). 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 clearly states the verb ('Draw a tarot card' and 'Interprets') and the resource ('from the 78-card deck'). It distinguishes this tool from all siblings, none of which are tarot-related.

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

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

While it does not explicitly state when to use this tool, the disclaimer 'Accuracy not guaranteed' implies it is for entertainment/divination, not factual decisions. No sibling tools exist as alternatives, so guidance is adequate but not explicit.

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

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

Discloses deactivation behavior and historical data availability, complementing annotations (idempotentHint=true, destructiveHint=false). No contradiction.

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

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

Two sentences, no redundancy, front-loaded with core action.

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?

Fully explains purpose, ownership constraint, and side effects for a simple tool with one 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?

Schema covers id parameter fully (100%). Description adds context that id is returned by subscribe, slightly exceeding 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?

Clear verb 'Cancel' and resource 'subscription'. Distinct from siblings '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?

Explicitly states ownership enforcement ('only cancel your own subscriptions') and explains behavioral nuance (deactivation vs deletion).

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

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

Annotations already declare readOnly and idempotent, but the description adds crucial behavioral context: it defines each verdict, warns that could_not_verify means the check did not happen and must not be treated as evidence, and clarifies unsupported vs. could_not_verify. This is valuable beyond the annotations.

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

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

The description is appropriately sized for the tool's complexity. It is front-loaded with trigger phrases and usage, then systematically explains routing, verdicts, and error semantics. Every sentence earns its place; 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?

The tool is complex and has no output schema, but the description covers return values (verdict, actual value, citation, reasoning), explains special error cases (could_not_verify, unsupported), and even mentions the performance benefit over sequential calls. This makes the description sufficiently complete for correct invocation and interpretation.

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, and the description does not add extra meaning beyond what the schema already provides. The tolerance_pct behavior (default, cap, override) is fully explained in the schema, so baseline 3 is appropriate.

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

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

The description clearly states a specific verb+resource: 'natural-language claim verification against authoritative sources.' It lists trigger phrases, distinguishes from sibling tools by noting it replaces 4-6 sequential calls, and outlines two distinct verification paths (structured SEC EDGAR vs. grounded pipeline).

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 explicit guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also differentiates use cases for financial vs. other claims. However, it does not explicitly name alternative tools or state when not to use this tool, 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.