Congress

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds useful context: free default model, BYO key for Anthropic, return format with score/confidence/signals/raw_response. 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 a single, well-organized paragraph. First sentence gives core purpose, second explains defaults and keys, third specifies return format, fourth lists use cases. No filler.

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

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

All parameters are documented, return format is described (though no output schema), and use cases are provided. Could briefly mention that results are cached or that it's a probe not a search, but it's sufficient.

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

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

Schema covers all 4 parameters (100%). Description adds significant meaning: explains default model, how `_apiKey` enables Anthropic probes, and that `context` helps disambiguate. This goes 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 probes LLMs for brand visibility and returns a score (0-100). It distinguishes from siblings like 'ask_pipeworx' and 'entity_profile' by focusing on multi-model AI visibility audits.

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

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

The description explicitly lists use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring). It doesn't explicitly state when not to use, but the clear purpose implies alternatives.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds value by revealing it routes to 3,745 tools and returns structured citations. Does not cover rate limits or auth, but openWorld hint implies no special auth.

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 long but well-structured: front-loaded preference, list of sources, trigger phrases, examples. 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?

Given the tool's complexity (many siblings, broad scope), the description fully covers purpose, usage, parameters, and return style (structured citations). No important gaps.

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

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

Input schema covers 100% of parameters with clear descriptions. The description adds examples and clarifies that 'question' accepts aliases, but does not provide deeper semantics beyond the schema.

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

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

Clearly states it answers factual questions from authoritative data sources, distinguishes from web search, lists example domains and trigger phrases. The verb 'ask' and resource 'Pipeworx' are well-defined.

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 'PREFER OVER WEB SEARCH', provides detailed scenarios and trigger phrases like 'what is', 'look up', 'find'. Gives concrete examples (e.g., 'current US unemployment rate'). Strong guidance on when 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds valuable behavioral context: lists return fields (answer, evidence, confidence, source, etc.), describes refusal reasons, mentions it costs one extra LLM call, and states it uses only tool result. 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 somewhat long but each sentence adds value. It front-loads the key purpose and then explains mechanism, return format, and usage guidance. Could be slightly more concise, but not verbose or redundant.

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

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

Given the tool's complexity (grounded extraction with refusal reasons), the description covers purpose, usage, behavior, return format, refusal reasons, and performance cost. No output schema, but description fully explains return values. Highly complete for the tool's function.

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 all parameters described. Description adds context that the question parameter is used for routing and fetching, explaining the tool's mechanism beyond the schema definition. Baseline 3 is elevated due to this added context.

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 is a 'hallucination-resistant answer mode' for high-stakes reads, with specific verbs: 'extracts the answer using ONLY what the tool result contains'. Distinguishes from sibling ask_pipeworx by noting extra LLM call cost and use case for quoted/cited answers.

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

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

Explicitly says 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' Contrasts with ask_pipeworx: 'prefer ask_pipeworx for casual lookups.' Provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description greatly exceeds this by detailing fan-out patterns, response shapes, resolver contract (confidence levels, alternatives, suggestions), parent event extraction, news handling (fallback mechanisms), safety short-circuits (low confidence, closed markets), 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 well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and is front-loaded with purpose and usage. However, it is verbose and contains some redundancy (e.g., explaining low-confidence short-circuit twice). A more concise version would improve scoring.

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 (multiple classifiers, fan-outs, safety mechanisms, resolution rules) and the absence of an output schema, the description thoroughly covers all aspects an agent needs: how inputs are resolved, what evidence is returned, how to interpret results (e.g., inspect market_match_confidence), and edge cases (closed markets, wide spreads, cancellation rules).

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 three parameters. The description adds context for 'market' (examples of slugs, URLs, questions) and mentions 'depth' and 'include_raw' in the context of fan-out and response size, but this largely duplicates schema information. No additional semantic enrichment 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 starts with a clear verb-resource pair: 'Research a Polymarket bet by pulling the relevant Pipeworx data.' It explicitly states inputs (slug, URL, question) and outputs (evidence packet + comparison). The purpose is distinct from siblings like 'polymarket_arbitrage' or 'polymarket_edges', which focus on specific subtasks.

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 usage examples: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' While it does not explicitly mention when not to use or list alternative tools, the context is clear enough for an agent to infer appropriate use cases.

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

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

Annotations already indicate safe read-only, idempotent behavior. The description adds critical behavioral details: for companies it pulls latest 10-K data with correct fiscal year handling, for drugs it pulls FAERS, FDA, and trial counts. It also notes sorted results and citation URIs, going well beyond annotation hints.

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

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

The description is information-dense yet structured with examples and clarifications. It is slightly long but every sentence adds value, and key guidance is front-loaded. 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 the tool's complexity (two entity types, 2–5 items), and no output schema, the description fully explains input, behavior, and output. It covers what data is returned for each type, sorting, and citation URIs, making it self-sufficient for an AI 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 covers both parameters with descriptions, but the description adds valuable context: examples of tickers/CIKs for company and drug names, max/min items, and explains the meaning of the values. This eases correct invocation beyond 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 performs side-by-side comparisons of 2–5 companies or drugs in one call, using verbs like 'compare', 'rank', and 'head-to-head'. It distinguishes itself from other tools such as entity_profile by focusing on comparative analysis.

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

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

Explicitly instructs to 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing clear when-to-use guidance. It also quantifies the benefit by stating it 'replaces 8–15 sequential lookups,' making the advantage concrete.

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, etc.), the description adds that it is grounded, never invents (gaps[]), returns structured findings, and takes 15-60s. It also discloses account/plan requirements, adding significant 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?

While slightly long, every sentence provides useful information and the description is front-loaded with the main purpose. It is well-structured and not 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?

Despite no output schema, the description covers purpose, usage, behavior, parameters, and constraints thoroughly. It mentions return format (structured findings packet with evidence, confidence, gaps). Complete for a complex research tool.

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

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

Schema coverage is 100%, so baseline 3. The description adds meaning by explaining depth values (quick=3, standard=5, thorough=8) and that broad questions are fine due to decomposition. This adds value beyond schema.

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

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

The description clearly states the tool does grounded multi-source research in one call, decomposing questions into sub-questions and routing them to many tools/sources. It distinguishes itself from ask_pipeworx for single lookups. This is a specific verb+resource with sibling differentiation.

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

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

Explicitly advises to use for broad/multi-part questions and directs to ask_pipeworx for single lookups. Also mentions account and plan requirements, giving clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds valuable context: that the tool returns tools ready to call directly with curated examples, requires no second schema lookup, and acts as a first-step tool. This complements annotations without contradiction, providing full transparency.

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

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

The description is a single paragraph that front-loads the purpose and then provides details. It is informative without being verbose, but the list of domains could be more concise. Still, every sentence adds value, making it effective.

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

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

Given the tool's complexity (6 parameters, many aliases, no output schema), the description adequately explains what is returned: top-N tools with names, descriptions, and full schemas ready to call. It also specifies the meta-tool role. The lack of output schema is compensated by clear output description.

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

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

Schema coverage is 100% with detailed descriptions for all parameters (including aliases). The description adds a paragraph of examples and usage context (e.g., 'Natural language description of what you want to do') which enhances understanding beyond the schema. Baseline is 3 due to high coverage; the extra context justifies a 4.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists numerous domains (SEC filings, FDA drugs, etc.) and explains that it returns top-N relevant tools with names, descriptions, and full input schemas. This distinguishes it from sibling tools, which are specific domain tools, 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?

The description explicitly advises: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear when-to-use guidance and implies it should be used for discovery rather than direct data retrieval. No when-not-to-use is necessary given its meta-tool nature.

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

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

The annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral details: the patent source may soft-fail until mid-2025, the return fields and sorting order, and the fallback mechanisms (GDELT→GNews). This goes beyond the annotations to provide a realistic picture of behavior.

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

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

The description is a single dense paragraph that puts the most important information first. Every sentence serves a purpose: examples, usage priority, data sources, return structure, limitations, and parameter guidance. There is no fluff or redundancy.

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

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

Given the tool's complexity (multiple data sources, fallbacks, soft-failures), the description is remarkably complete. It explains what is returned (cik, company_name, filings up to 5 with URIs, fundamentals sorted, patents soft-fail, news fallback, LEI). Without an output schema, this provides the agent with a thorough understanding of the tool's output and behavior.

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

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

Schema coverage is 100%, so the schema already describes both parameters. The description adds value by reinforcing the input format for 'value' ('Ticker or zero-padded CIK') and explicitly stating that names are not supported, directing users to resolve_entity. It also mentions upcoming support for person/place for the 'type' parameter. This enriches the schema definitions.

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

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

The description explicitly states the core purpose: 'full cross-source profile of a US public company in ONE parallel call.' It provides numerous example queries and lists the data sources and return fields, making the tool's function crystal clear. It also distinguishes itself from chaining multiple single-purpose lookups, though it doesn't directly name specific 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?

Clear usage guidance is given: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also explicitly states when not to use it ('names not supported — use resolve_entity first') and provides examples of appropriate inputs. This helps the agent select this tool over alternatives.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, which the description reinforces. The description adds no further behavioral details (e.g., whether deletion is permanent, return value, or idempotency confirmed) 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?

Three sentences, front-loaded with the primary action, and every sentence adds value: action, usage context, and pairing advice. Nothing extraneous.

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 delete tool with one parameter and no output schema, the description covers purpose, usage context, and pairing. It does not mention return behavior, but that is minor given the tool's simplicity and annotations.

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 description restates that the key is the identifier ('by key'), but the schema already describes 'Memory key to delete' with 100% coverage. No additional constraints or format details are added.

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 ('Delete'), the resource ('previously stored memory'), and the identifier ('by key'). It effectively distinguishes from siblings 'remember' and 'recall' by specifying the opposite operation.

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

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

Explicitly provides three use cases (context stale, task done, clear sensitive data) and suggests pairing with complementary tools. However, it does not specify when not to use or contrast with alternative tools among siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds behavioral context by explaining the extraction process (title/description/key links) and output format, going beyond annotations without contradicting them.

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

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

The description is concise, front-loaded with the core action, and uses bullet points for use cases. Every sentence adds value with no wasted words.

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

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

Given the rich annotations and complete schema, the description adequately covers the output format and usage. It lacks edge case handling (e.g., non-HTML pages) but is sufficient for an informed 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 baseline is 3. The description mentions 'URL' but does not add operational detail about parameters beyond what the schema provides. No extra value added from description.

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

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

The description clearly states the verb 'Generate' and the resource 'llms.txt file for any URL'. It also specifies the output format and lists concrete use cases, distinguishing it from siblings like ai_visibility_check.

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

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

The description provides clear usage context with three example scenarios. However, it does not explicitly state when not to use the tool or mention alternative tools, missing an opportunity for clearer differentiation.

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, etc. Description adds specifics about returned data (text, sponsors, votes) and ID source (GovTrack), supplementing annotations effectively.

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 extraneous words; action, resource, and return values are front-loaded.

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

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

With an output schema present, description doesn't need to detail return format. The listed fields and ID type are sufficient for a simple one-parameter tool with strong annotations.

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 already describes the 'id' parameter as 'GovTrack bill ID (numeric)'. Description repeats this without adding new semantic detail.

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

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

Clearly states 'Get full details for a congressional bill by its ID' with specific return fields, distinguishing it from sibling tools like search_bills and get_votes.

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?

Implicitly indicates use for retrieving comprehensive bill data by ID. While no explicit when-not guidance, the context of siblings like search_bills provides alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds that the result includes name, party, state, etc., which is not in the schema, but does not disclose other behaviors like rate limits or data freshness.

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

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

Single sentence that is front-loaded with the core purpose and specific output fields. No unnecessary words.

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

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

Given the simplicity (1 parameter, rich annotations, output schema exists), the description is nearly complete. However, it omits mention of the default limit and that results are paginated, which might be needed for full understanding.

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

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

Schema covers 100% of parameters with description for 'limit'. Description does not add new meaning beyond the schema; 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?

Clearly states the tool retrieves members of Congress with specific fields (name, party, state, district, contact info). Distinguishes from sibling tools like get_bill and get_votes which focus on legislation and voting records.

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?

No guidance on when to use this tool versus alternatives like search_bills or entity_profile. No mention of filtering, pagination, or limitations.

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. The description adds the return field list but does not disclose any behavioral traits beyond what annotations cover, such as ordering, pagination, or rate limits. It is adequate but not enhanced.

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 concise sentence that immediately states the purpose and return fields. It is front-loaded with the main action ('Get recent congressional votes') and contains no 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?

Given the tool's simplicity (2 optional parameters, clear annotations, and an output schema), the description covers the essential information. It lists return fields, which is helpful even with an output schema present. Could be more precise about 'recent' ordering but overall complete.

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

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

Schema coverage is 100% with clear descriptions for both parameters ('limit' and 'congress'). The tool description adds no additional meaning beyond the schema; it mentions 'recent' but does not clarify ordering or date filtering. Baseline 3 is appropriate.

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

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

The description clearly states the tool retrieves recent congressional votes and lists the specific fields returned (question, result, chamber, vote counts, date, related bill). It effectively distinguishes from sibling tools like 'get_bill' and 'get_members' by focusing on votes.

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 no guidance on when to use this tool versus alternatives (e.g., 'search_bills' or 'get_bill'). There is no mention of prerequisites, typical use cases, or exclusions, leaving the agent to infer context from the tool name alone.

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 specify readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. Description adds minor context (return fields) but not significant beyond annotations.

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

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

Two concise sentences: first declares purpose with returned fields, second gives usage guidance. No unnecessary words, well-structured.

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

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

Tool is simple with one optional parameter and no output schema; description adequately explains return fields and appropriate usage. Annotations cover behavioral traits fully.

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?

Single parameter include_inactive has full schema description coverage (100%), so description adds no extra meaning. 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?

Description clearly states it lists the caller's active subscriptions and specifies returned fields. No explicit differentiation from sibling tools (subscribe, unsubscribe) but the purpose is evident.

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 good usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Implies when to use, though no explicit when-not or alternatives.

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

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

Annotations are neutral, but description adds that it's free, doesn't count against tool-call quota, and is rate-limited to 5 per identifier per day, which are useful behavioral details.

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

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

The description is concise (5 sentences), front-loads the core purpose, and every sentence adds value without redundancy.

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

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

Given no output schema, the description covers use cases, behavior, and constraints well; a minor gap is lack of detail on what happens after submission, but it's not critical.

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

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

Schema covers 100% of parameters with descriptions; the description adds further context on how to write the message and the meaning of enum values.

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

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

The description states it is for telling the Pipeworx team about broken, missing, or needed features, listing specific types (bug, feature, data_gap, praise) and distinguishing itself from all sibling tools, which are analytical or informational.

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 (bug, feature/data_gap, praise) and what not to do (don't paste end-user prompt), plus provides context on rate limiting and quota.

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

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

Adds valuable context beyond annotations: self-aggregating, derived from CF analytics-engine, no PII, caching behavior (5min-1h). Annotations already indicate read-only, idempotent, non-destructive; description enriches these with operational details.

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

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

Three concise paragraphs: purpose, use cases, data transparency. Every sentence adds value without redundancy.

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

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

For a simple read-only aggregator with one optional parameter and no output schema, the description fully informs about return content (top tools, packs, volume), data source, and freshness.

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?

Description reinforces the window parameter's semantics ('shorter windows surface what's hot right now; longer windows show steady-state demand'), adding meaning beyond the schema's enum and 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?

Description clearly states the tool returns aggregated trending data (top tools, packs, volume) over configurable windows, distinguishing it from siblings that handle queries, entity lookups, or feedback.

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 three explicit use cases (discovering hot data, confirming canonical tools, aligning with agent needs) but does not mention when to avoid using the tool or what alternatives exist for granular call data.

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

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

Annotations already declare readOnlyHint, openWorldHint, etc. The description adds extensive behavioral detail: how it walks child markets, checks monotonicity, computes partition checks, uses Jaccard similarity, filters placeholders, and performs fill checks with CLOB depth. 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 long but well-structured with clear sections and bullet points. It front-loads the key requirement ('REQUIRES one of event or topic'). However, some details (e.g., fill check) could be more concise or delegated to output schema if available.

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

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

The description fully explains the response structure (opportunities array with fields, partition_check for event mode) and covers edge cases (skipped_low_similarity, placeholders_filtered, fill check details). Since there is no output schema, 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 descriptions for both parameters. The description adds value by explaining the expected format (event slug or full URL for 'event', seed question for 'topic') and providing examples. Slightly beyond the baseline 3.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes two modes (event and topic) and refers to sibling tool polymarket_fill_risk for custom sizing, providing clear differentiation.

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 tells when to use each mode: 'event (recommended for a specific market)' vs 'topic (for cross-event scanning)'. It states that calling with no args fails, and provides detailed guidance on the fill check and when not to trade (realizable_edge_pp ≤ 0).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds substantial behavioral context: explains three segments, edge calculations (e.g., lognormal barrier, GDELT ratio, partition_overround), caching (1h at KV level), and diagnostics for why segments are empty.

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, then segments, knobs, and response structure. It is informative but lengthy; some technical details could be trimmed for brevity. Still appropriately sized for a complex tool.

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

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

Given 9 parameters, no output schema, and nested structures, the description is very complete. It explains the output structure (by_segment, diagnostics), caching, and edge metrics like edge_pp_net and kelly_fraction. No gaps for an AI agent to understand the tool.

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

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

Schema coverage is 100% but the description adds extra meaning for parameters like min_kelly, slippage_pp, min_partition_leg_kelly, including rationale and usage tips. Baseline 3 raised to 4 due to added value.

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

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

The description clearly states the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, with a specific verb ('scan') and resource ('top Polymarket markets'). It distinguishes from siblings like polymarket_arbitrage and polymarket_kalshi_spread by focusing on edge discovery.

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

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

The description explicitly states it's built for 'what should I bet on today' and that agents can discover opportunities without paging hundreds of markets. It provides knobs for filtering but does not explicitly exclude alternatives or mention when not to use.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds behavioral context: snapshots have a 60-day TTL, decay numbers come from daily closes, and gaps in data are due to cache-misses. No contradiction.

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

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

The description is thorough but well-structured, starting with a clear purpose, then parameters, then response fields. It could be slightly more concise but is not overly 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 no output schema, the description provides detailed explanation of response fields (tracked[], expired[], snapshot_dates[]) and mentions limits and caveats. This fully compensates for the absence of an output schema.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by explaining defaults and the response structure, including details about the snapshots and limits.

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 about edge longevity. It distinguishes itself from sibling tools like polymarket_edges by focusing on time-series analysis.

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

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

The description explains when to use it (to differentiate between fresh and old edges) and implies that polymarket_edges might be used for current snapshot. It doesn't explicitly state when not to use, but the context is clear.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds behavioral details beyond annotations: walks the ladder, returns verdict (clean/degraded/cannot_fill), identifies thin_legs, and warns about forced directional risk. 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 structured with bold headings (REQUIRES, SINGLE-MARKET, BASKET) and lists return fields. It is somewhat long but every sentence provides necessary detail. A minor improvement could be more concise grouping, but overall well-organized and front-loaded with purpose.

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

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

Given the complexity (two modes, four parameters, many return fields) and no output schema, the description thoroughly explains return values for both modes (e.g., top_of_book, vwap_fill_price, theoretical_sum, realizable_sum, thin_legs). It covers behavior, edge cases, and risks. Fully adequate for an agent to understand and invoke correctly.

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

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

Schema description coverage is 100%, so baseline 3. The description adds significant context: explains the difference between 'market' for single-market and 'event' for basket, describes default values and parameter interpretations (e.g., size_usd as settlement notional for basket). This adds meaning beyond the schema.

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

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

The description clearly states it performs a realizable-vs-theoretical edge check against live CLOB order-book depth, and distinguishes between single-market and basket modes. It lists specific return fields (top_of_book, vwap_fill_price, etc.) and a verdict. This differentiates it from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly instructs 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Also explains when not to rely on theoretical overround and warns about partial basket fills converting arb into unhedged positions, providing clear context for when to use this tool versus alternatives.

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

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

The description extensively discloses behavior beyond annotations, including response structure (leg-by-leg prices, spreads), safety fields (compatibility_warning, temporal_alignment), and edge cases. Annotations indicate read-only and idempotent; description adds value without contradiction.

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

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

The description is dense but efficient, front-loaded with core purpose, and structured with capital labels. It is slightly long but justified by the tool's complexity; 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 lacking an output schema, the description fully explains the response format (venues' leg prices, matched spreads) and safety fields. For a complex cross-venue tool, this coverage 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 coverage is 100%, so baseline is 3. The description adds context like mode interaction and override behavior, but the schema already describes each parameter. Extra semantics lift the score to 4.

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

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

The description precisely defines the tool as a cross-venue spread calculator for Kalshi and Polymarket, clearly distinguishes two modes (topic shortcuts and explicit tickers), and implies differentiation from intra-venue tools like polymarket_arbitrage.

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

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

The description provides explicit guidance on when to use the tool (same resolving question, temporal alignment) and when not (compatibility warnings, semantic mismatches). It warns that most pre-mapped topics are not tradeable, aiding in decision-making.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable context about scoping ('Scoped to your identifier'), which goes beyond annotations. No contradictions.

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

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

The description is four sentences, all front-loaded with the main purpose. Every sentence adds value: main function, usage context, scoping, and pairing. No redundant or irrelevant 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 tool with one optional parameter and no output schema, the description provides sufficient completeness: what it does, when to use, scoping, and relationships. It does not specify return format, but that is reasonable given the simplicity.

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 description for 'key'. The description clarifies that omitting the key lists all saved keys and reinforces the purpose of the key as a memory key. It adds meaningful context beyond the schema, such as scoping and pairing with other tools.

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

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

The description uses a specific verb ('Retrieve' / 'list') and clearly identifies the resource (values saved via remember). It distinguishes this tool from siblings 'remember' and 'forget' by stating its retrieval function.

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

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

The description explicitly states when to use the tool: 'Use to look up context the agent stored earlier'. It also mentions pairing with 'remember' and 'forget', giving implicit guidance on alternatives. However, it does not explicitly say when not to use it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds that mark_read mutates read state (affecting future calls), explains return format details, and confirms polling behavior. No contradiction with annotations.

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

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

The description is three sentences, front-loads the core purpose, and provides necessary details without redundancy or fluff. 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 lacking an output schema, the description covers the return format, all parameters, their effects, and mentions polling and an alternative endpoint. It is complete for a read-only filtering 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%, and the description adds meaning beyond the schema: it explains each filter (type, since, mark_read, unread_only) with examples and clarifies the effect of mark_read. It also describes the return payload, which is not in the schema.

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

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

The description clearly states the tool 'pulls fired events' from the subscription feed, listing what each alert contains (source, citation_uri, payload) and supporting filters. It is distinct from sibling tools like list_subscriptions or recent_changes.

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 its use for retrieving recent alerts and mentions that 'polls work fine', indicating suitability for polling. It also references an alternative REST endpoint for scripts/dashboards, but does not explicitly exclude other tools or state when not to use it.

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

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

Annotations already indicate read-only, idempotent, non-destructive, and open-world behavior. The description adds valuable behavioral details: fan-out to multiple sources, fallback chains, date parsing, and the return format (changes[] grouped by source, total_changes count, pipeworx:// URIs). This goes well beyond the structured annotations.

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

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

The description is front-loaded with example queries that serve as usage cues, then provides a clear definition of the tool's core function. It packs many details (sources, fallback, date formats, return structure) into a few sentences. While slightly verbose with examples, they enhance clarity without redundancy.

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

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

Given the tool's complexity (multiple sources, fallback logic, date parsing, and no output schema), the description covers all key aspects: sources, fallback, date formats, return structure, and sibling differentiation. The return type is described well enough for an agent to use the tool without ambiguity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds practical examples and context: for 'since' it shows both ISO and relative formats with common values ('7d', '30d', '3m', '1y') and suggests '30d' for monitoring; for 'value' it shows ticker and CIK examples; for 'type' it notes only 'company' is supported. This adds 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 begins with concrete example queries ('What's new with X', 'latest on Y'), then clearly states it is a 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It specifies the sources (SEC EDGAR, GDELT/GNews, USPTO) and explicitly contrasts with the sibling tool entity_profile, making the purpose distinct.

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 guidance via example queries and a direct alternative: 'Use entity_profile instead when you want the static profile... regardless of window.' It also explains fallback logic (GDELT preferred, GNews on rate limit/5xx) and a soft-fail condition for USPTO, giving clear usage boundaries.

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

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

Adds context beyond annotations: explains scoping by identifier, persistence duration (24h for anonymous, persistent for authenticated). Annotations already indicate idempotentHint=true and non-destructive; description complements well without contradiction.

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

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

Four sentences, front-loaded with purpose, no wasted words. 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 simple parameters and no output schema, the description adequately covers purpose, usage, scoping, and persistence. Pairs well with recall and forget siblings, making it complete for agent decision-making.

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

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

Schema covers 100% of parameters with descriptions. Description provides example keys and clarifies value can be any text, adding practical guidance beyond schema.

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

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

The description clearly states the tool saves data for later reuse, specifying it is key-value storage scoped by identifier. It distinguishes from sibling tools like 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?

Explicitly tells when to use: 'when you discover something worth carrying forward.' Mentions when not needed: links to recall (retrieve) and forget (delete). Provides persistence details for authenticated vs. anonymous sessions.

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=true, idempotentHint=true, and destructiveHint=false, indicating safe, non-destructive behavior. The description adds that each call cascades through several lookup endpoints internally and replaces 2-3 manual lookups, which provides useful behavioral context beyond annotations. No contradictions.

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

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

The description is slightly long but each sentence adds value: examples, use case, supported types, internal behavior, and return format. It is well-structured and front-loaded with purpose. Minor trimming possible, but overall effective.

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

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

Despite no output schema, the description thoroughly explains the return values for both entity types (company: ticker+CIK+company_name+citation; drug: RxCUI+ingredient+brand+citation). It also notes auto-disambiguation for company and internal cascading logic, making the tool fully comprehensible.

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

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

Schema coverage is 100%, but the description adds significant meaning for the 'value' parameter, detailing accepted formats (ticker, CIK, name for company; brand/generic for drug). This clarifies usage beyond the schema's generic description.

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

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

The description uses specific example queries like "What's the ticker for…" and explicitly states it resolves names to canonical/official identifiers. It clearly distinguishes from sibling tools like entity_profile or compare_entities, 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 explicitly advises 'Use FIRST whenever you have a name but need an ID.' It provides clear context for when to use the tool, though it does not explicitly state when not to use it or mention alternatives beyond implied distinction from siblings.

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

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

Annotations declare safe, read-only, idempotent behavior. The description adds that it probes each entity with `ai_visibility_check`, ranks results, and returns a ranked list with score/confidence/signal density. 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 earning its place: main purpose, process, example use case, output format. 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?

Despite no output schema, the description explains return format. Covers all 4 parameters, references sibling, explains optionality of `_apiKey`, and sets entity range (2-8). Complete for a tool with this complexity.

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

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

Schema coverage is 100%; description adds that first entity is treated as 'subject' for narrative and that `_apiKey` is only needed for 'anthropic' model. This adds value beyond schema.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, distinguishing it from sibling `ai_visibility_check` which checks a single entity.

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

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

Provides explicit usage context: 'Useful for competitive AI-marketing audits' and a concrete question. Sibling tools imply alternatives, but no explicit when-not-to-use or exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety is known. Description adds valuable behavioral details: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and sources_failed list on timeout. 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 informative but somewhat lengthy. It front-loads purpose and then provides details. Could be slightly more concise, but 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?

Given no output schema, the description fully explains the return structure: summary block, per-advisory detail, links, and recent alternative versions. Also mentions limitations (NPM only) and error handling. Complete for a read-only, idempotent tool.

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

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

Schema coverage is 100% with both parameters described. Description adds meaning by clarifying that 'package' accepts scoped packages (e.g., '@types/node') and that 'version' defaults to latest. This goes beyond the schema's basic 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?

Description uses specific verb 'scan' and resource 'dependency' combined with a clear composite check for npm packages across deps.dev and bundlephobia. It distinctly differentiates from sibling tools like 'scan_competitor_ai_presence' by focusing on package safety and cost.

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

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

Explicitly states when to use: 'whenever an agent asks 'is X safe / popular / small'' and provides an example. Limits scope to NPM ecosystem. Does not explicitly state when not to use, but the 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, idempotentHint, openWorldHint as true, and destructiveHint false. The description adds that it returns specific fields (bill type, number, title, status, sponsor, introduction date) and performs keyword search, which complements the annotations without contradiction.

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

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

The description is two sentences with no wasted words. First sentence defines purpose and output; second sentence provides actionable guidance on alternative tool.

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

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

For a search tool with 2 parameters, high schema coverage, and output schema present, the description effectively covers purpose, output fields, and alternative tool, leaving no critical gaps.

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

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

Schema coverage is 100% with both parameters described. The description does not add new information about parameters beyond what the schema provides, maintaining baseline of 3.

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

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

The description clearly states the tool searches US congressional bills by keyword, specifying the verb 'Search' and resource 'bills'. It distinguishes from sibling tool get_bill by directing to use it for full details.

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

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

The description explicitly tells when to use search vs get_bill, providing a clear alternative. It lacks explicit when-not-to-use guidance 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?

Adds valuable details beyond annotations: uses BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flagging, and that passages include offsets for verification. 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?

Concise, front-loaded with core function, then efficiently explains behavior, limitations, and pairing with sibling. Every sentence serves a purpose with no redundancy.

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

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

Covers input constraints, behavior (embeddings, windowing, truncation), output details (passages, offsets, scores), and integration hint. No output schema is compensated by clear description. Annotations are rich but description adds essential context.

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

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

Schema coverage is 100%, but the description adds examples for query, clarifies limits for text (200K chars) and limit (1-20, default 5), and provides usage guidance beyond schema descriptions.

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

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

The description clearly states the tool's purpose as semantic search inside a fetched record, specifies use cases like SEC filings, and distinguishes it from sibling tool ask_pipeworx_grounded by mentioning pairing for grounded generation.

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 when to use: 'when the record is too big to cram into the prompt', and suggests alternative ask_pipeworx_grounded. Provides clear context for selection.

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

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

Beyond annotations, the description discloses key behaviors: return of subscription id, one-time webhook secret, rate limits (10 SMS/day), auto-disable after 10 webhook failures, and auth constraints. No contradiction with annotations.

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

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

The description is front-loaded with purpose, then organized by types and delivery. It is somewhat lengthy but every sentence adds value; minor verbosity prevents a 5.

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 auth, type parameters, delivery channels, and constraints. Lacks details on response structure beyond subscription id, duplicate handling (idempotent annotation hints but not described), and subscription limits. Adequate for 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%, and the description adds substantial value: explains each type with example parameters (ticker, items, topic, series_id), delivery channel options with constraints (phone verification, webhook signing), and additional context not in schema descriptions.

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream', specifying verb (create), resource (subscription), and context. It distinguishes from siblings like list_subscriptions and unsubscribe by focusing on creation.

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

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

The description provides context on when to use (proactive monitoring), auth requirements (Pipeworx OAuth account), and type-specific examples. It implicitly distinguishes from pull alternatives but lacks explicit when-not-to-use or direct sibling comparisons.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context: returns category-bucketed example questions with exact tool+argument shapes, drawn from the live catalog. This goes 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 moderately long but highly informative, with every sentence adding value. It is front-loaded with the primary use case and triggers. Slight wordiness could be trimmed, but overall 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 no output schema, the description properly explains the return value (category-bucketed examples with tool+argument shapes). It covers purpose, usage, parameter, and output comprehensively, matching the low complexity of 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 description coverage is 100%, so the baseline is 3. The description adds meaning by listing example topic values (finance, pharma, etc.) and clarifying that omitting the parameter gives a full cross-category spread, which is not in the schema.

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

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

The description clearly defines the tool as the onboarding entry point for a new agent, returning example questions with tool+argument shapes. It distinguishes itself from siblings by focusing on 'what can I ask Pipeworx' rather than data retrieval.

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

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

The description explicitly recommends using this tool FIRST when the agent doesn't know Pipeworx's capabilities, and explains when to pass a topic vs no arguments. It does not explicitly state when not to use it or provide alternatives, but the context is sufficiently clear.

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

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

The description adds value beyond annotations by specifying ownership constraints and that the row is deactivated (not deleted), preserving historical events. Annotations already indicate non-destructive and idempotent behavior, but the description enriches this with practical implications.

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

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

Two sentences, no wasted words. The action is front-loaded, and the ownership and behavior details follow efficiently. Every sentence adds critical context.

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

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

Given low complexity (1 param, no output schema) and good annotations, the description fully covers purpose, ownership, deactivation, and links to 'recent_alerts'. No gaps remain.

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

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

With 100% schema description coverage, the baseline is 3. The description does not add additional meaning for the 'id' parameter beyond what the schema provides. The parameter usage is straightforward.

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 'cancel' and the resource 'subscription by id'. It distinguishes from siblings: 'subscribe' (opposite) and 'list_subscriptions' (listing). The action is unambiguous.

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

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

The description provides explicit ownership enforcement ('you can only cancel your own subscriptions') and explains the deactivation behavior. While it doesn't directly contrast with siblings like 'list_subscriptions', the context is clear enough for selection.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, establishing a safe, non-destructive profile. The description adds significant behavioral context: return types (verdict values, structured form, actual value with citation, percent delta), domain scope (SEC EDGAR + XBRL), and efficiency gains (replaces 4-6 sequential calls). 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 substantive but slightly verbose. It front-loads with examples and a clear definition, then transitions to domain scope and return details. Every sentence serves a purpose, but minor redundancy (e.g., repeating 'natural-language claim verification') could be trimmed. Still well-organized.

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

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

Given the tool's complexity (NLU, domain-specific fact-checking, structured output) and the absence of an output schema, the description provides all necessary context: supported claim types, data sources, return structure, and efficiency benefits. It is self-contained and complete for an AI agent to select and invoke correctly.

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

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

Schema description coverage is 100% for the single parameter, with a clear description in the schema. The tool description adds value by giving examples of valid claims and explaining the expected format (e.g., 'Apple's FY2024 revenue was $400 billion'), which goes beyond the schema. However, the schema already handles the basics, so the baseline is 3; the extra context justifies a 4.

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

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

The description clearly states the tool performs natural-language claim verification against authoritative sources, with explicit examples of user intents (fact check, verify, confirm/refute). It distinguishes itself from siblings by specifying a unique function not covered by similar tools like deep_research or ask_pipeworx_grounded.

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

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

The description explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct.' It also notes the current domain limitation to company-financial claims, providing clear context. However, it does not explicitly exclude other types of claims or mention sibling tools as alternatives for non-financial claims.

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