Grants Gov

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

Annotations already declare read-only, open-world, idempotent, non-destructive. Description adds transparency about probing multiple models, returning per-model and combined views, and that _apiKey is passed straight through. 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?

Two sentences with front-loaded purpose and action, followed by key details (default model, optional key, return structure). 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 4 parameters, 1 required, and rich annotations, description covers return structure (score, confidence, signals, raw_response, combined view) and use cases. Lacks details on what 'signals' means, but sufficient for an agent to decide and invoke.

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 slight value by noting default model and condition for _apiKey, but schema already describes each parameter sufficiently.

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 verb (probe, score) and resource (LLMs for visibility). It specifies scoring 0-100 per model and distinguishes from sibling tools like 'ask_pipeworx' or 'scan_competitor_ai_presence' by focusing on LLM knowledge probing, not general queries or competitor scanning.

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

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

Explicitly states use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. Mentions default model and BYO key for Anthropic, guiding when to use which. No explicit alternatives but context is clear enough.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so the safety profile is clear. The description adds useful context about internal routing to thousands of tools, 'works on every tier, one fast call', and stable pipeworx:// citation URIs. No contradictions with annotations.

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

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

The description is lengthy but front-loaded with the key directive 'PREFER OVER WEB SEARCH' and then organized into purpose, usage triggers, examples, and escalation paths. Every section contributes distinct information, though a bit verbose.

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

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

Given the tool's simple one-parameter input and no output schema, the description covers all essential context: what it does, when to use it, example questions, alternatives for specific needs, how citations are returned, and performance characteristics. This is complete for an agent to 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% for the 'question' parameter and aliases, so the baseline is 3. The description adds value by providing multiple example queries ('current US unemployment rate', 'Apple's latest 10-K') and clarifying that any natural-language question is accepted, which helps the agent understand the expected input format.

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: routes questions to the right one of 5,529 tools across 1455 verified sources and returns structured answers with citation URIs. It explicitly distinguishes from siblings like ask_pipeworx_grounded and deep_research by positioning this 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 gives explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and lists trigger phrases like 'what is', 'look up', 'find'. It also provides alternatives: use ask_pipeworx_grounded for hallucination-resistant answers and deep_research for multi-part questions.

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 is a beta with experimental routing that may change when candidates are tested, and it explicitly states it is a full working router, not a stub. This complements the readOnlyHint and idempotentHint annotations by explaining the variability and current equivalence to the stable version.

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 moderately concise and informative. It front-loads the beta identity and then explains the routing mechanism, current status, and usage. Some redundancy exists ('identical' and 'matches exactly'), but each sentence contributes useful context. Slightly longer than minimal, but acceptable.

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

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

The description covers the tool's experimental nature, its relationship to the stable router, and confirms it is fully functional. There is no output schema, but the description mentions 'same response shape' as ask_pipeworx, providing enough context for expected return. It does not detail response fields, but that is likely available from the sibling tool. Overall, complete for a beta variant.

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

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

The input schema has 100% coverage with descriptions for all six parameters, all aliases for 'question'. The description adds no additional parameter-specific information, so it relies on the schema. This meets the baseline but does not exceed it.

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

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

The description clearly states the tool is a beta version of ask_pipeworx, a universal router, and specifies it has the same tools and arguments. It distinguishes itself from the stable sibling by noting it has candidate routing improvements and is the experimental edge.

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 says 'Use it exactly like ask_pipeworx when you want the newest routing,' giving clear usage guidance. It also explains the current state (no active candidate) and the purpose of comparing results against the stable router, implying when the stable version might be preferred, though not explicitly stating a '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?

Beyond annotations (read-only, open-world, idempotent), the description reveals critical behaviors: refusal handling with specific refusal_reason values, return format including evidence as a verbatim quote, and an extra LLM call cost. These details give the agent a precise expectation of success and failure modes, which is especially important given no output schema.

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

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

Three information-dense sentences pack the core purpose, mechanism, return contract, usage contexts, and cost trade-off with zero wasted words. The description is front-loaded with 'Hallucination-resistant answer mode' and every sentence earns its place.

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

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

With no output schema, the description fully specifies success and refusal return shapes, lists refusal reasons, and covers when to use/not use the tool. It also explains the relationship to ask_pipeworx, making it self-sufficient for an agent to select and invoke correctly.

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

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

The input schema already covers all six parameters (aliases for question) with full descriptions, and the description adds no per-parameter semantics beyond the generic phrase 'fills arguments.' Since schema coverage is 100%, the baseline of 3 is appropriate; the description doesn't need to compensate.

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

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

The description opens with 'Hallucination-resistant answer mode for high-stakes reads' and explains that it extracts answers only from tool results, clearly distinguishing it from siblings. It specifies the exact mechanism (routing, filling arguments, fetching data, extracting) and names the alternative ask_pipeworx, making the purpose unmistakable.

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

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

It explicitly states when to use the tool: 'whenever an answer will be quoted, cited, or acted on' and lists high-stakes domains. It also provides a direct alternative guideline: 'prefer ask_pipeworx for casual lookups' and notes the extra LLM call cost, giving clear decision criteria.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false. The description goes far beyond by detailing resolver contract, parent event extraction, news fallback mechanisms, safety short-circuits (low confidence, closed markets, wide spreads), and resolution-rule risk. No contradictions with annotations.

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

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

The description is very long but well-structured with sections (classifiers, fan-out examples, response shapes, resolver contract, etc.). Every sentence provides essential information; however, some details (like specific FRED series codes) could be considered excessive. Overall, dense and valuable.

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 data sources, fallbacks, safety checks, resolution rules), the description covers nearly every aspect an agent needs to use it correctly. No output schema, but response shapes are detailed. Annotations are lean, so the description carries the full burden and succeeds.

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 good descriptions. The description adds extra context: market parameter accepts slug, URL, or question text; depth enum explains quick vs thorough with defaults; include_raw gives practical guidance (recommended false, true when needed). This adds meaningful value beyond the schema alone.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data in one call. It uses a specific verb ('Research') and resource ('Polymarket bet'), and distinguishes from siblings like polymarket_edges and polymarket_arbitrage by listing exact use cases.

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 to use for questions like 'should I bet on X' or 'what does the data say about Y'. It provides numerous examples and fan-out scenarios, implying when to use without outright excluding alternatives. Lacks explicit 'do not use when' statements but provides enough context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, etc. Description adds valuable behavioral context: uses SEC EDGAR/XBRL, handles off-calendar fiscal years, results sorted by primary metric, returns 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 information-dense but front-loaded with common query patterns. Every sentence serves a purpose, though slightly lengthy. Could be more structured with bullets, but efficient overall.

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

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

No output schema exists, so description must explain return values. It mentions paired data, sorted results, and citation URIs. Given tool complexity (two entity types, multiple data sources), coverage is good. Could add more detail on output 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%, but description enriches meaning by explaining that type='company' pulls from SEC EDGAR and type='drug' from FAERS, and values parameter specifies tickers/CIKs vs drug names. Adds real-world examples and constraints not in 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 like 'compare', 'rank', 'head to head' and clearly states the tool performs side-by-side comparison of 2-5 companies or drugs in one parallel call. It distinguishes itself from sibling tools like entity_profile by emphasizing preference over sequential 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?

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Provides when-to-use context: comparing, ranking, head-to-head. Also clarifies entity types and their data sources.

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/non-destructive, and the description adds substantial behavioral context: not open-web search, returns gaps[] and never invents findings, citations are always fetchable via pipeworx:// URIs, large records are semantically excerpted, and latency expectations (15-60s, up to ~90s). 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 content is dense and generally earns its place, but it is not front-loaded: it opens with account requirements and the signup URL rather than the core purpose. Length is justified by the tool's complexity, but the front-loading issue prevents a top score.

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 detailing the findings packet (verbatim evidence + confidence + source + fetched_at + citation), gaps[] behavior, contradictions[], and depth-specific outputs. It also covers account tiers, latency, and prohibitions (never invented), making it complete 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?

Though the schema already describes both parameters (100% coverage), the description adds important semantics: depth meanings (quick=3 facets single hop; standard adds gap recovery + contradictions; thorough adds iterative lead-chasing, paid) and explains question accepts broad/multi-part queries. This goes well beyond the schema's 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?

The description states a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources... in ONE call' and explains the decomposition/routing mechanism. It clearly distinguishes from siblings by contrasting with ask_pipeworx and open-web search, so purpose is unambiguous.

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

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

Explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data'; 'For a single lookup use ask_pipeworx'; 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'; and 'If you are not signed in, use ask_pipeworx instead'. It also gives depth selection guidelines, so usage is fully scoped.

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=true, destructiveHint=false, idempotentHint=true. The description adds key behavioral details: returns top-N relevant tools with names, descriptions, full input schemas with curated examples, ready to call directly. 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 purpose and lists many domains, but it is fairly long. However, every sentence serves a purpose (listing domains, explaining return format, giving usage advice). Minor reduction could improve conciseness 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?

Given the tool's complexity (discovery, many domains, returning schemas), the description explains what is returned (names, descriptions, schemas, examples) and provides examples in the input schema. No output schema, but the description adequately covers the return value. Context is complete.

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

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

Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description mentions that query accepts natural language and that task, q, description, search are aliases, which adds marginal value but does not go beyond what the schema provides. 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 that the tool finds tools by describing the data or task, and lists numerous specific domains (SEC filings, financials, FDA drugs, etc.), making the purpose very concrete and distinguishable from sibling tools that perform different tasks.

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 'Call this FIRST when you have many tools available and want to see the option set,' providing clear context for when to use. Does not explicitly state when not to use, but the context is sufficient for an AI 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 declare readOnlyHint and idempotentHint true. Description adds context: fans out across multiple sources, patents soft-fail until reactivated, and returns specific fields (cik, filings, fundamentals, etc.). 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?

Well-structured with examples front-loaded and details following. Slightly long but every sentence adds value. Could be more concise without losing substance.

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 explains return fields (cik, up to 5 filings with URIs, fundamentals sorted, patents with sunset note, news fallback, LEI). Covers failure modes and limitations.

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 100% so baseline 3. Description adds value by explaining accepted values (ticker or zero-padded CIK), noting names not supported, and linking to resolve_entity. Provides more semantics than the schema alone.

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

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

The description clearly states the tool provides a 'full cross-source profile of a US public company in ONE parallel call' with specific examples like 'Tell me about X' and 'company profile for Microsoft'. It distinguishes from chaining single-pack lookups by stating 'ALWAYS PREFER over chaining...'.

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 ('holistic view') and when not to use ('names not supported – use resolve_entity first'). Provides examples of accepted inputs (ticker or zero-padded CIK).

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 confirms destructive behavior (delete) and adds context about clearing sensitive data. Annotations already indicate destructiveHint=true, so description adds value beyond structured fields. Idempotency hinted in annotations but not contradicted.

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 clear, efficient sentences with no fluff. Each 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?

Simple tool with one parameter, no output schema. Description covers purpose, usage, and behavioral context completely given tool complexity.

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

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

Schema already provides 100% coverage for the single 'key' parameter with clear description. Description does not add additional meaning 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 states specific verb ('Delete') and resource ('memory by key'). Differentiates 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 states when to use: stale context, task done, clear sensitive data. Also recommends 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?

The description adds value beyond annotations by explaining the process (fetch, extract, emit) and output format. Annotations already confirm idempotent, read-only, non-destructive; description aligns perfectly with no contradictions.

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

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

Two concise, front-loaded sentences cover purpose, process, and output. Every word adds value; 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?

For a simple tool with 2 params and no output schema, the description adequately explains input (URL), optional parameter (max_links), and output (text blob). Could mention example output format, but not necessary for 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% with both parameters documented. The description does not add additional meaning beyond the schema descriptions (e.g., default and max are already stated). Baseline of 3 is appropriate.

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

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

The description clearly states it generates an llms.txt file for AI crawlers, specifying the action (generate), resource (llms.txt for a URL), and context. It distinguishes from siblings by focusing on a specific output format and use case.

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

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

The description lists concrete use cases (client indexing, own project, competitor audit) but lacks explicit guidance on when not to use or alternatives. However, sibling tools are distinct enough that confusion is unlikely.

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's job is lighter. It adds value by listing the returned data fields, which helps the agent understand what is retrieved without requiring a call.

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 clearly states the purpose, the second enumerates return fields. Every sentence earns its place, and there is no redundancy or unnecessary 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's simplicity (one required parameter), rich annotations, high schema coverage, and existence of an output schema, the description is complete. It tells the agent what the tool does, what it returns, and how to use it (via 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 coverage is 100%, so baseline is 3. The description does not add any information about the parameter beyond what is already in the schema. The parameter is well-documented in the schema itself.

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 'Fetch full details for a Grants.gov opportunity by ID', using a specific verb and resource. It lists the returned fields (synopsis, eligibility, etc.), which distinguishes it from sibling tools like search_opportunities that return only summary 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 does not explicitly state when to use this tool versus alternatives. The parameter description hints that the ID comes from search_opportunities, but the main description lacks direct usage guidance, such as 'use this after search_opportunities to get full details'.

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

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

Annotations already declare readOnlyHint, idempotentHint, and nondestructive nature. The description adds context about the scope ('the caller's'), default filtering to active subscriptions, and the specific return fields, which 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?

The description is two sentences with no extraneous information. It front-loads the core purpose and returns, then adds usage guidance. Every word contributes 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?

For a simple list tool with one optional parameter, the description is complete. It explains what data is returned and provides usage scenarios. Annotations cover safety, and the description fills in the behavioral details, making it fully 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?

Schema coverage is 100% with a well-described boolean parameter. The description does not need to add more detail, as the schema already explains 'include_inactive'. The baseline of 3 is appropriate.

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

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

The description clearly states the verb 'List' and the resource 'the caller's active subscriptions', and specifies the return fields (id, type, etc.). It distinguishes from sibling tools like subscribe and unsubscribe, which are different operations.

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

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

The description provides explicit usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This guides the agent on when to invoke the tool, though it does not explicitly mention 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?

Beyond the annotations (which are all false), the description discloses rate limiting ('Rate-limited to 5 per identifier per day'), that it is free and doesn't count against quota, and the token-based follow-up behavior ('Filing without an account returns a claim_token... pass it back later to read whether it was fixed'). It also sets expectations that the team reads digests daily, which affects response times. These are meaningful behavioral details not present in the annotations.

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

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

The description is long but every sentence serves a purpose: primary purpose, use cases, exclusion for other servers, token workflow, rate limit, and quota. It is front-loaded with the most important information and structured logically. While it could be trimmed slightly, there is no filler or repetition.

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

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

Given the tool's simplicity and the absence of an output schema, the description provides a complete operational picture: when to use, what to include, how to follow up, and constraints (rate limit, quota). It explains the claim_token response mechanism sufficiently for an agent to handle the response correctly. No critical information appears to be 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%, so the baseline is 3. The description adds meaning by explaining the claim_token workflow (file and later read status) and providing guidance on message content ('Don't paste the end-user's prompt', 'Describe the issue in terms of Pipeworx tools/packs'). This goes beyond the schema's parameter descriptions, enriching the semantics of the 'message' and 'claim_token' fields.

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 statement of what the tool does: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies the verb (tell/send feedback) and resource (Pipeworx team), and distinguishes from sibling tools by explicitly scoping to tools served by this Pipeworx connection, not other MCP servers.

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: for bugs (wrong/stale data), feature requests, data gaps, and praise. It also provides a clear exclusion: if the tool came from a different MCP server, file with that server instead. Additionally, it explains how to follow up using a claim_token, leaving no ambiguity about when and how 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?

Discloses caching behavior (5min-1h), data source (CF analytics-engine), privacy (no PII), and data format (pack, tool, count). Annotations already indicate read-only, idempotent, non-destructive, but description adds significant 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?

Description is concise (three sentences plus a bulleted list) with no wasted words. Every sentence adds value, and the structure is easy to parse.

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 simple tool (one optional parameter, no output schema, comprehensive annotations), the description covers purpose, usage, behavioral details, and parameter semantics completely. It is sufficient for an agent to invoke correctly.

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

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

Schema covers 100% with enum and description. Description adds guidance on window selection: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This enriches understanding 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 returns top tools, packs, and call volume over a window. It provides specific use cases (discovering hot data sources, confirming canonical tools, aligning use cases) and distinguishes itself from siblings like discover_tools by focusing on trending signals.

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 useful scenarios (discovering hot data sources, confirming popular tools, aligning use cases). Does not mention when not to use or alternative sibling tools, but the context is clear enough for an AI agent to decide.

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), description adds rich context: semantic anchor Jaccard threshold, partition filter for placeholder slugs, fill check against CLOB depth, and what outputs to expect. 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 detailed but well-organized with clear sections for modes and constraints. While slightly long, every sentence adds value and the structure supports quick parsing.

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 all aspects: modes, filtering, fill check, output format (opportunities array with fields). Without an output schema, description fully explains return values, making it complete for an agent.

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

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

Schema has 100% coverage with descriptions. Description adds value by noting event accepts full URLs and explaining topic mode searches related events, 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 clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) and stands out among sibling tools with its specific functionality.

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 guidance on when to use each mode: no args for trending_scan, event for specific market (recommended with slug example), topic for cross-event scanning. Includes warnings about when not to trade (realizable_edge_pp ≤ 0) and references sibling tool 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?

Annotations already indicate read-only, open-world, idempotent, non-destructive. Description adds extensive behavioral details: caching, model families, response structure including diagnostics, slippage assumptions, and Fed bets. 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?

Description is lengthy but well-structured with clear sections for model families, response fields, and knobs. Front-loaded with purpose. Every sentence adds value, though could be slightly more concise.

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

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

No output schema, but description compensates thoroughly by detailing the response structure: top-level fields, by_segment, diagnostics, and caching behavior. Covers all necessary context for an agent to understand what the tool returns and how to interpret results.

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

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

Schema coverage is 100%, so baseline 3. Description adds value by grouping parameters as 'TRADEABLE-EDGE KNOBS' and explaining their role in filtering opportunities, going 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?

Clearly states it scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. Uses specific verb 'scan' and resource 'top Polymarket markets'. Distinguishes from siblings like polymarket_arbitrage by focusing on model-driven disagreement and daily discovery.

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

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

Explicitly says it's built for 'what should I bet on today' and that agents discover opportunities without paging hundreds of markets. Provides implicit guidance on when to use it, but does not explicitly state when not to use it or mention 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 mark it as read-only, idempotent, non-destructive. The description adds valuable behavioral details: response structure (tracked, expired, snapshot_dates), history depth bounded by 60-day TTL, decay computed from daily closes, and interpretation of negative edge_pp_net. No contradictions with annotations.

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

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

The description is thorough but remains efficiently structured: overview, core question, parameters, response fields, and limitations. Every sentence adds value, though it could be slightly more concise.

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

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

Despite lacking an output schema, the description fully explains the three response arrays (tracked, expired, snapshot_dates) and their subfields, plus limits. It provides sufficient context for an agent to understand and use the tool effectively.

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

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

Schema coverage is 100% with good descriptions. The description reinforces default values and clamp ranges, and adds meaningful context like snapshot TTL limiting lookback and decay derivation from daily closes, going beyond what the schema provides.

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

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

The description clearly states the tool provides edge persistence and decay telemetry from daily snapshots, answering a specific question. It distinguishes itself from sibling tool 'polymarket_edges' by focusing on time-series analysis of edge existence and decay.

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 when to use this tool (when needing edge persistence/decay info) and provides context via the question it answers. However, it does not explicitly state when not to use it or compare with 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 read-only, idempotent, safe behavior. The description adds significant context: explains it walks the order-book ladder, returns specific fields (top_of_book, vwap_fill_price, etc.), and highlights risks like forced_directional_risk and partial fill pitfalls. 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 well-structured: core purpose first, then requirements, then mode-specific details. It is slightly long but each sentence adds necessary information. The structure aids readability.

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 comprehensively lists expected return fields for both modes (e.g., top_of_book, vwap_fill_price, capture_ratio, thin_legs, forced_directional_risk). It covers edge cases and risks, making it complete enough for an agent to understand what to expect.

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 all 4 parameters. The description enhances meaning by explaining size_usd as 'settlement notional' in basket mode, default side logic, and clarifying units. It adds value beyond the schema though the schema already covers basics.

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, and differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by specifying when to use this tool before acting on those signals.

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

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

Explicit guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also clarifies the two modes (market vs event) and explains the rationale for using this tool (theoretical overround not capturable on thin books, partial fills causing unhedged positions).

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 by explaining the two modes, compatibility warnings, temporal alignment, and skipped cross-type/subtype counters, all 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 thorough but somewhat verbose, with multiple sections and detailed safety field explanations. While well-structured and front-loaded, it could be more concise by reducing redundant elaboration.

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 full responsibility for explaining the response structure (leg-by-leg prices, top_spreads_pp, safety fields) and edge cases (compatibility_warning, temporal_alignment). This is complete and sufficient 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% (all three parameters described). The description adds context by listing valid topic values, explaining that explicit tickers override topic, and clarifying the role of each parameter. This goes 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 it is a 'Cross-venue spread between Kalshi and Polymarket for the same resolving question' and specifies two operational modes (topic and explicit). This distinguishes it from sibling tools like 'polymarket_arbitrage' or 'polymarket_edges', which are venue-specific.

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 guidance on when spreads are meaningful via compatibility_warning and temporal_alignment, and cautions that 'pre-mapped ≠ tradeable'. However, it does not explicitly contrast with sibling tools or state when to prefer this tool over alternatives.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds value by explaining scoping to anonymous IP / key hash / account ID and the ability to list all keys by omitting the argument. 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 with no wasted words. First sentence gives the core action, second provides context and pairing hints. Perfectly 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?

For a simple retrieval tool with no output schema, the description covers purpose, usage, scoping, and interaction with siblings. Missing output format details but sufficient for typical use.

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 duplicates the schema's explanation of the key parameter (omit to list all keys). No additional semantic guidance beyond what the schema already provides, 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?

Clearly states the tool retrieves a saved value or lists all keys, naming the companion tools (remember, forget) and the scope (user identifier). Distinguishes itself from siblings by explaining its role in the memory triad.

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 to look up context the agent stored earlier' and references pairing with remember/forget. Does not explicitly state when NOT to use it, but the context is clear enough for an agent to decide.

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

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

The description states that setting mark_read:true flags returned events as read, which is a mutable side effect. This directly contradicts the annotation readOnlyHint=true, indicating a serious inconsistency. The description should align with annotations.

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

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

The description is two paragraphs: the first covers purpose and return fields, the second covers parameters with examples. Every sentence adds value, and there is no verbosity. It is 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?

Despite lacking an output schema, the description explains return fields (source, citation_uri, raw payload) and mentions pagination via limit and mark_read. It covers all parameters and provides an alternative endpoint for completeness.

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

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

Schema coverage is 100%, but the description adds significant value by explaining mark_read behavior, giving concrete filter examples (e.g., 'sec_8k'), clarifying limit range (1-200, default 50), and describing the effect of unread_only. This meaningfully extends 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 'Pull fired events from your subscription feed' and specifies that it returns recent alerts with key fields (source, citation_uri, raw payload). This distinguishes it from siblings like list_subscriptions or search_opportunities, which serve different purposes.

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

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

The description provides guidance on when to use (polls work fine) and mentions an alternative endpoint for scripts/dashboards. However, it lacks explicit scenarios for when not to use or direct comparisons 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?

Description details multi-source fan-out (SEC EDGAR, GDELT→GNews fallback, USPTO), fallback behavior (GNews when GDELT rate-limited or 5xx), and soft-failure for patents due to API sunset. This complements annotations (readOnly, idempotent, openWorld) with specific behavioral context.

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

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

Description is a single dense paragraph, front-loaded with example queries. Every sentence adds value, but structure could be improved with bullet points for sources or parameters. Still efficient and clear.

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 lack of output schema, description sufficiently covers sources, grouping, citations, and parameter formats. However, it does not detail the exact structure of the changes array or total_changes count, leaving some ambiguity for an agent.

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

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

Schema coverage is 100%, but description adds value: explains since parameter accepts ISO dates or relative shorthands, recommends '30d', clarifies type is limited to 'company', and describes value as ticker or CIK. Adds pragmatic usage details 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 specifies the tool's purpose: providing a change feed for a company over a time window, with example queries like 'What's new with X'. It distinguishes from sibling tool entity_profile, which is for static profiles, achieving high specificity.

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

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

Explicit guidance on when to use this tool (recent changes feed) versus entity_profile (static profile). Also recommends typical monitoring window ('30d' or '1m') and explains parameter formats.

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 key-value storage scoped by identifier, persistence model (24h for anonymous, persistent for authenticated), and idempotent hint from 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?

Four sentences, each adds essential information. Purpose first, then usage, then behavioral details, then sibling linking. 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?

All aspects covered: purpose, parameters, behavior, storage model, and relationship to other tools. No output schema, but the description manages expectations well.

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 clear descriptions. Description adds naming conventions (e.g., 'subject_property') but does not significantly extend meaning 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?

Cleary states verb 'save' and resource 'data', with explicit examples of what to store (resolved ticker, target address, etc.). Distinguishes from sibling tools 'recall' and 'forget'.

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

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

Provides explicit when to use: 'Use when you discover something worth carrying forward.' Also explains authentication-dependent persistence and pairing with recall/forget.

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 annotations by explaining internal cascading behavior, explicit handling of unresolved identifiers, and graceful degradation (LEI/FIGI fallback). It also states output behavior such as labeling each identifier with its source, which the annotations do not cover. This adds substantive context without contradicting the readOnlyHint.

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-organized, starting with examples and a clear action statement, then details by type. Every sentence adds value, but it could be tightened (e.g., the enumeration of examples is somewhat repetitive). Preferring a slightly more compact version would improve conciseness.

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

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

Despite lacking an output schema, the description fully specifies what each type returns (CIK, ticker, LEI, FIGI for company; RxCUI, brand for drug) and even includes citation URLs. It also covers edge cases (unresolved identifiers, unavailable enrichment sources). This makes the tool well-understood even without structured output details.

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 thorough descriptions for both parameters (type enum and value format). The description roughly mirrors the schema with examples (AAPL, CIK, 'ozempic') but adds no new meaning beyond what the schema states. With 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states the action ('resolve a user-spoken NAME to the canonical/official identifiers') and the resource (entity identifiers). It distinguishes from siblings by explicitly saying 'Use FIRST whenever you have a name but need an ID' and listing supported types. The examples ('What's the ticker for…') make the purpose unmistakable.

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

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

The description provides a strong usage cue: 'Use FIRST whenever you have a name but need an ID.' It also clarifies when to use the company vs drug types. However, it does not explicitly name alternative tools or give 'when not to use' scenarios, though the 'FIRST' directive implies it precedes other lookups.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior, so the description's main contribution is revealing the probing process (calling ai_visibility_check for each entity) and the output structure (ranked list with score, confidence, signal density). No contradictions with annotations.

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

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

The description is concise, with no wasted words. It front-loads the main action ('Compare AI visibility across multiple entities side-by-side') and then efficiently explains the process, use case, and output.

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

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

With 100% schema coverage, annotations, and a clear description of the output (ranked list with fields), the description is nearly complete for an AI agent. The only minor gap is the lack of output schema, but the text sufficiently describes the return format.

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

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

Schema description coverage is 100% with all parameters documented. The description adds value by clarifying that the first entity in 'entities' is treated as 'subject' for narrative purposes, which is not in the schema, and by explaining the role of 'context' in disambiguation.

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 compares AI visibility across multiple entities side-by-side, distinguishes from the sibling 'ai_visibility_check' by framing it as a comparative ranking tool, and uses specific verbs like 'probes', 'ranks', and 'surfaces'.

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 a clear use case ('competitive AI-marketing audits') and an example question ('does Claude know about us as well as our competitors?'), implying when to use this over a single-entity check. It does not explicitly state when not to use it, but the context is 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?

The description provides extensive behavioral details beyond the annotations: it fans out across two services, returns a detailed summary block, per-advisory details, links, and alternative versions. It also warns about bundlephobia's first measurement delay and partial failure behavior, which adds significant value beyond the read-only/idempotent flags.

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 fairly long but every sentence adds value: it starts with the composite nature, lists use cases, details the return structure, and adds caveats about timeouts and ecosystem limitations. It is front-loaded with the main purpose. Minor reduction for length, but overall well-organized 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 complexity of the tool (fans out to two services, no output schema), the description is complete: it specifies the exact fields returned, includes per-advisory details, links, alternative versions, and explains partial failures. It fully compensates for the lack of output schema and handles the complexity well.

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

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

The input schema has 100% coverage for both parameters, so the description is not required to add more parameter information. While the description provides context about what the parameters are used for (e.g., package and version), it does not add new semantic constraints or formats beyond what the schema already provides. 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 that it is a composite check for evaluating npm packages, aggregating data from deps.dev and bundlephobia. It distinguishes itself from sibling tools by specifying the exact use case and ecosystem, and it provides a clear verb (scan) and resource (dependency).

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 this tool: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"' and also notes that for other ecosystems, use deps.dev:version directly, providing clear context and alternatives.

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

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

Annotations (readOnlyHint, idempotentHint, destructiveHint, openWorldHint) already provide a strong safety profile. The description adds context about searching federal funding opportunities and return fields, but this does not go significantly 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 two sentences, front-loaded with the main action, and contains no 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 the presence of an output schema, rich annotations, and 7 parameters with full schema descriptions, the description is complete. It covers purpose, filters, and return fields 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%, meaning each parameter has a description in the schema. The description provides a brief summary of filterable fields but does not add meaning beyond the schema's per-parameter descriptions.

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

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

The description clearly states the tool searches Grants.gov for federal funding opportunities, specifies the scope (currently-open or recently-closed), lists filterable fields, and mentions return fields. This distinguishes it from siblings like get_opportunity.

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

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

The description implies usage for broad searches with various filters but does not explicitly state when to use this tool versus alternatives or provide exclusions. It is clear but lacks explicit 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 indicate readOnlyHint and idempotentHint, which the description does not contradict. The description adds significant behavioral details: uses BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, and a 200K character cap with truncation flag. This goes well beyond the annotations.

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

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

The description is a single, dense paragraph that front-loads the core purpose and then efficiently covers usage, output, constraints, and internal details. No superfluous words; 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?

Despite no output schema, the description fully explains the return value (passages with character offsets and similarity scores). It covers input constraints (200K chars, truncation), pairing with a sibling, and the embedding model. For a moderately complex tool, this is comprehensive.

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 value by clarifying the 'text' parameter's maximum length (200K chars) and providing example queries for the 'query' parameter. It also states default for 'limit' (5), which is not in the schema description.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' and gives concrete examples (SEC filing, article, tool result). It specifies the action (search), resource (a record's text), and the output (top-N passages with offsets and scores). This differentiates it from siblings, especially by mentioning pairing with 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?

Explicitly states when to use: 'Use when the record is too big to cram into the prompt'. It explains the benefits (saves context, returns only relevant passages, provides offsets for verification). It also guides on pairing with ask_pipeworx_grounded, giving clear usage context.

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

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

Beyond annotations (readOnlyHint=false, idempotentHint=true, etc.), the description adds operational details: OAuth requirement, delivery caps, phone verification, webhook auto-disable. It does not contradict annotations, though idempotency is not explicitly addressed.

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 fairly long but every sentence adds essential information. It front-loads the core purpose and uses structure (bulleted types, delivery options) to aid readability. Minor 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 no output schema, the description adequately explains the return (subscription id). It covers all key aspects: types, parameters, delivery, constraints, verification, caps, and webhook details. 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%, but the description greatly enriches parameter meaning with concrete examples for each type and delivery channel, including webhook signing details. It adds significant value beyond the schema.

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

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

The description clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream.' It uses a specific verb ('Create') and resource ('subscription'), and distinguishes it from siblings like unsubscribe and list_subscriptions.

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

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

The description provides prerequisites (Pipeworx OAuth account), supported types with examples, and delivery channel constraints. It implicitly differentiates from siblings by focusing on creation, but could explicitly mention when not to use (e.g., if already subscribed).

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. Description adds valuable behavioral details: returns 'live catalog' of examples, each with exact tool and argument shape, and is the onboarding entry point. 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?

Front-loaded with example queries, then explains function. Slightly long single sentence but packs all needed information. Good structure overall.

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 one optional parameter with full schema coverage, annotations present, and no output schema needed, description fully explains tool's purpose, usage, and output structure. Complete for an exploration 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% for the single optional parameter. Description adds that omitting topic gives cross-category spread, which is already implied by schema description. Value added is minimal 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 it's the 'onboarding entry point' for exploring Pipeworx capabilities, returning category-bucketed example questions with tool+argument shape. It distinguishes from siblings by saying 'Use this FIRST when you do not yet know what Pipeworx can do for you', unlike other tools like ask_pipeworx or entity_profile.

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

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

Explicitly advises using this tool first for onboarding and learning how to call meta-tools. Provides context on when to omit or include the topic parameter. Does not explicitly state when not to use it, but gives clear 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?

Adds key behavioral details beyond annotations: ownership enforcement and deactivation rather than deletion, ensuring historical events remain available. Consistent with idempotentHint and 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?

Two sentences, each adding distinct value. Front-loaded with action and purpose. No redundancy or 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?

For a simple mutation tool with one parameter, the description fully covers purpose, constraints, and side effects. No output schema needed for clarity.

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 description adds little beyond identifying the parameter as 'id' and referencing that it comes from 'subscribe'. 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?

Clear verb 'Cancel' with specific resource 'subscription by id'. Distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by specifying ownership enforcement and deactivation behavior.

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

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

States when to use (cancel subscription), ownership constraint (only own), and effect (deactivated not deleted). Does not explicitly list when not to use, but context is 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 read-only/idempotent, but the description adds substantial behavioral context: the full list of verdicts, the semantic difference between 'could_not_verify' and 'unsupported', the presence of verification_error{stage,detail}, and instructions not to treat could_not_verify as evidence. This exceeds 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 longer than typical, but every sentence earns its place. It is well-structured: trigger phrases, purpose, pipeline branching, return values, and critical caller caveats. No filler, though the length could be slightly trimmed without losing 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?

Despite lacking an output schema, the description inventories the complete return envelope: verdict values, actual value with pipeworx:// citation, and reasoning. It also explains failure modes ('could_not_verify' vs 'unsupported') and the two processing paths, making the tool's behavior fully understandable for an agent.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful nuance for tolerance_pct: default behavior (implied by wording, capped at 5), override semantics, and a specific use case (hallucination detection with 1–2%). This goes beyond the schema and helps callers set the parameter correctly.

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

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

The description opens with explicit trigger phrases and immediately defines the tool as 'natural-language claim verification against authoritative sources'. It distinguishes between company-financial claims (SEC EDGAR + XBRL fast path) and any other factual claim (grounded pipeline), clearly setting it apart 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?

Provides explicit usage guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also clarifies the routing for two claim types and explains that 'could_not_verify' means the check did not happen, which prevents misuse of the tool's results.

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