Congress

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

Annotations indicate read-only, open-world, idempotent, non-destructive. The description adds value by explaining cost implications (free Workers AI, BYO key for Anthropic), the scoring range, and that keys are passed through to Anthropic. This goes beyond what annotations provide.

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

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

The description is concise (4 sentences) and front-loaded with the core action. Every sentence provides essential information: what it does, output structure, default/custom options, and use cases. No redundant or vague phrasing.

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

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

The description covers the main behavior, parameters, output structure (though no formal output schema), and use cases. It lacks explicit mention of rate limits or error handling, but annotations already confirm idempotency and read-only nature. Overall, it is sufficiently complete for the tool's complexity.

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

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

Schema description coverage is 100% (all parameters described in schema). The description adds context beyond the schema: it explains that the entity is the subject, that models array is optional and defaults to workers-ai, and that _apiKey is only needed for Anthropic. It provides examples and clarifies the default model.

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 entity visibility and returns a 0-100 score per model. It specifies the verb 'probe', the resource 'LLMs', and the output format. It distinguishes from sibling tools like 'scan_competitor_ai_presence' by focusing on multi-model probing with scoring.

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 does not mention when not to use or contrast with specific siblings, but the context is clear enough for an agent to decide appropriately.

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

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

The description adds significant context beyond the annotations: it routes to thousands of sources, fills arguments, returns structured answers with citation URIs, works on every tier, and is 'one fast call'. It also explains how it handles breaking news. 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?

Despite its length, every sentence earns its place: opening directive, scope, behavior, alternatives, examples, and escalation policy. It is well-organized, front-loaded, and has no repetition or fluff.

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

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

The description covers what the tool does, when to use it, examples, and the nature of the result (structured answer with stable citations). It omits details on error handling or answer length limits, but for a router tool this is sufficient, especially given the rich annotations and 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?

The input schema already provides 100% coverage with the 'question' property and its aliases, plus examples in both schema and description. The description does not add parameter-level detail beyond what the schema offers, so the baseline of 3 applies.

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

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

The description clearly states the tool's function: 'Routes the question to the right one of 5,529 tools across 1455 verified sources' and enumerates covered domains. It distinguishes from siblings by explicitly naming ask_pipeworx_grounded and deep_research as alternatives.

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

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

The description gives explicit guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and directs when to escalate ('Step up only when needed: ... use ask_pipeworx_grounded; ... use deep_research'). It also notes that breaking news is covered by this tool, providing clear when-to-use vs. not.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive. The description adds valuable behavioral context: experimental edge, candidate routing improvements enabled live, comparison against stable router, and explicit 'Falls back to nothing — this IS a full working router.' 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?

Four sentences, each earning its place: defines the beta router, states current no-candidate state, gives usage guidance, and clarifies it is fully functional. Dense but not bloated, with front-loaded identity.

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 beta router with no output schema, the description covers purpose, current state, usage, and operational guarantee. It references the same response shape as ask_pipeworx but does not elaborate further, which is a slight gap given no 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 description coverage is 100%; all six parameters are aliases for 'question' and are fully described in the schema. The description only says 'same arguments as ask_pipeworx,' adding no new parameter meaning, so baseline 3 is appropriate.

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

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

The description clearly states this is a beta version of ask_pipeworx: an identical universal router with the same 5,529 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by emphasizing experimental routing, making the purpose and uniqueness explicit.

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

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

It explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and clarifies current behavior matches the stable router. However, it does not mention when not to use it or mention the alternative ask_pipeworx_grounded.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description goes far beyond by disclosing the extra LLM call cost, the exact success output structure, and five explicit refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error). It also clarifies that answers are extracted ONLY from tool results, setting accurate expectations about hallucination resistance. 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 dense but every sentence earns its place: purpose, mechanism, success payload, failure payload, usage context, and cost trade-off. It is well-structured in a logical flow, front-loading the key value proposition and ending with practical guidance. No filler 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?

With no output schema, the description fully compensates by enumerating the return fields ({answer, evidence, confidence, source, fetched_at, refusal_reason}) and refusal reasons. It also provides context about the tool's scale (5,529 tools, 1455 sources), the extra LLM call cost, and the high-stakes use cases. The annotations cover safety, so the description covers behavior and outcomes comprehensively.

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

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

Schema coverage is 100%, with the single meaningful parameter 'question' fully described, including aliases. The description does not add any parameter-specific semantics beyond what the schema provides, but given the high schema coverage, a baseline of 3 is appropriate.

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

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

The description clearly identifies this as a hallucination-resistant answer mode for high-stakes reads, with a specific verb ('extracts') and resource ('tool result'). It explicitly contrasts with 'ask_pipeworx' by naming the sibling and explaining the same routing but stricter extraction, making the purpose and differentiation 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?

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts (financial verdicts, legal claims, medical lookups, public statements).' It also gives a clear exclusion and alternative: 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups.' This is model behavior for usage 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds extensive behavioral context including resolution confidence, parent event extraction, news fallback, safety short-circuits, cancellation rules, and tradeability warnings. No contradiction with annotations.

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

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

The description is lengthy but well-structured, with purpose front-loaded and detailed sections for classifiers, fan-outs, response shapes, and safety. Every sentence adds specific guidance; slight verbosity is justified by complexity.

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

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

Given the tool's complexity (multiple classifiers, fan-outs, response shapes, blocking conditions), the description is extremely thorough. It covers all critical aspects including resolution rules, cancellation risk, and fallback mechanisms without relying on 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% (all three parameters described). The description adds significant value beyond schema, explaining input formats for 'market', when to use 'depth' and 'include_raw', and providing examples.

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 'research', the resource 'Polymarket bet', and the action 'pulling the relevant Pipeworx data for it in one call'. It also distinguishes from sibling tools by focusing on Polymarket bets.

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

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

The description explicitly lists use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and provides extensive examples of classifiers and fan-outs. It lacks explicit when-not guidelines 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?

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=true. The description adds significant behavioral detail beyond this: it specifies data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), mentions handling of off-calendar fiscal years, explains sorting by primary metric, and notes citation URIs in return. No contradictions with annotations.

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

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

The description is thorough but slightly verbose. It is well-structured: starting with user-facing phrases, then behavioral explanation, then per-type details. Every sentence adds value, but a few phrases like 'head to head' and 'off-calendar fiscal years handled correctly' could be integrated more succinctly. Still, it earns its length.

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

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

No output schema exists, but the description clearly states what is returned: 'paired data + pipeworx:// citation URIs per entity'. It covers the two distinct entity types, sorting behavior, and the source of data. For a comparison tool with 2 parameters and no output schema, this description is complete and leaves 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 description coverage is 100% with both parameters documented. The description adds substantial meaning: for 'type' it details the specific data fields retrieved per type (revenue, net income for companies; adverse-event counts for drugs). For 'values' it provides examples and clarifies minItems and maxItems. This enriches the schema beyond the enum and array type.

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 that the tool provides side-by-side comparison of 2-5 companies or drugs, with concrete examples like 'X vs Y' and 'rank these companies'. It clearly distinguishes itself from a single entity lookup by emphasizing parallel comparison over sequential lookups, and it differentiates from sibling tools such as entity_profile.

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

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

The description gives explicit usage guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also lists triggers (e.g., 'which is bigger', 'head to head') which helps the agent decide when to invoke this tool. No when-not-to is needed since the tool is specialized for comparison and the guidance is clear.

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

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

The description discloses significant behavioral traits beyond the readOnly/openWorld/idempotent annotations: it can return gaps[] and never invents answers, it excerpts large records semantically, it includes hop and citation_uri fields only when fetchable, it returns contradictions for standard/thorough, and it explains timing expectations. No contradiction with annotations exists.

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

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

The description is long, but every sentence carries unique information: account requirements, fallback alternatives, data source scope, operational mechanics, return packet contents, gaps/contradictions, citation guarantees, and timing. It is structured logically with clear topic shifts, though it could be tightened slightly without losing value.

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

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

For a complex tool with no output schema, the description fully explains what is returned (findings packet with verbatim evidence, confidence, source, fetched_at, citation, gaps, contradictions, hop field), how records are excerpted, and expected latency. It also covers edge cases (unfetchable citations, empty gaps for non-catalog topics) making it complete for an agent to invoke and interpret results.

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

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

Schema coverage is 100%, but the description adds meaningful context: depth is fully explained with the effect of each level (quick=3 facets, standard=5, thorough=8 plus recovery/contradiction scans), and question semantics are clarified as accepting broad/multi-part natural language. This goes beyond the schema's enum and brief 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 performs grounded multi-source research across Pipeworx's 1455 structured data sources in one call, decomposing questions into facets and routing them in parallel. It explicitly distinguishes from siblings by noting it is NOT open-web search and contrasting with ask_pipeworx for single lookups, giving a specific verb, resource, and scope.

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

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

Usage guidance is explicit and thorough: use for broad/multi-part questions over structured data; use ask_pipeworx instead for single lookups and for breaking/current news topics. It also provides account prerequisites, depth-tier guidance, and names the alternative tool, making when-to-use and when-not-to-use unambiguous.

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 valuable context: it returns top-N tools with full schemas and curated examples, ready to call directly. 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 a single paragraph that front-loads purpose and usage. While it is somewhat lengthy due to the list of topics, every sentence adds value. Could be slightly more concise by listing only a few examples, but overall well-structured.

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

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

Given the lack of an output schema, the description adequately explains return format (top-N tools with names, descriptions, full schemas, examples). The tool is moderately complex with 6 parameters and many siblings, but the description covers the main use case and distinguishes it from other tools.

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 documented. The description adds value by listing aliases for the 'query' parameter and providing example usage in the input schema examples. It clarifies that multiple parameter names are accepted.

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 'Find tools by describing the data or task.' It uses a specific verb ('find') and resource ('tools'). It distinguishes from siblings by positioning itself as the first tool to call when exploring the tool set, contrasting with other tools that perform specific tasks.

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

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

The description explicitly states when to use this tool ('when you need to browse, search, look up, or discover what tools exist') and provides a list of example topics. It also advises calling it 'FIRST' to see the option set. However, it does not explicitly mention when not to use it or alternative tools for specific queries.

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

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

The description adds significant behavioral context beyond the annotations (readOnlyHint, etc.). It details the fan-out across multiple sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), mentions that patents may soft-fail due to API sunset, and lists the exact return fields with formatting details. 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 concise given the complexity, front-loading with clear examples and a summary of behavior. Each sentence adds value—there is no fluff. The structure flows logically from purpose to details to edge cases.

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 compensates by listing all return fields (cik, company_name, recent_filings with URIs, fundamentals sorted, patents, news, LEI). It also covers edge cases (patent sunset, name not supported) and provides fallback behavior (GDELT→GNews).

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 coverage, the description still adds critical meaning: it explains that 'type' is limited to 'company', and that 'value' accepts ticker or zero-padded CIK but not names, with concrete examples ('AAPL', '0000320193'). 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 clearly states the tool's purpose: providing a full cross-source profile of a US public company. It includes specific verb phrases like 'full cross-source profile' and lists examples ('Tell me about X', 'research Acme'), making the purpose unambiguous. It also distinguishes from siblings like 'resolve_entity' by specifying when to use each.

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 to 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also notes that names are not supported and suggests using 'resolve_entity' first if only a name is available. This provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds 'clear sensitive data' but doesn't disclose additional behavioral traits beyond what annotations provide. No contradiction, but minimal added value.

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

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

Two clear, front-loaded sentences with zero wasted words. Every sentence adds value.

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

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

The tool is simple with one parameter and no output schema. The description fully covers its purpose, usage, and interaction with siblings. No gaps remain.

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

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

Schema coverage is 100% for the single parameter 'key', and its description 'Memory key to delete' is straightforward. The description adds no extra meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states 'Delete a previously stored memory by key', using a specific verb and resource. It distinguishes itself from siblings 'remember' and 'recall' by focusing on deletion.

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 scenarios: 'context is stale, task is done, or clear sensitive data'. Also recommends pairing with 'remember' and 'recall', giving clear context for usage.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds process details (fetches page, extracts title/description/links, emits markdown). 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?

Very concise, front-loaded with the main action. Every sentence adds value: purpose, process, output, use cases.

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

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

Covers all necessary aspects: purpose, process, output format, and use cases. Despite no output schema, the description explains the output adequately.

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

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

Schema coverage is 100%, so baseline is 3. Description doesn't add significant new info beyond schema, though it mentions default and max for max_links implicitly.

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

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

The description clearly states it generates an llms.txt file for any URL, with specific steps and output format. It distinguishes itself from sibling tools like ai_visibility_check by focusing on file 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 lists three use cases (client site indexing, personal project drafting, competitor auditing). Lacks explicit when-not-to-use or alternatives, but context is clear enough.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. Description adds valuable context by enumerating the specific data fields returned, beyond what annotations convey.

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

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

Two sentences, no fluff, first sentence states core purpose. Efficient and well-structured.

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

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

Given the simple one-parameter input, presence of output schema, and comprehensive annotations, the description covers all necessary context. Returns list is sufficiently detailed.

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 describes the parameter. Description does not add additional semantic information beyond the schema's 'GovTrack bill ID (numeric)'.

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 full details for a congressional bill by ID. Lists specific data returned (text, sponsors, cosponsors, committee assignments, actions, vote history), distinguishing it from sibling tools like search_bills or get_recent_bills.

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?

Implies usage when you have a bill ID and need comprehensive details. Does not explicitly state when not to use or name alternatives, but context with siblings provides some 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, and destructiveHint as true/false appropriately, indicating a safe, read-only operation. The description adds no extra behavioral detail but does not contradict annotations.

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

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

The description is a single, succinct sentence that front-loads the purpose and key details. No wasted words.

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

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

Given the simplicity of the tool (single optional parameter, output schema present), the description completely covers what the tool does and its output fields. No gaps.

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

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

The schema has full coverage (100%) for the limit parameter with a description. The tool's description does not add additional meaning beyond the schema, meeting the baseline of 3.

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

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

The description clearly states the verb 'get' and the resource 'current members of Congress', and lists the output fields (name, party, state, district, contact information). This distinguishes it from sibling tools like get_bill or 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?

The description implies usage for retrieving current member details, but does not explicitly mention when not to use it or provide alternative tools. However, given the simplicity and the context of sibling tools, it is clear enough.

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

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

Annotations already declare readOnlyHint/openWorldHint/idempotentHint/destructiveHint=false, and the description does not contradict them. It adds valuable behavioral context: the tool takes no subject/keyword, only handles open-ended recency queries, and discloses the caveat that results are 'mostly routine post-office namings' — going beyond what annotations provide.

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

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

The description is dense but well-structured: it starts with the core action, then constraints, usage examples, alternatives, and return fields. Every sentence adds information, and the ALL-CAPS emphasis on 'NO', 'OPEN-ENDED', and 'PREFER OVER' helps an agent parse key distinctions quickly. 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 having no output schema, the description lists the returned fields ('bill type, number, title, status, sponsor, and dates') and thoroughly explains the tool's limitations and selection criteria. For a simple list tool with 3 optional params, this is complete enough for an agent to invoke it correctly and interpret results.

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

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

Input schema covers all 3 parameters with 100% description coverage, including clear explanations for 'by', 'limit', and 'congress'. The description restates the 'by' concept in prose ('by introduction date or by latest action') but does not add new parameter-level details beyond the schema, so the baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'List the most recent congressional bills' and clarifies the ordering ('newest first by introduction date or by latest action'). It explicitly distinguishes itself from congress_search_bills, so the purpose is unambiguous and well-differentiated from siblings.

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

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

Provides explicit usage guidance: it names concrete question types meant for this tool ('what bills were introduced this week', 'latest bills in Congress') and gives a clear exclusion case ('If the question NAMES a bill...'). It also explicitly recommends congress_search_bills as the alternative for named subjects, making when-to-use and when-not-to-use highly actionable.

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

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

The description adds behavioral details beyond annotations: the 'newest first' ordering and the included result components (question, result, chamber, counts, date, related bill). Annotations already declare read-only, idempotent, and non-destructive, so 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?

A single sentence that is front-loaded with the core purpose and compactly lists return fields. No filler or redundancy.

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

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

For a simple list tool with two optional params and an output schema, the description fully covers purpose, ordering, scope, and return content. Safety and idempotence are captured by annotations, so the description 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?

The input schema already provides 100% description coverage for both parameters (limit and congress) with default and max values. The description adds no additional parameter semantics, so the schema carries the full weight.

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

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

The description uses a specific verb ('Get') and clear resource ('congressional votes on bills'), specifies ordering ('newest first'), and enumerates return fields. This distinguishes it from siblings like get_recent_bills and search_bills, which are about bills rather than 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 implies when to use the tool (when recent vote data is needed) but does not explicitly name alternatives or exclusions. The context is clear, and given sibling names, an agent can infer differentiation, though explicit 'use for votes instead of bills' guidance would be ideal.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. Description adds that it returns specific fields and defaults to active subscriptions only. No contradictions.

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

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

Two efficient sentences with no fluff. Front-loads the purpose, then adds usage context. Each sentence earns its place.

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

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

Given the simplicity of the tool (one optional parameter, good annotations, no output schema but description lists fields), the description is complete and sufficient for an agent to select and invoke correctly.

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

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

Schema coverage is 100% with a clear boolean description. Description adds value by specifying that it lists 'active' subscriptions by default and lists the output fields, compensating for the missing output schema.

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

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

Description clearly states 'List the caller's active subscriptions' with a specific verb and resource. It distinguishes from sibling tools like subscribe and unsubscribe by mentioning 'find an id to cancel'. It also lists the returned fields.

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

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

Provides clear context: 'Use this to review what you're monitoring before adding more or to find an id to cancel'. This tells when to use it but does not explicitly mention when not to use it, though it's implied.

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

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

Annotations only say readOnlyHint=false, destructiveHint=false, which doesn't describe side effects well. The description adds meaningful context: filing creates a claim_token, requires no account, is rate-limited to 5/day, doesn't count against quota, and the team reads digests daily. Minor gap: no explicit statement that the tool creates a persistent record on the Pipeworx side, though the token mechanism implies it.

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

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

The description is longer than typical but every sentence adds a distinct piece of operational guidance: what to report, what not to report, how tokens work, and rate limits. It's front-loaded with the core purpose and scoping in the first two sentences. Could be trimmed slightly, but the density justifies the length.

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

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

Given this is a low-complexity, no-output-schema tool with excellent parameter schemas, the description covers all needed context: when to use, what to include in the message, the claim_token lifecycle, rate limits, and the relationship to other MCP servers. No significant gaps remain for an agent to misuse this tool.

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

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

Schema covers all 4 parameters at 100% with descriptions, so baseline 3 applies. The description adds value by explaining the claim_token flow (pass it back later to read status) and advises against pasting end-user prompts into the message, but these are behavioral notes rather than parameter syntax details. It doesn't add meaning beyond the schema descriptions for type/context/message.

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

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

The description opens with a specific verb (Tell) and resource (Pipeworx team), and clearly states the four categories of feedback (bug, missing, needs to exist, praise). It distinguishes itself from siblings by explicitly scoping to 'tools served by this Pipeworx connection' and naming alternative handling for other MCP servers.

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

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

Provides explicit when-to-use guidance for each feedback type (bug vs feature vs data_gap vs praise) and a clear exclusion: don't report issues for non-Pipeworx MCP servers, with a helpful ambiguity resolution rule. Also explains the claim_token workflow for follow-up, which is essential context.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. The description adds caching (5min-1h) and data source (CF analytics engine, no PII), which provide extra context beyond annotations.

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

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

Three sentences, bullet points for use cases, front-loaded with primary output. No wasted words.

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

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

Given simple schema, full annotation coverage, and no output schema, the description fully informs the agent about purpose, usage, constraints, and returns.

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

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

Schema covers 100% with enum and description. Description reinforces window semantics and adds nuance (shorter windows for hot trends, longer for steady-state).

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 what the tool returns (top tools, top packs, total call volume) and the window parameter. Differentiates from siblings like 'discover_tools' by specifying it's about trending data.

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

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

Explicitly lists three use cases with contexts: discovering hot data sources, confirming popular tool, and checking alignment. Also explains trade-off between windows (shorter for hot, longer for steady-state).

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 as true, and destructiveHint false. Description adds critical behavioral context: fill check (theoretical vs realizable edge, thin_legs), semantic anchor (Jaccard similarity), partition filter (placeholder fraction), and response structure. 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 thorough and well-organized, front-loading purpose then detailing modes and edge cases. Every sentence adds value, though slightly verbose. Could be tightened without losing clarity.

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

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

Given the tool's complexity (multi-mode, fill check, semantic filters), the description covers all essential aspects: invocation, parameters, internal logic, response format, and trade guidance. No output schema, but response structure is described.

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

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

Schema coverage is 100%, but description adds substantial meaning: explains exactly what values to pass for event (slug or URL) and topic (seed question), and what each mode does internally. Goes beyond basic schema descriptions.

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

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

Description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks, and distinguishes three modes (no args, event, topic). It uses specific verbs and resources, and stands apart from sibling tools like polymarket_edges or polymarket_fill_risk.

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 specifies when to use each invocation mode: no args for trending scan, event for a specific market, topic for cross-event scanning. Includes recommendations ('event recommended for a specific market') and explains when not to trade via the fill check section.

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

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

The description goes far beyond annotations by detailing internal logic (three model families, Kelly calculations, slippage handling), caching behavior (1h KV-level), and diagnostics for empty segments. It also explains special cases like Fed bets being excluded. Annotations are read-only and idempotent, which is consistent with the description.

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: a clear opening sentence, followed by detailed sections on model families, opportunity fields, knobs, and response structure. Capitalized headings like 'FIVE MODEL FAMILIES' and 'TRADEABLE-EDGE KNOBS' improve scannability. While every sentence earns its place, a slightly more concise summary could have been provided, but the detail is necessary given the complexity.

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

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

Despite having no output schema, the description thoroughly explains the response structure (by_segment, fed_candidates, _diagnostics) and all important fields (edge_pp_net, kelly_fraction, market liquidity, spread, volume, 24h-move warning). It covers edge cases like Fed bets and explains why segments may be empty. For a tool with 9 parameters and complex output, this is highly 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 significant value by explaining how parameters interact (e.g., min_partition_leg_kelly versus min_kelly), providing context for defaults (e.g., slippage_pp rationalizing 0.3% based on Polymarket's fee structure and typical spreads), and clarifying tradeable-edge filters. This raises the score above baseline.

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

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

The description clearly states the verb 'scan' and 'return' with the specific resource 'top Polymarket markets where Pipeworx data disagrees with market price.' It distinguishes itself from siblings like polymarket_arbitrage by focusing on model-driven edge discovery, and the 'what should I bet on today' phrase makes the use case immediately obvious.

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

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

The description explicitly frames the tool for daily opportunity scanning ('what should I bet on today') and explains that it avoids paging through hundreds of markets. It also provides guidance on knobs like min_liquidity and max_spread_pp for filtering. However, it does not explicitly say when not to use it or name alternatives, though sibling names imply different 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?

The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds significant behavioral context: it reads snapshots, provides time-series and trend calculations, explains decay computation, notes snapshot gaps due to cache-miss, and mentions TTL limits. 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 relatively long but well-structured with clear sections for purpose, parameters, response structure, and limitations. The core question and answer are front-loaded. While every sentence earns its place, some minor tightening could improve conciseness.

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

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

Given the complexity and lack of output schema, the description thoroughly explains the return fields (tracked[], expired[], snapshot_dates[]), their structure, and limitations (60-day TTL, daily closes). It also explains derived fields like trend and decay_pp_per_day. The description is complete for an agent to understand the tool's 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% as both parameters are described in the input schema. The description adds default values and constraints (days default 14, max 30; window default '1wk') and clarifies the meaning of window as 'snapshot family'. This adds useful context beyond the schema descriptions.

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

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

The description clearly defines the tool as providing edge persistence and decay telemetry from daily snapshots. It answers a specific trader question ('how long has this edge existed and is it shrinking?') and naturally distinguishes itself from sibling tools like polymarket_edges by emphasizing time-series analysis rather than just current edges.

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

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

The description implies when to use the tool: when you need to know if an edge is fresh or aged. It contrasts a fresh wide edge with a 3-week-old one, guiding usage. However, it does not explicitly state when not to use it or name alternatives like polymarket_edges for current edges, though the sibling list makes this 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 indicate readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds behavioral details: walks the ladder, returns fill metrics and verdict, warns about thin books and partial fills. 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 long but well-structured with labeled sections. Front-loaded with core purpose. Every sentence adds value, though could be slightly more concise. Still, appropriate for the tool's complexity.

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

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

Given the two modes, multiple parameters, and detailed output (no output schema), description thoroughly explains behavior, return fields, and usage context. Provides enough information for correct agent invocation.

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

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

Schema has 100% coverage but description adds significant context: explains size_usd semantics for single-market (max spend/target proceeds) and basket (settlement notional), describes side defaults and auto-detection for basket mode. 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 the tool's primary function: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes, and explicitly relates it to 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 states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Provides rationale about thin books and directional risk, effectively guiding the agent on 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 show readOnlyHint=true, idempotentHint=true, etc. The description adds significant behavioral details: safety fields (compatibility_warning, temporal_alignment), skipped leg counters, and that most pre-mapped topics return warnings. No contradiction with annotations.

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

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

The description is well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS). It is comprehensive but slightly verbose; some sentences could be tightened without losing meaning.

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

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

Despite no output schema, the description fully explains the response structure (leg-by-leg prices, spreads, safety fields) and edge cases (compatibility warnings, temporal alignment). It covers all relevant aspects for correct usage.

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

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

Schema has 100% coverage with descriptions for all parameters. The description adds context on how parameters interact (e.g., explicit overrides topic) and lists the 10 topic shortcuts. This extra context elevates it above the baseline of 3.

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

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

The description clearly states it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from sibling tools like polymarket_arbitrage by being venue-agnostic and focusing on matched outcomes.

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

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

Explicitly describes two modes (topic shortcuts and explicit pairings) and when to use each. Provides warnings about compatibility and temporal alignment, guiding the agent when spreads are meaningful versus when they are not.

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

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

Description adds context beyond annotations: scoping to identifier and pairing with remember/forget. No contradiction with annotations (readOnlyHint, idempotentHint, destructiveHint).

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

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

Description is slightly wordy but well-structured, front-loading the main purpose. Each sentence adds value, though a minor redundancy exists.

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

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

Given one optional parameter, no output schema, and rich description covering behavior, scoping, and pairing, no evident gaps remain.

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

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

Schema covers 100% of parameters, but description adds value by explaining that omitting key lists all saved keys, augmenting the schema's 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 retrieves a previously saved value or lists all keys, with a specific verb (retrieve/list) and resource (memory key). It distinguishes from sibling tools like remember 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?

Description explicitly advises when to use the tool (look up stored context) and mentions it is scoped to an identifier. It does not explicitly state when not to use it, but the pairing with remember/forget provides implicit guidance.

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

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

The description states that setting mark_read:true flags events as read, modifying the persisted feed state. This contradicts the annotations which declare readOnlyHint=true (no state modification). Per the scoring rule, a contradiction with annotations results in a score of 1.

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

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

The description is concise, consisting of 4 sentences with no filler. It front-loads the main action and each sentence adds essential information: purpose, return details, parameter usage, and alternative access method.

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 the return structure (source, citation_uri, payload). It covers all parameters, side effects, and even provides an alternative endpoint. For a read tool with optional parameters, it is fully informative.

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

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

The schema covers all 5 parameters (100% coverage), but the description adds meaningful context: it explains the effect of mark_read on subsequent calls, notes the default limit, and suggests using type and since for filtering. This adds value beyond the schema descriptions.

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

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

The description clearly states the tool pulls fired events from a subscription feed, specifying the return fields (source, citation_uri, raw payload). It distinguishes itself by mentioning the alternative access method via GET registry.pipeworx.io/alerts.json, making the purpose distinct among siblings.

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 context on when to use this tool (polls work fine) and points to an alternative for scripts/dashboards. It suggests filtering by type and since, and explains mark_read for read tracking. However, it does not explicitly exclude other sibling tools or provide when-not-to-use scenarios.

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

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

Annotations already indicate readOnlyHint and idempotentHint. The description adds significant behavioral context: fans out to multiple sources (SEC EDGAR, GDELT→GNews, USPTO), fallback behavior, and return format (structured changes grouped by source with citations).

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 but front-loaded with example queries, then sources, parameter details, return format, and sibling distinction. Every sentence adds value; no wasted words.

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

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

No output schema exists, but the description thoroughly covers return values (changes grouped by source, total_changes count, citation URIs). It also explains source fallback and soft-fail for USPTO. Complete for a tool with 3 required params and complex 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% with basic descriptions. The description adds extra meaning: relative shorthand examples for 'since' (7d, 30d, 3m, 1y), ticker vs CIK for 'value', and confirmation that only 'company' is supported for 'type'. A small improvement over schema alone.

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

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

The description clearly states the tool provides a 'change feed for a company in the last N days/weeks/months' and lists example queries. It distinguishes from the sibling tool 'entity_profile' by contrasting dynamic changes vs static profile.

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

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

Explicit usage examples are given (e.g., 'What's new with X'). The description also tells when not to use it: 'Use entity_profile instead when you want the static profile regardless of window.' Parameter 'since' usage is explained with suggestions like '30d'.

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 significant behavioral context beyond annotations: storage is key-value scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous sessions. Annotations only provide idempotentHint=true; description enriches with lifecycle and scoping 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?

Compact and well-structured: first sentence states purpose, second sentence gives usage context, third explains storage behavior, fourth ties to siblings. No filler, every sentence earns its place.

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

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

Fully equips the agent: describes purpose, when to use, parameter semantics, storage behavior, and sibling relationships. No gaps given the tool's simplicity and existing 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 already covers both parameters with examples (100% coverage). Description reinforces that key is a label and value is arbitrary text, and explains the key-value pair concept. Slightly redundant with schema but adds contextual 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?

Explicitly states 'Save data the agent will need to reuse later', with a specific verb and resource. Distinguishes from sibling tools recall and forget by name, making its unique role clear.

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

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

Directly states when to use ('when you discover something worth carrying forward') and provides explicit alternatives (recall to retrieve, forget to delete). Also clarifies session vs. persistent memory, guiding agent 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 read-only/idempotent/non-destructive behavior. The description adds valuable context about internal cascading through multiple endpoints, graceful degradation of LEI/FIGI enrichment, and explicit handling of unresolved identifiers. This goes well beyond the annotations.

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

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

The description is long but highly structured and information-dense. It begins with illustrative examples, then states the core purpose, and systematically covers supported types and behavioral details. Every sentence adds value, with no redundant fluff.

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

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

With no output schema, the description fully compensates by explaining the return structure: identifiers with source labels, explicit unresolved list, and citations. It also covers failure modes (degradation). This makes the tool's behavior predictable in all cases.

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

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

The schema covers 100% of parameter descriptions, so baseline is 3. The description further clarifies parameter semantics by explaining what each type (company vs drug) returns and what input formats are accepted for 'value', adding meaningful context beyond the schema.

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

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

The description clearly states the tool's purpose: resolving user-spoken names to canonical/official identifiers. It provides concrete examples and explicitly says 'Use FIRST whenever you have a name but need an ID,' which differentiates it from sibling tools.

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

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

The description gives explicit usage guidance: 'Use FIRST whenever you have a name but need an ID.' It also details supported types and input formats, telling the agent exactly when to invoke this tool versus alternatives, and notes that it replaces 2-3 manual lookups.

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

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

Annotations declare readOnly, idempotent, non-destructive. Description adds process detail (probes with ai_visibility_check, ranks, outputs score/confidence/signal density). 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?

Three sentences, front-loaded with purpose, no fluff. Each sentence adds distinct 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?

Covers required and optional parameters, constraints (2-8 entities), and return structure (ranked list with metrics). No output schema, but description provides sufficient return info.

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

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

Schema coverage 100%, description adds semantic value: explains 'entities' sequence (first as subject), model selection, context disambiguation, and API key usage.

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

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

Describes specific verb 'Compare' and resource 'AI visibility across multiple entities', clearly distinguishing from sibling ai_visibility_check (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 use case ('competitive AI-marketing audits') and example question, implying when to use. Does not explicitly state when not to use but differentiation from sibling is clear.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive. The description adds detailed behavioral context: composite fan-out, return fields (summary, advisories, alternatives), partial failure handling with sources_failed, and timing note for bundlephobia first measurement. 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?

Description is moderately long but well-structured: starts with core purpose, then usage, ecosystem scope, and failure behavior. Every sentence adds value, though minor trimming possible. Front-loaded effectively.

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 lists all return fields (summary block, per-advisory detail, links, alternatives). It covers ecosystem limitation, partial failure, performance nuance, and parameter behavior. Fully complete for a composite 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 descriptions. The description adds value by mentioning scoped packages (e.g., @types/node) and default version behavior, which slightly exceeds schema. For high coverage, baseline 3, so 4 is appropriate.

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

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

Description clearly states it is a composite check for npm packages across deps.dev and bundlephobia, specifying the verb 'scan', resource 'npm package dependency', and scope. It distinguishes from siblings by noting NPM-only focus and fallback to deps.dev:version for other ecosystems.

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

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

Description explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also notes NPM ecosystem only, with indication that other ecosystems fall under deps.dev:version directly. However, it does not name the sibling tool explicitly, slightly reducing clarity.

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

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

Annotations already declare readOnly, openWorld, idempotent, and not destructive. The description adds valuable context: federal-only scope, search method (by subject or keyword), inclusion of recently introduced bills, and the specific return fields. It does not contradict 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 fairly long but well-structured, with a clear front-loading of purpose, then usage guidance, return fields, and scope limitations. Every sentence contributes actionable information, though it could be tightened slightly.

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

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

Given the presence of an output schema and rich annotations, the description covers all necessary context: purpose, usage, alternatives, expected return fields, and jurisdictional limits. It is fully sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% for both parameters (query and limit). The description adds slight nuance ('by subject or keyword') and notes that it includes recently introduced bills, but does not fundamentally extend beyond what the schema already documents.

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

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

The description clearly states a specific verb+resource ('searches US FEDERAL congressional bills') and explicitly distinguishes from siblings by noting that only this tool can filter by topic, while get_bill provides full details and get_recent_bills offers date-sorted listings.

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

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

It provides explicit when-to-use guidance ('Prefer this over a date-sorted recent-bills listing whenever the question names a topic') and when-not-to-use with alternatives ('for STATE legislature bills... use legiscan or openstates instead'). This is comprehensive.

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 (readOnly, idempotent, etc.), description adds critical behavioral details: returns top-N passages with character offsets and similarity scores, uses BGE-base-en embeddings with cosine similarity over 500-char overlapping windows, caps input at 200K chars with truncation flag. This is essential for agent understanding.

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

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

Description is front-loaded with core purpose and usage. While it includes some technical details (embedding model, window size), these are relevant for transparency. Slightly wordy but still efficient for the complexity.

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

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

Given no output schema, description explains return value (passages with offsets, scores). It covers all 3 parameters, includes pairing with a sibling, and provides technical boundaries (char limit, truncation). Annotations already address safety/correctness.

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

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

Schema already covers all parameters (100% coverage). Description adds practical examples for 'query' and notes the 'text' max length (though also in schema). This additional context improves usability without being redundant.

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

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

The description clearly states the tool performs semantic search inside a fetched record, with concrete examples like SEC 10-K body. It explicitly distinguishes from sibling ask_pipeworx_grounded by explaining their complementary roles.

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 the record is too big to cram into the prompt') and when not to (instead use ask_pipeworx_grounded after fetching). Provides clear context and alternative.

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

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

Despite annotations (readOnlyHint: false, idempotentHint: true, destructiveHint: false), the description adds significant behavioral context: requires authentication and OAuth account, phone verification for SMS, rate limits (10/day), and webhook signing. It does not contradict annotations, though the idempotentHint is not elaborated.

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

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

The description is well-structured with clear sections for types and delivery, but slightly verbose. It front-loads the core purpose and then details subtypes, making it easy to parse. Minor redundancy (e.g., phone verification mentioned twice) prevents a perfect score.

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

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

Given the tool's complexity (3 params, nested objects, no output schema), the description is thorough. It covers all subscription types and delivery options, includes constraints and prerequisites, and explains what happens with each channel. No significant 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%, so baseline is 3. The description adds substantial meaning: it provides concrete examples for each subscription type (e.g., sec_8k with items, polymarket_edge with topic), explains delivery channel fields, and notes constraints like phone verification. This goes well beyond the schema.

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

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

The description explicitly states 'Create a proactive monitoring subscription to a live-data event stream' and specifies the return value (subscription id). It distinguishes from siblings like unsubscribe and list_subscriptions by focusing on creation and listing supported subtypes.

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 clearly outlines prerequisites (Pipeworx OAuth account), lists supported types with examples, and explains delivery channels. It implicitly tells when to use this tool (to subscribe to alerts) but does not explicitly state when not to use it or contrast with alternatves like recent_alerts.

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 safe read-only, idempotent, non-destructive behavior. Description adds that it returns 'category-bucketed example questions' with 'exact tool + argument shape', drawn from a 'live catalog of thousands of tools', providing richness beyond annotations.

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

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

Description is front-loaded with synonyms and clear purpose, then details return structure and usage. Slightly verbose but every sentence adds value (guidance, examples, link to meta-tools). Could be trimmed slightly without losing meaning.

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

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

For a simple discovery tool with 1 optional param and no output schema, the description fully explains what it returns (category-bucketed examples with tool+argument), when to use it (onboarding, unknown capabilities), and how to call it. No gaps remain.

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

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

Schema has 1 optional param with 100% description coverage. Description reinforces the param's intent, listing example topics ('finance', 'pharma') and the default behavior (full spread). Adds context beyond schema's enum list.

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

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

The description clearly states the tool's purpose as 'the onboarding entry point' that returns example questions with exact tool+argument shapes. It distinguishes from sibling tools like ask_pipeworx by being the discovery tool for learning what Pipeworx can do.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools...' and provides calling guidance (full spread vs. topic focus). Does not explicitly exclude scenarios but 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?

Discloses that the row is deactivated (not deleted) and historical events remain available via recent_alerts. Adds context beyond annotations (idempotentHint, destructiveHint).

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

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

Two concise sentences with no extraneous information. Front-loaded with action and resource.

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

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

For a single-parameter tool with no output schema, description adequately covers ownership and side effects. Complete for its 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 covers 100% of parameter description (id is uuid returned by subscribe). Description adds no further semantics but is consistent.

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 'Cancel a subscription by id' with specific verb and resource. Distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Explicitly states ownership enforcement ('only cancel your own subscriptions'), guiding appropriate use. Does not mention alternatives but context with siblings implies 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 only declare safety hints (read-only, idempotent). The description adds substantive behavior: the two verification paths, exact percent-delta math, verdict values, return of actual value with citation and reasoning, and the distinction that could_not_verify is a failed check not evidence either way. This goes well beyond the annotations.

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

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

The description is dense but not bloated. It front-loads example phrases and clear use cases, then systematically covers behavior, return values, error semantics, and efficiency. Every sentence carries information relevant to the agent's decision-making, with no filler.

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

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

With no output schema, the description fully compensates by enumerating the possible verdicts, the actual value + citation + reasoning return, and the error/semantic distinctions. It also explains unsupported and could_not_verify in a way that covers edge cases, making the tool's behavior predictable without an output schema.

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

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

Though schema coverage is 100%, the description enriches both parameters. It explains that tolerance_pct overrides the claim-wording-implied tolerance, gives a practical range (0.5–50), suggests 1–2 for hallucination detection, and clarifies the default ('implied by wording, capped at 5'). This goes beyond the schema's field descriptions.

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

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

The description opens with natural-language trigger phrases and a specific verb+resource: 'natural-language claim verification against authoritative sources.' It clearly distinguishes the tool's scope (fact-checking user statements) and even notes it replaces 4–6 sequential calls, setting it apart from lower-level 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?

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct.' It also provides conditional routing (SEC EDGAR for company-financial claims, grounded pipeline for all else) and gives critical guidance on how to interpret could_not_verify vs unsupported, preventing misuse.

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