Govtrack

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds key behavioral details: default free model, BYO key for Anthropic, and return structure (per-model + combined view). 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?

Three impactful sentences: first states core function and output, second expands on models and cost, third lists use cases. No redundant phrases; front-loaded with actionable information.

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

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

Despite having 4 parameters and no output schema, the description fully explains the return format (per-model score, confidence, signals, raw_response + combined view) and all parameter purposes. Completely adequate 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%, but the description adds value by clarifying 'entity' scope (brand/product/person/topic) and explaining 'context' as disambiguation aid. All parameters are meaningfully described beyond schema.

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

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

The description uses specific verbs ('probe', 'score') and clearly identifies the resource (LLMs) and result (visibility score 0-100). It distinguishes from sibling tools by focusing on AI visibility audits, which is unique among the listed 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?

Explicitly states when to use (AI-marketing audits, pre-launch brand checks, competitive monitoring). Clarifies default model and API key requirement for Anthropic. Lacks explicit 'when not to use', but context is sufficient given sibling diversity.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds meaningful behavior beyond these: it routes to thousands of tools, fills arguments, returns structured answers with stable pipeworx:// citation URIs, and notes it is 'one fast call.' This is strong added context, though it does not discuss edge cases like rate limits or failure modes.

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 ideal, but it is front-loaded with the most critical guidance ('PREFER OVER WEB SEARCH') and each sentence adds usage or behavioral context. The long lists of example sources and queries are somewhat redundant but still reinforce when to use the tool.

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

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

Despite having no output schema, the description explains what the tool returns ('structured answer with stable pipeworx:// citation URIs'), covers its default status, mentions all relevant sibling escalation paths, and provides concrete examples. It is highly complete for a complex routing tool.

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

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

The schema already provides 100% coverage of all 6 parameters, including the required 'question' parameter and its aliases (q, text, input, query, prompt). The description adds illustrative examples and trigger phrases but does not materially change parameter meaning, 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 opens by stating 'PREFER OVER WEB SEARCH' and explicitly says it 'routes the question to the right one of 5,529 tools across 1455 verified sources,' giving a specific verb and resource. It also distinguishes itself from sibling tools like ask_pipeworx_grounded and deep_research by positioning itself as the default entry point.

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 the user asks...', 'START HERE for most questions') and 'when not to use' by naming alternatives ('for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research'). It even addresses breaking-news coverage, showing clear awareness of alternatives.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses that the tool is experimental, with candidate routing improvements enabled live only when one is under test. It provides the current state (no active candidate, last retired on 2026-07-26) and clarifies that it is a full working router with no fallback. This is rich behavioral context that helps the agent trust and predict behavior.

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

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

The description is four sentences, each contributing unique information: definition, current state, usage guidance, and fallback clarification. It is front-loaded with the 'beta version of ask_pipeworx' identity and not overly verbose, though it could be slightly tighter.

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 lack of output schema, the description compensates by stating 'same response shape' as ask_pipeworx, leveraging a sibling tool. It covers the experimental status, live candidate behavior, and exact current parity, making it sufficiently complete for an agent to decide whether and how to invoke it.

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

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

Schema description coverage is 100% and all six parameters are simply aliases for the required 'question' field, each documented in the schema. The description adds only that arguments are the same as ask_pipeworx, which is redundant with the schema and doesn't deepen parameter meaning. Baseline of 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly identifies this as a beta version of ask_pipeworx, an 'identical universal router' with 5,529 tools and the same arguments/response shape. It distinguishes from the stable ask_pipeworx by its experimental edge and candidate routing improvements. However, it does not explicitly state the core function (i.e., routing natural language questions to tools) as a direct verb phrase.

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 it exactly like ask_pipeworx when you want the newest routing.' It also notes that results are compared against the stable router to decide merges, implying ask_pipeworx is the stable alternative. While it doesn't explicitly state 'when not to use,' the beta/experimental context and current matching to ask_pipeworx are 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?

Annotations already indicate readOnly/idempotent/non-destructive; the description supplements this with refusal behavior (refusal_reason enum), return shape including evidence verbatim quote and fetched_at, and the cost tradeoff of an extra LLM call. It also clarifies that the answer is grounded strictly in the tool result, which is critical 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?

Three dense sentences cover purpose, behavior, refusal semantics, evidence format, use cases, and cost tradeoff. No filler words; each clause contributes new information while remaining front-loaded with the core purpose.

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

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

Because there is no output schema, the description provides a full return contract including both success and refusal shapes. It also covers when to use, when not to use, and cost relative to sibling ask_pipeworx, making it self-sufficient for an agent to invoke confidently.

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 `question` and its five aliases fully described in the input schema. The description says the tool 'fills arguments' and takes a natural-language question but adds no per-parameter syntax or format details beyond what the schema already provides, so the schema carries the semantic weight.

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 'Hallucination-resistant answer mode for high-stakes reads' and specifies 'EXTRACTS the answer using ONLY what the tool result contains', clearly distinguishing this grounded variant from sibling ask_pipeworx. It names the resource (Pipeworx tool routing) and the specific evidence-based behavior, making the purpose unambiguous.

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

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

Explicitly states 'Use whenever an answer will be quoted, cited, or acted on' and 'the agent must not invent facts' with concrete domains (financial verdicts, legal claims, medical lookups). Also gives the alternative: 'prefer ask_pipeworx for casual lookups' and notes the extra LLM call cost, providing clear when-to-use and when-not-to-use guidance.

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

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

The description is extremely detailed about behavior: market resolution, classification, fan-out for different categories, response shapes, resolver contract with confidence levels, parent event extraction, news field fallback, safety short-circuits for low-confidence/closed markets, spread warnings, and cancellation rule parsing. This far exceeds the minimal annotations (readOnlyHint) and provides comprehensive transparency.

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

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

The description is very long and packed with information, but it is somewhat unstructured as a continuous paragraph. Key points are front-loaded (purpose, use cases), but the density of content may overwhelm. It could benefit from more structured formatting (e.g., bullet points or sections), though it earns its length by covering essential details.

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 comprehensively explains the return values: result.market fields, result.analysis with model probability and edge warnings, result.evidence by source, resolver contract with confidence and alternatives, parent event extraction, news field metadata, safety short-circuits, spread warnings, and cancellation rule parsing. It covers all aspects an agent needs to use and interpret the tool correctly.

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

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

The input schema already has 100% coverage with descriptions for all three parameters (market, depth, include_raw). The description adds minimal further detail for parameters (e.g., market can be slug, URL, or text), but this is not a significant addition beyond the schema. Baseline is 3 due to high schema coverage.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data, resolving the market, classifying, and returning an evidence packet. It lists use cases like 'should I bet on X'. However, it does not explicitly differentiate it from similar sibling tools (e.g., polymarket_edges), though the purpose is specific enough.

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 and examples of when to use (e.g., 'is there edge in Z'). It also gives guidance on inspecting market_match_confidence before trusting analysis. However, it does not explicitly state when not to use it or compare it to alternative tools.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, and no destructiveness. The description adds value by explaining data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs.

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

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

The description is a single dense paragraph but front-loads common queries and packs every sentence with essential information. It could be slightly more structured but remains concise 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 complexity (two entity types, multiple data sources) and lack of output schema, the description covers key inputs, data sources, sorting, and citations. It lacks precise output field names but is largely 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%, but the description adds contextual meaning: for type='company' it specifies the exact financial fields pulled, and for values it provides examples and constraints. This supplements the schema's basic descriptions.

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

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

The description explicitly states the tool performs side-by-side comparisons of 2-5 companies or drugs, pulling financial data or drug statistics. It distinguishes itself from siblings by advocating preference over sequential single-entity lookups.

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

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

The description provides clear trigger phrases like 'Compare X and Y' and 'rank these companies,' and explicitly states 'ALWAYS PREFER over sequential single-pack lookups.' However, it does not list when not to use it relative to alternatives.

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

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

The description discloses key behaviors beyond the read-only/idempotent annotations: requires a GitHub sign-in (thorough needs paid plan), never invents data (explicit gaps[]), returns fetchable pipeworx:// citations, semantically excerpts large records, and reports expected latency (15-60s, up to ~90s). It also reveals depth-specific behaviors (gap recovery, contradictions[]) not present 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 efficient and information-dense; every clause adds operational knowledge, but it is a single long paragraph that front-loads account requirements rather than the core purpose. For a tool this complex the length is justified, but a terse summary line at the top would improve scannability.

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 fully covers what to expect: findings packet with verbatim evidence, confidence, source, fetched_at, citation_uri, hop, gaps[], and contradictions[], plus timing and source catalog scope. It addresses both capabilities and limitations (e.g., current-news gaps), making it complete for agent 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?

Though the schema already documents depth and question, the description adds rich semantics: it defines quick/standard/thorough facet counts, explains the gap-recovery and contradiction passes, states 'thorough' is paid, and gives an example question. This lets an agent choose parameter values based on desired thoroughness, cost, and iteration behavior.

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 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources...' which clearly identifies the tool as a research orchestrator that decomposes questions into facets and routes them in parallel to thousands of tools. It explicitly contrasts with open-web search and distinguishes itself from ask_pipeworx, making its unique role unambiguous.

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

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

Provides explicit when-to-use: 'Best for broad/multi-part questions over structured data', and when-not-to: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. Also notes sign-in prerequisites and that ask_pipeworx works on every tier, fully covering alternative selection.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds that it returns top-N tools with schemas and examples, ready to call directly, confirming idempotence and non-destructive nature. 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?

Only two sentences, front-loaded with purpose, efficiently packed with domain examples and output details. 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?

Covers purpose, usage timing, output format (top-N with schemas), and examples. No output schema needed; description sufficiently explains return value. Comprehensive for a discovery 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 baseline is 3. Description adds value by listing example data domains (e.g., 'SEC filings, financials, FDA drugs') that inform what 'query' can contain, going beyond the parameter descriptions.

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

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

Description clearly states 'Find tools by describing the data or task' and lists specific data domains (SEC filings, FDA drugs, etc.). It distinguishes from siblings by advising 'Call this FIRST' when exploring tool options, implying it is for discovery rather than direct data retrieval.

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 tells when to use: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST... to see the option set.' Lacks explicit exclusion for cases when the tool is already known, 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 already indicate read-only, idempotent, open-world. Description adds critical behavioral context: the fan-out across five data sources, soft-failure of patents API, and exact structure of returned data (CIK, filings, fundamentals, etc.).

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 examples and key message. It is slightly lengthy but every sentence adds value; could be tightened slightly without losing information.

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

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

Despite no output schema, description comprehensively lists all return components (CIK, filings, fundamentals, patents, news, LEI) and notes limitations (patents soft-fail, names unsupported). No gaps for a tool of this complexity.

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

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

Schema coverage is 100% but description adds meaning: clarifies type is restricted to 'company' for now, value can be ticker or CIK, and explicitly states names are unsupported. This goes beyond enum descriptions.

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

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

Description clearly identifies the tool's purpose: producing a holistic cross-source profile of a US public company in one parallel call. It contrasts with chaining individual lookups and distinguishes from sibling resolve_entity.

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 instruction to prefer this over chaining single-pack lookups for holistic views. Also clarifies when to use resolve_entity if only a name is known, and warns that patents may soft-fail.

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

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

Description aligns with annotations (destructiveHint=true). Doesn't add much beyond stating deletion, but 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, front-loaded with action, then usage context. 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 single parameter and annotations, description is complete: explains why and when to use, and pairs with relevant siblings.

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 description of 'key' parameter. Description adds no extra 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?

Clearly states verb 'delete' and resource 'stored memory by key'. Distinguishes from siblings like 'remember' and 'recall' by naming them explicitly.

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

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

Explains when to use: context stale, task done, clear sensitive data. Mentions pairing with siblings, but doesn't explicitly state when not to use.

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 fetching external pages and extracting specific elements. Annotations already indicate read-only, open-world, and idempotent; description adds extraction details and output format. Could mention failure behavior for unreachable URLs.

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?

Single paragraph, front-loaded with main action. Every sentence provides essential info: purpose, process, output format, use cases. 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?

Adequate for a simple tool with 2 parameters and no output schema. Covers inputs, behavior, and output format. Minor gap: no mention of error handling for invalid URLs.

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

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

Schema covers both parameters with full descriptions (url as full URL, max_links with default/max). Description adds no extra meaning beyond what's in schema, so baseline score applies.

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

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

Description clearly states the tool generates an llms.txt file for any URL, specifies the target AI crawlers, and mentions exact outputs (title/description/key links). Distinct from siblings, which are unrelated (betting, AI visibility, etc.).

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 three concrete use cases (client indexing, own project drafting, competitor auditing). Does not provide negative guidance (when not to use) but given the sibling list, no obvious alternative exists.

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, idempotent, non-destructive; description adds that it lists the caller's subscriptions and defaults to active only. Specifies return fields, which is useful 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?

Two concise sentences: first defines purpose and output, second provides usage guidance. 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 simplicity (1 optional param, no output schema), description fully covers purpose, return fields, usage, and parameter behavior. Agent can correctly select and invoke the tool.

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

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

Schema coverage is 100%, so baseline is 3. Description mentions the boolean parameter in usage context but does not add new semantic 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?

Clearly states 'List the caller's active subscriptions' and enumerates return fields (id, type, params, etc.). Distinguishes from siblings like subscribe and unsubscribe by focusing on listing.

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

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

Explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Provides clear context for when to use, though does not explicitly mention when not to use.

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

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

The annotations are sparse (all false hints), so the description carries the burden of behavioral disclosure. It adds crucial context: rate limiting ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), the claim_token mechanism for tracking feedback, and confirmation that the team reads digests daily. These go far 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?

The description is long (9 sentences) but information-dense. It is front-loaded with the core purpose and usage, then covers exclusions, message guidelines, claim_token, rate limit, and cost. Every sentence contributes value, though it could be tightened. For its complexity, the length is justified, but it's not as concise as it could be.

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

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

There is no output schema, and the description explains the return value only in the no-account case (claim_token). It doesn't specify what happens when filing with an account or the exact output format. However, it covers the essential aspects: when to use, scope, message guidelines, claim_token flow, rate limit, and cost. This is mostly complete for a feedback tool, missing only the generic return 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?

The schema already covers all parameters (100% coverage), so the baseline is 3. The description adds meaningful guidance: it explains the claim_token parameter with a concrete example, instructs to 'Describe the issue in terms of Pipeworx tools/packs' for the message/context, and implicitly reinforces the type enum by defining bug, feature, data_gap, and praise. This pushes it above the baseline, but it doesn't add much about the 'context' nested object.

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 action verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates the specific categories (bug, feature/data_gap, praise) and immediately distinguishes this tool from other servers' feedback tools by stating it is 'ONLY for tools served by this Pipeworx connection.' This leaves no ambiguity about what the tool does and its scope.

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

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

The description provides explicit 'when to use' conditions: bug, feature/data_gap, praise. It also gives a clear exclusion and alternative: if the tool came from a different MCP server, file it there instead. This is exactly the kind of when/when-not guidance that helps an agent select the correct 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 indicate readOnly, idempotent, openWorld. The description adds caching duration (5min-1h) and confirms no PII, enhancing transparency 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?

Four sentences front-loaded with purpose, followed by use cases and details. Every sentence adds value, no fluff, well-structured.

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

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

Given low complexity (1 optional param, no output schema, full annotations), the description covers purpose, usage, caching, and privacy completely, leaving no gaps.

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

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

Schema has 100% coverage with enum description. The description adds semantic guidance that shorter windows show hot trends, longer windows show steady-state demand, adding 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?

The description clearly states it returns top tools, packs, and call volume over a window. It provides three specific use cases, distinguishing it from siblings like discover_tools by focusing on trending data from AI agent calls.

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 three useful scenarios and notes caching behavior. However, it does not specify when not to use it or mention alternative tools, though 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 indicate readOnly, openWorld, and idempotent. Description adds extensive behavioral context: monotonicity/partition checks, fill check using CLOB depth, and thresholds (e.g., 3pp deviation, 0.30 Jaccard). 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?

Well-structured and front-loaded with purpose. Every sentence adds value, though the description is somewhat lengthy. Could be slightly more concise without losing clarity.

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

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

Given the tool's complexity (2 optional parameters, no output schema, no nested objects), the description is remarkably thorough: covers response fields (opportunities[], partition_check), edge cases (placeholder slugs, Jaccard similarity, fill check), and cross-event benefits. No gaps.

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

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

Schema coverage is 100%. Description adds significant meaning beyond the schema: explains parameter usage with examples ('fed-decision-may-2026'), accepts full Polymarket URLs, and describes the behavior differences between event and topic modes.

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 differentiates between invocation modes (no args, event, topic).

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?

Excellent usage guidance: explicitly recommends `event` for a specific market and `topic` for cross-event scanning, explains when each is appropriate, and warns against trading when fill check yields non-positive realizable edge. Also includes details on semantic anchors and partition filters.

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

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

The description adds substantial behavioral context beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint). It details caching behavior ('Cached 1h at the KV level'), edge computation methodology (lognormal barriers, GDELT momentum, partition overround with sport-specific alpha), and how parameters like slippage affect results. 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 well-structured with clear paragraphs and section indicators (e.g., '(1) MODEL_DRIVEN', '(2) STRUCTURAL_ARBITRAGE', '(3) CONCENTRATED_LONGSHOT'). Key information is front-loaded (purpose and high-level opportunity types). While verbose, 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's complexity (9 parameters, no output schema, three response segments with detailed methodology), the description is exceptionally complete. It explains the response structure (by_segment, fed_candidates, diagnostics), highlights edge cases (Fed bets exclusion), and clarifies caching and filter logic. The lack of an output schema is compensated by thorough textual documentation.

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

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

Schema coverage is 100% (all 9 parameters documented), providing a baseline of 3. The description adds meaningful context beyond the schema, such as default values, behavioral impact (e.g., 'Edge is evaluated NET of slippage'), and rationale for filter thresholds. This additional guidance warrants a score of 4.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, with a specific use case 'what should I bet on today'. It distinguishes itself from siblings by detailing three unique model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and providing extensive methodological detail.

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

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

The description implies usage context ('what should I bet on today') but does not explicitly state when to use this tool versus sibling tools like polymarket_arbitrage or polymarket_edge_tracker. There is no clear exclusion guidance, leaving ambiguity for the agent about which tool to invoke in overlapping 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 declare readOnlyHint, idempotentHint, destructiveHint. Description adds extensive behavioral details: snapshot gaps, TTL, decay computation from daily closes, and explanation of negative values. 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?

Front-loaded with the core question, then structured by response fields. Every sentence adds value, no redundancy. Length appropriate for tool 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?

No output schema, but description thoroughly details the response structure (tracked[], expired[], snapshot_dates[]) and limits (TTL, decay computation). Complete for a telemetry tool with simple inputs.

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

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

Schema covers both parameters at 100%. Description adds context such as default values, clamp ranges, and explanation of window families (24hr, 1wk, 1mo) 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?

Description clearly states it provides 'edge persistence and decay telemetry' and answers a specific temporal question about edges. It distinguishes from sibling polymarket_edges by focusing on time-series analysis rather than current snapshots.

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: comparing fresh vs old edges. Though not naming alternatives, the context implies that for current edges one would use polymarket_edges instead.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context beyond annotations: it walks the order book ladder, returns specific fields like top_of_book, vwap_fill_price, slippage_pp, shares_filled, and a verdict (clean|degraded|cannot_fill), and explains the risk of partial basket fills leading to unhedged directional positions.

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

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

The description is well-structured with clear sections (SINGLE-MARKET, BASKET), uses bolded terms for key outputs, and is front-loaded with purpose. Every sentence earns its place, providing necessary detail without extraneous information.

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

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

Despite having no output schema and 4 parameters, the description completely covers what the tool returns (e.g., top_of_book, vwap_fill_price, per-leg fill detail, thin_legs, forced_directional_risk), how it works in both modes, and why it matters for risk management. No gaps remain.

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 meaning beyond schema by clarifying the dual-mode operation (single-market vs basket), explaining that size_usd in basket mode is 'settlement notional S (shares per leg)', and detailing defaults and auto-selection logic for side. This adds significant value.

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

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

The description clearly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth', distinguishes between single-market and basket modes, and explicitly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by specifying when to use this tool before those.

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 to use this tool 'before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', and explains why (theoretical overround on thin books is not capturable, partial basket fills create directional risk), providing clear when-to-use and why-not alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds significant value beyond these annotations by explaining the compatibility_warning field, temporal_alignment, skipped_cross_type/subtype counters, and the meaning of matched_pairs:0 scenarios. 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 but verbose and could benefit from a more structured format (e.g., bullet points for modes and safety fields). Every sentence provides value, but the length makes it harder for an agent to quickly parse key 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?

Given the tool has 3 parameters, no output schema, and high complexity, the description covers all necessary aspects: modes, response fields (spread, compatibility_warning, temporal_alignment), edge cases, and usage limitations. It sufficiently prepares the agent 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 description coverage is 100% with all three parameters described. The description adds context about the two modes and explains that explicit tickers override the topic-mapped side, providing clear semantics 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 computes cross-venue spreads between Kalshi and Polymarket. It specifies two modes (topic shortcuts and explicit tickers) and distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on cross-venue comparison.

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

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

The description provides explicit guidance on when to use the tool (for comparing prices across venues) and when not (when compatibility_warning fires, indicating non-equivalent bet shapes or unrelated events). It also warns that real spreads are rarer than the macro-shortcut list suggests, setting proper expectations.

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

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

Annotations already declare readOnly, idempotent, non-destructive. The description adds behavior beyond annotations: listing all keys when key is omitted, scoping to identifier, and pairing with other tools.

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

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

The description is three sentences, front-loaded with the main purpose, efficient, and 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 simplicity (one optional param, no output schema, good annotations), the description fully covers behavior, scoping, and related tools, making it 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% and the description adds rich semantics: explains the effect of omitting the key (list all), provides examples like 'user_research_topic', and contextualizes typical use (ticker, address).

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

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

The description clearly states the tool retrieves saved values or lists keys, using strong verbs and specifying the resource. It distinguishes from siblings (remember, forget) by explicitly pairing them.

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 concrete use cases (target ticker, address, research notes) and explains scoping, but lacks explicit when-not-to-use instructions or alternatives for fresh data.

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 the side effect of mark_read:true, which flags events as read and affects subsequent calls. This adds value beyond annotations, which mark the tool as read-only but the description clarifies the conditional state change.

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

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

The description is four sentences, front-loaded with the core purpose, then listing key fields, filtering options, a side effect note, and an alternative access method. 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?

Without an output schema, the description explains the return fields (source, citation_uri, payload). It also mentions the alternative URL. It does not explicitly mention the limit parameter, though it is in the schema, which is a minor gap.

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

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

Schema coverage is 100%, and the description adds meaning by providing examples (e.g., type 'sec_8k', ISO timestamp) and explaining the mark_read behavior. This contextualizes the parameters beyond the schema definitions.

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

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

The description clearly states the tool pulls fired events from the subscription feed, specifying it returns recent alerts with source, citation_uri, and raw event payload. The verb 'pull' and resource 'fired events' make the purpose unambiguous.

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

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

The description explains filtering by type and since, and mentions polling works fine. It also provides an alternative API endpoint for scripts/dashboards, giving context for when to use this tool. However, it does not explicitly compare to sibling tools.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context: sources queried in parallel, fallback logic, rate-limiting behavior, and soft-fail for USPTO. 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?

Extremely concise yet packed with essential information. Front-loaded with usage examples, then details sources, parameters, and return structure. Every sentence adds value.

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

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

Even without an output schema, the description explains the return format (structured changes[] grouped by source, total_changes count, URIs). Covers multiple data sources, fallbacks, parameter formats, and sibling differentiation.

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 adds meaningful context beyond schema: explains 'since' accepts ISO date or relative shorthand, recommends '30d'/'1m' for monitoring, and clarifies 'value' accepts ticker or CIK.

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 in the last N days/weeks/months' with specific sources (SEC EDGAR, GDELT→GNews, USPTO). It distinguishes from the sibling tool entity_profile, which focuses on static profiles.

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

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

Provides clear examples of when to use (e.g., 'what's new with X', 'updates on Acme') and explicitly advises using entity_profile instead for static profiles. Also specifies fallback behavior (GDELT→GNews) and soft-fail for USPTO.

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 show idempotentHint=true and destructiveHint=false. Description adds scope by identifier, persistent vs 24-hour retention, 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?

Three sentences, each serving a purpose: purpose, usage, behavioral scope. No filler. Front-loaded with the core verb.

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 key-value store with two parameters and no output schema, the description covers purpose, usage, storage duration, and sibling pairing comprehensively.

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

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

Schema covers 100% of parameters with descriptions. Description reinforces key-value nature with examples but adds minimal new semantic 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?

The description clearly states the tool saves data for later reuse across conversations/sessions, and it distinguishes from sibling tools like 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?

Provides clear usage context: use when discovering items worth carrying forward. Pairs with recall/forget, but does not explicitly exclude other storage methods. Still strong 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 signal read-only, open-world, idempotent, non-destructive. The description adds behavioral details beyond annotations: internal cascading through multiple lookup endpoints, graceful degradation when GLEIF/OpenFIGI unavailable, explicit labeling of unresolved identifiers, and per-source attribution. This goes far beyond the annotation hints.

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

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

The description is long and detailed, but every section adds necessary context about supported types, examples, fallback behavior, and output composition. It is front-loaded with example queries and ends with efficiency notes. While verbose, the complexity of the tool justifies the length; still, it is not as concise as it could be.

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

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

With no output schema, the description takes on the burden of explaining return values. It does so extensively for both entity types, listing identifiers, sources, and handling of unresolved fields. It also covers failure modes (graceful degradation). Given the tool's complexity, the description is complete and actionable.

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

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

The schema provides basic descriptions for type and value, both with 100% coverage. The description enriches these by explaining what each type returns (e.g., company resolves to CIK, LEI, FIGI; drug resolves to RxCUI, ingredient, brand) and specifying accepted input formats like ticker, CIK, or company name. This adds meaning beyond the schema, though the schema already covers the basic semantics.

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

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

The description clearly states the tool resolves names to canonical/official identifiers, with specific verbs (resolve, look up) and resource types (company, drug). It distinguishes from siblings by stating 'Use FIRST whenever you have a name but need an ID,' positioning it as the go-to tool for name-to-ID resolution.

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 instruction: 'Use FIRST whenever you have a name but need an ID.' It also enumerates example user queries and supported entity types. While it doesn't name alternative tools explicitly, the 'Use FIRST' directive gives clear contextual guidance.

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

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

Annotations already indicate safe, non-destructive, idempotent, open-world behavior. The description adds behavioral context: it probes each entity with 'ai_visibility_check', ranks by score, and returns a ranked list with score, confidence, and signal density. This adds value without contradicting annotations.

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

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

The description is concise (3 sentences), front-loaded with the main purpose, and every sentence adds value. 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 the tool's complexity (4 parameters, no output schema), the description explains what it does, how it works (probes with 'ai_visibility_check'), and what it returns (ranked list with score, confidence, signal density). It is complete enough for an agent to understand usage.

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

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

Schema coverage is 100%, so the schema already documents parameters. The description adds additional meaning: 'First entry treated as the 'subject' for narrative; rest are competitors' and clarifies that 'models' can include 'anthropic' requiring '_apiKey'. This exceeds what the schema provides.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, ranks by score, and surfaces which is most/least recognized. It distinguishes from the sibling 'ai_visibility_check' which likely handles single entities, and 'compare_entities' which may be more general.

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 'Useful for competitive AI-marketing audits' and gives an example question. It implies when to use (comparing multiple entities) but does not explicitly state when not to use or compare to alternatives like 'compare_entities'. The sibling list provides context, but the description could be more direct about exclusions.

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

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

Annotations already declare read-only, open-world, and idempotent hints. The description adds significant behavioral context: it fans out across two services, mentions timing (bundlephobia's first measurement can take 5-30s), and explains that partial failures degrade gracefully with a sources_failed list.

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 every sentence provides useful information. It is front-loaded with the purpose and then details. Could be slightly more concise, but the length is justified by the complexity of the tool.

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

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

Given that there is no output schema, the description does an excellent job of explaining what the tool returns (summary block, per-advisory detail, links, alternative versions). It also covers ecosystem limitations, behavioral notes, and fallback mechanisms, making it complete enough for an 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%, so the schema already documents parameters. The description adds value by explaining default behavior (version defaults to latest) and the output structure (summary block, per-advisory detail, links, alternatives). However, the schema descriptions are already adequate, so a 4 is appropriate.

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

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

The description clearly states it is a composite check for adding npm packages, covering license, advisories, version history, and bundle size. It distinguishes itself from siblings by specifying the exact use case and scope (npm ecosystem only).

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

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

Explicitly says when to use the tool (when agent asks about safety/popularity/size/cost of an npm package) and what it covers. Also notes that Python, Maven, etc. fall under a different tool (deps.dev:version directly), and describes partial failure behavior.

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 safe, idempotent, open-world read. Description adds rich behavioral details: embedding model, window size, character cap with truncation flag, and return structure (offsets, scores). 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?

Concise, front-loaded, every sentence adds value. Clear structure: purpose, usage, technical details.

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, description sufficiently explains return values (passages, offsets, scores) and limitations (200K cap, truncation). Connects to sibling tool. Complete for a search tool.

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

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

Schema coverage is 100%, so baseline is 3. Description adds example queries and restates text limit, but does not significantly extend schema documentation.

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

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

The description clearly states the tool performs semantic search inside a fetched record, with specific verb and resource. It distinguishes from siblings like ask_pipeworx_grounded by focusing on internal search vs. grounding over passages.

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 use when records are too large for prompts, and pairs with ask_pipeworx_grounded. Provides clear context but lacks explicit 'when not to use' 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 mutability (readOnlyHint=false) and idempotency (idempotentHint=true). The description adds critical behavioral details: requires OAuth, caps on SMS (10/day), webhook signing and auto-disable, and persistence requirements. 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 lengthy but well-structured, front-loading the core purpose and then detailing types and delivery. Every sentence adds value, though some redundancy could be trimmed.

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

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

Given the complexity (3 params, nested objects, no output schema), the description covers purpose, auth, types, delivery channels, and constraints. It lacks explicit error handling or rate limits beyond SMS cap, but this is acceptable.

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%, yet the description enriches each parameter with concrete examples and constraints (e.g., sec_8k items codes, SMS cap, webhook HMAC signing). This adds significant meaning beyond the schema.

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

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

The description clearly states the action ('Create a proactive monitoring subscription'), the resource ('live-data event stream'), and the output ('Returns the new subscription id'). It distinguishes itself from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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 prerequisite (Pipeworx OAuth account) and provides examples for each subscription type, giving clear context for when to use. It does not explicitly state when not to use or list alternatives, but the context is sufficient for selection.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety. The description adds valuable behavioral context: the output is category-bucketed, includes exact tool+argument shapes, and draws from a live catalog. 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 front-loaded with alternative queries, then clearly explains purpose, output, parameter usage, and when to use. Every sentence adds value, though slightly verbose. Well-structured and 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?

Given a single optional parameter, complete schema coverage, and no output schema, the description fully explains the output format (category-bucketed questions with tool shapes) and use cases. It covers all essentials for an onboarding tool.

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

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

Schema coverage is 100%, baseline 3. The description adds meaning beyond the schema by listing example topic values (finance, pharma, etc.), explaining the behavior when omitted (full spread), and describing the output richness (exact tool+argument shapes from live catalog).

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 an onboarding entry point that returns category-bucketed example questions with tool and argument shapes. It uses specific verbs ('returns', 'use') and distinguishes from sibling tools like 'ask_pipeworx' by specifying it is for discovering what to ask.

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

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

The description explicitly states when to use the tool: 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains how to invoke it with or without the topic parameter. It provides clear context but lacks explicit exclusionary guidance (when not to use).

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

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

Adds ownership enforcement and deactivation behavior beyond annotations (idempotent, not destructive). No contradiction with annotations.

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

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

Two sentences, front-loaded with core action and constraints, 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?

Completely describes the behavior for a simple mutation with 1 parameter. No output schema, but the effect is clearly stated.

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 single parameter 'id' is described with origin ('returned by subscribe'), adding value beyond the schema's description. Schema coverage is 100%.

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

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

The description uses a specific verb ('Cancel') and resource ('subscription'), clearly distinguishing it from the sibling 'subscribe' tool.

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

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

States ownership enforcement and effect (deactivated, not deleted), but does not explicitly exclude use cases (e.g., that it only works for own subscriptions).

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 beyond the readOnly/idempotent annotations by defining verdict semantics, especially that could_not_verify indicates the check did not happen (and must not be presented as evidence) and unsupported means no source covers it. It also discloses the two pipeline paths and the return format with citation.

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 each section earns its place: user intent examples, purpose, routing logic, return values, and a critical caller warning. It is front-loaded with the core purpose and remains structured and readable.

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

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

With no output schema, the description compensates by enumerating the verdict types and explaining their meanings, including failure modes. It covers the two source paths, citations, and why the tool replaces a multi-step workflow, making it complete for the tool's complexity.

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

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

While the schema already documents both parameters, the description adds valuable context: it gives example claims, explains that tolerance_pct overrides the implied wording tolerance, states the default cap of 5%, and recommends 1–2% for hallucination detection. This goes well 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 performs natural-language claim verification against authoritative sources, with specific verbs like 'fact check' and 'verify'. It also distinguishes itself from sibling tools by describing its two routing paths and by noting it replaces 4–6 sequential calls.

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

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

It explicitly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also provides routing guidance for company-financial vs. any other claim, and tells callers that the tool replaces multi-step manual verification, effectively indicating when not to use a stepwise approach.

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