Senate Lobbying

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable context: Workers AI is free, Anthropic calls require BYO key and direct billing, return format includes per-model {score, confidence, signals, raw_response} and a combined view. 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, well-structured paragraph of 4 sentences. It front-loads the core action and scoring, then details parameters and use cases. Every sentence serves a purpose with no redundancy or fluff.

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

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

Given the tool's moderate complexity (4 params, no output schema), the description covers return format, optional parameters, cost implications, and example entities. Minor gap: 'signals' in the return object is not explained, but overall completeness is high.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description elaborates beyond the schema: defines 'entity' as 'The thing to ask about...', explains the 'models' parameter supports specific values, clarifies the optional `_apiKey` relationship with Anthropic, and adds context about cost implications. This adds meaningful value.

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

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

The description clearly states the tool probes LLMs for entity knowledge and returns a visibility score (0-100). It specifies default model and optional Anthropic integration. However, it does not explicitly differentiate from sibling tools like 'deep_research' or 'scan_competitor_ai_presence', which may have overlapping functionality.

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

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

The description lists use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It explains when to use the `_apiKey` parameter (if Anthropic probing is desired). It does not provide explicit when-not-to-use scenarios or compare to alternatives, but the context is sufficient for most agents.

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 context beyond annotations: it routes to 5,008 tools, fills arguments autonomously, and returns structured answers with stable citation URIs. This complements the readOnlyHint and idempotentHint annotations, with no contradictions.

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

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

The description is relatively long but well-structured with clear sections for usage guidance, examples, and tool comparisons. It earns its length by providing essential decision-making context, though slight trimming 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?

The description is complete given the tool's complexity: it covers purpose, usage, input examples, output format (citations), and alternative tools. No output schema exists, but the description adequately explains what to expect.

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

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

The schema covers 100% of parameters with descriptions, and the description adds value by providing examples of valid questions and noting aliases for the main parameter. This goes beyond the schema alone.

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

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

The description clearly states the tool's purpose: answering factual questions about current or historical data with structured citations. It distinguishes from siblings like web search and other Pipeworx tools by emphasizing its breadth and reliability.

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 provides when to use the tool (most factual questions) and when to use alternatives (ask_pipeworx_grounded for single verified answers, deep_research for broad queries). It also advises preferring it over web search for authoritative data.

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

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

Discloses beta status, candidate routing improvements, source-preference ranking, and that it's a full working router. No contradictions with annotations, which already indicate read-only, open-world, idempotent, non-destructive behavior.

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

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

Single paragraph with key information front-loaded (beta status, identical to ask_pipeworx). Slightly dense but each sentence adds value; could be shortened slightly but maintains 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?

For a complex tool (beta router with experimental features), description explains experimental nature, source-preference ranking, comparison purpose, and lack of fallback. No output schema, but states same response shape as stable router, which is sufficient.

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

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

Input schema has 100% coverage with clear descriptions for each parameter (aliases and natural language). The description does not add further semantic detail beyond what the schema provides, which is already sufficient.

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 identifies as the beta version of ask_pipeworx with identical tools but experimental routing improvements, specifically source-preference ranking. Distinguishes from sibling tools by being the experimental edge.

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

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

Explicitly states when to use: for newest routing and comparing against stable router. Implicitly suggests not using for stable routing by referencing ask_pipeworx. Provides clear context but could explicitly mention alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true. The description adds substantial behavioral context: hallucination-resistant process, picking tools, filling arguments, extracting answers, and listing specific refusal reasons. No contradiction.

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

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

The description is well-structured with a clear first sentence stating purpose, followed by process, return format, and usage guidance. While slightly long, every sentence adds necessary information with minimal redundancy.

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

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

Given the tool's complexity (high-stakes, many sources, extra LLM call), the description is highly complete. It explains failure modes, when to use vs. sibling, return format, and refusal reasons. No output schema but return format is described in detail.

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 parameters are well-documented in the schema. The description adds value by stating the question accepts natural language and listing aliases (query, q, prompt, etc.), which aids understanding beyond the schema.

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

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

The description clearly states the tool's purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It specifies it extracts answers only from tool results, distinguishes from ask_pipeworx by noting extra cost and use case, and provides return format details.

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

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

Explicitly states when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with examples. Also advises when not to use: 'prefer ask_pipeworx for casual lookups,' providing clear guidance.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. The description goes far beyond by detailing fan-out behavior, response shapes, resolver contract, parent_event extractor, news fields handling, safety short-circuits, closed market handling, wide-spread illiquidity notes, and resolution-rule risk. No contradictions with annotations; adds rich behavioral context.

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

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

The description is long but well-structured with clear sections (purpose, classifiers, fan-out examples, response shapes, resolver, parent event, etc.). It is dense but every sentence adds value. Could be slightly more concise, but organization aids readability.

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

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

Given no output schema, the description thoroughly explains the response structure (result.market, result.analysis, result.evidence) and edge cases (low confidence, closed markets, wide spreads, resolution rules). It covers error states and blocking behavior. Complete for a research tool.

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

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

Schema coverage is 100% with descriptions for all three parameters. The tool description adds additional meaning: for 'depth' it explains 'quick=2-3 evidence sources, thorough=full fan-out'; for 'market' it gives examples; for 'include_raw' it explains the trade-off. It also mentions default behavior not in schema. Adds significant value beyond schema.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data, with specific verb+resource. It provides ample detail on what it does, though it does not explicitly differentiate from sibling tools like polymarket_edges. The level of detail helps distinguish it from other 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 explicitly states when to use: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides concrete examples and fan-out patterns. However, it does not mention when not to use or alternatives like polymarket_edges, but the guidance is still clear and helpful.

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 confirm read-only, idempotent, open-world, non-destructive behavior. The description adds valuable context: for companies, pulls latest 10-K data from SEC EDGAR/XBRL with correct off-calendar fiscal year handling; for drugs, FAERS adverse events, FDA approvals, active trials. Results are sorted by primary metric and include citation URIs.

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

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

The description is somewhat long but each sentence adds value. It starts with typical query patterns, gives a strong usage directive, then details data sources and behavior. Could be slightly more concise, but structure is logical and front-loaded.

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

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

With only 2 parameters and no output schema, the description provides sufficient context: it explains what data is returned (paired data + citation URIs) and that results are sorted by primary metric. It does not detail exact output format or pagination, but for a comparison tool it covers key aspects.

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 meaningful context: 'values' for company are tickers/CIKs with examples ['AAPL','MSFT'], and for drug are names with examples ['ozempic','mounjaro']. This clarifies expected input 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 that this tool performs side-by-side comparisons of 2-5 companies or drugs in a single parallel call. It distinguishes itself from single-entity lookups like entity_profile by explicitly recommending this tool over sequential lookups.

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

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

Provides strong guidance to prefer this tool when comparing entities, with example queries like 'compare X and Y' and 'rank these companies'. However, it does not explicitly mention siblings like entity_profile as alternatives for single-entity 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?

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are present and the description adds rich behavioral context: parallel tool routing, gap reporting, contradiction scanning, hop fields, citation URIs, semantic excerpting, and timing estimates. 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 comprehensive but slightly lengthy. It is well-structured with important information front-loaded (account requirement, fallback). Every sentence adds value, but some redundancy could be trimmed. Still, it remains clear and scannable.

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

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

Given no output schema, the description thoroughly explains the return format (findings packet with verbatim evidence, confidence, source, fetched_at, citation_uri, gaps, contradictions). It covers timing, iteration behavior, and edge cases like large records being semantically excerpted. It is complete for a complex tool.

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

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

Schema description coverage is 100%, and the description adds significant meaning beyond the schema: explains the depth parameter's options (quick, standard, thorough) with details on facet counts, gap recovery, and contradiction scans. The question parameter is described as accepting natural language and broad/multi-part queries.

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 structured data sources in one call, distinguishing it from siblings like ask_pipeworx and ask_pipeworx_grounded. It uses specific verbs ('decomposes', 'routes', 'returns') and specifies the resource (Pipeworx's structured data sources).

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 guidelines are provided: use for broad/multi-part questions, not for breaking news or single lookups. Alternatives (ask_pipeworx) are named, and fallback instructions (if not signed in) are given. The description also advises when to prefer ask_pipeworx over this tool.

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

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

Annotations declare readOnlyHint, idempotentHint, and non-destructive nature. The description adds valuable behavioral details: returns top-N tools with schemas and examples, and results are ready to call directly. No contradictions.

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

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

Four sentences, front-loaded with purpose and examples, each sentence provides essential information without redundancy.

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

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

Despite no output schema, the description fully explains what is returned (names, descriptions, schemas). With 6 parameters mostly aliases, the description covers usage 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%, but description adds context by listing aliases (task, q, description, search) and explaining the limit parameter, which enhances understanding beyond the raw schema.

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

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

The description uses a specific verb ('Find tools') and clearly states the resource ('by describing the data or task'). It lists numerous domains, distinguishing it from sibling tools that perform specific operations.

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

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

Explicitly advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer),' providing clear guidance on when to use versus when 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 mark it as read-only, open-world, and idempotent. The description adds meaningful behavioral context: it makes a single parallel call, fans out across multiple sources, soft-fails for patents after May 2025, and returns specific fields. This supplements the annotations without contradiction.

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

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

The description is dense but front-loaded with example queries. Every sentence serves a purpose, though slightly verbose. It could be trimmed without losing meaning, but the structure is effective for an agent.

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

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

Given the tool's complexity (multiple data sources) and the absence of an output schema, the description thoroughly explains what is returned: CIK, company name, recent filings with URIs, fundamentals (sorted), patents with status, news via GDELT/GNews, and LEI. It also notes the patent API sunset and soft-fail behavior. This is comprehensive and leaves no major 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 input schema covers both parameters with 100% description coverage. The description adds practical semantics: value can be ticker (e.g., 'AAPL') or zero-padded CIK (e.g., '0000320193'), and names are not supported. This is more than the schema's basic description and helps correct tool invocation.

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 provides a 'full cross-source profile of a US public company in ONE parallel call.' It lists specific data sources (SEC, XBRL, USPTO, news, GLEIF) and return fields (CIK, filings, fundamentals, patents, news, LEI). Example queries like 'Tell me about X' or 'company profile for Microsoft' make the purpose immediately understandable and distinguish it from sibling tools like resolve_entity.

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

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

The description explicitly advises: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also clarifies input limitations: 'Pass ticker or zero-padded CIK — names not supported (use resolve_entity first if you only have a name).' 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 provide destructiveHint=true and idempotentHint=true. Description is consistent and adds that it deletes a previously stored memory by key. Could add detail about idempotency (deleting non-existent key is no-op), but annotations cover that sufficiently.

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 with no wasted words. First sentence states the action, second gives usage context, third references related tools. Front-loaded and efficient.

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

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

For a simple delete operation with one parameter and no output schema, the description, combined with annotations and schema, is complete. It covers purpose, usage, and relation to siblings.

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

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

Schema coverage is 100% and the parameter description already states 'Memory key to delete'. The description reinforces the same meaning without adding new nuance beyond 'previously stored', which implies existence. Baseline 3 is appropriate.

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

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

Description clearly states it deletes a previously stored memory by key. It uses a specific verb (delete) and resource (memory by key), and distinguishes from siblings 'remember' and 'recall' by indicating they pair together.

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: when context is stale, task is done, or to clear sensitive data. Also mentions pairing with remember and recall, providing alternatives for storage and retrieval.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds process details (fetch, extract, emit) and output format, enhancing transparency beyond annotations.

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

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

Three concise sentences plus a bullet of use cases, no wasted words, main purpose immediately stated.

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 100% schema coverage, clear annotations, and no output schema, the description provides sufficient context for correct invocation and understanding of output.

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

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

Schema covers both parameters with descriptions. Description repeats the constraints (max_links default 25 max 50) but does not add new meaning beyond the schema.

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

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

Clearly states verb 'generate', resource 'llms.txt file', and purpose for AI crawler indexing. Distinguishes from siblings by focusing on a specific output format.

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 use cases (client indexing, personal project, competitor auditing) but does not mention when not to use or contrast with similar tools like scan_competitor_ai_presence.

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 safety profile (readOnly, idempotent). Description adds 'Keyless' (no auth required) and enumerates return content, adding value beyond annotations.

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

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

Single sentence conveying purpose and data fields, plus example and keyless note. No wasted words, though could be slightly more 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?

No output schema, but description lists key return data (registrant, client, finances, activities). Sufficient for a detail retrieval tool with rich annotations.

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

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

Schema coverage 100% with description. Description provides example UUID, which adds clarity beyond schema. Baseline 3 for coverage, +1 for example.

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 specifies verb 'Get', resource 'filing', and lists exact data fields. Distinguishes from sibling 'search_filings' which returns a list.

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

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

States the tool is for getting a single filing by UUID, with example. Does not explicitly mention when not to use or alternatives, 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?

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false, which describe safety and idempotency. The description adds value by stating it returns 'valid general issue area codes' and giving examples, but does not introduce new behavioral traits beyond what annotations cover. It is consistent with the annotations.

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

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

The description is extremely concise: two sentences. The first defines the tool's purpose and connection to another tool. The second provides examples and notes the lack of parameters. Every word adds value with no redundancy.

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

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

For a tool with no parameters and no output schema, the description is fully complete. It explains what the tool does, its relationship to search_filings, and provides representative examples. No additional context is required.

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?

There are no parameters, and the schema coverage is 100% (empty). The description reinforces this by saying 'Keyless,' indicating no parameters are needed. Since there are no parameters to document, a score of 4 (baseline for 0 params) is appropriate.

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

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

The description clearly states the tool lists 'valid general issue area codes used by LDA filings' and explicitly ties them to the 'issue' filter on search_filings. It gives concrete examples (TAX=Taxation, HCR=Health Issues, ENV=Environment) which quickly convey the resource. This distinguishes it from sibling tools like search_filings which are for searching filings, not listing codes.

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 indicates when to use this tool: when you need the codes accepted by the `issue` filter on search_filings. It implicitly communicates that this is a preparatory step before using search_filings. It does not explicitly mention when not to use it or list alternatives, but for a simple lookup tool, the context is clear.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and non-destructive behavior. The description adds context about the return fields and the effect of the 'include_inactive' parameter, enhancing transparency beyond annotations.

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

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

Two concise sentences: first states purpose and return fields, second provides usage guidance. No unnecessary words, front-loaded with key information.

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

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

For a simple read-only list tool with one optional parameter and no output schema, the description covers purpose, return structure, and usage context 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% with a single parameter described in the schema. The description does not add additional semantic detail for the parameter beyond what the schema provides, but it does list return fields which aids understanding.

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

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

The description clearly states the tool lists the caller's active subscriptions and enumerates the return fields (id, type, etc.). It distinguishes itself from sibling tools like 'subscribe' and 'unsubscribe'.

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

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

The description provides explicit usage guidance: review before adding more subscriptions or find an id to cancel. It implies when to use but does not explicitly state when not to.

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 rate limiting (5 per identifier per day), free status, and that it doesn't count toward quota. Annotations are all false, so description adds all necessary behavioral context; 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 purpose, followed by usage guidelines, format instructions, and rate limits. Every sentence adds value with no redundancy.

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

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

For a simple feedback tool with 3 parameters and no output schema, the description covers purpose, usage, format, team impact, and constraints completely.

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

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

Schema coverage is 100% with good descriptions, but the tool description adds specific examples (e.g., 'fred' for pack, 'fred_get_series' for tool) and explains the enum values in more detail, enhancing clarity 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 sends feedback about Pipeworx, listing specific categories (bug, feature, data_gap, praise). It distinguishes from sibling tools, which are all query or research tools, not feedback.

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

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

Explicitly states when to use for bugs, missing features, or praise. Provides guidance on formatting (describe in terms of tools/packs, avoid pasting prompts). Also mentions rate limits and free 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 indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds value by disclosing data source (CF analytics-engine), privacy (no PII), and caching (5min-1h), providing context beyond the annotations.

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

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

The description is well-structured with bullet points and concise sentences. It efficiently conveys the tool's function, use cases, and behavioral traits without unnecessary 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?

Given the tool's simplicity and lack of output schema, the description adequately explains what is returned (top tools, packs, volume). It is complete enough for an agent to understand the tool's capabilities and limitations.

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

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

The single parameter 'window' is fully described in the schema with enum values and a basic description. The tool's description adds practical guidance on how window choice affects results ('hot right now' vs 'steady-state demand'), enhancing semantic understanding.

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

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

The description clearly states the tool's purpose: it returns trending data (top tools, packs, total call volume) from Pipeworx, based on recent windows. This differentiates it from siblings like 'discover_tools' or 'ask_pipeworx' by focusing on aggregated popularity signals.

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

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

The description explicitly lists three use cases: discovering hot data sources, confirming a canonical tool, and aligning use cases with agent trends. While it does not explicitly state when not to use it, the positive guidance is clear and helpful.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds context about monotonicity checks, partition sum checks, placeholder filtering, and fill depth verification. No contradictions.

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

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

Well-structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) but somewhat verbose. Some details like response format could be omitted if output schema existed, 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?

Despite no output schema, description thoroughly explains response format, special cases, fill check, and links to sibling tool. Covers all necessary context for correct invocation and interpretation.

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

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

Schema has 100% description coverage. Description adds significant meaning beyond schema: explains event slug vs topic string, details mode behavior, and technical filters like Jaccard similarity and placeholder threshold.

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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) and references sibling tools like 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?

Explicit guidance on when to use each mode: no args for trending scan, event for specific market, topic for cross-event. Recommends event for specific markets and warns against trading when fill check shows non-positive realizable edge.

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 extensive behavioral detail beyond the readOnlyHint, openWorldHint, idempotentHint, and destructiveHint annotations. It explains the three model families, filtering logic, response structure (by_segment, fed_candidates, diagnostics), and caching behavior. There is no contradiction with annotations.

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

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

The description is well-structured, front-loading the purpose, and logically organized into segments. However, it is lengthy with technical details that could be slightly shortened without losing meaning. It earns its place but could be more concise.

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

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

Given the tool's complexity (9 parameters, no output schema, rich response with nested segments), the description is highly complete. It explains the output fields (by_segment, fed_candidates, diagnostics), caching, and how filters affect results. Without an output schema, the description fully covers return values.

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

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

Although the input schema descriptions cover 100% of parameters, the tool description adds significant context, such as the meaning of 'min_kelly' (half-Kelly fraction with example), 'slippage_pp' (Polymarket's zero fees but bid/ask costs), and 'min_partition_leg_kelly' (why partition arbs have parent kelly=0). This adds value beyond the schema.

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

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

The description states a specific action: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly distinguishes itself from sibling tools like 'polymarket_arbitrage' and 'polymarket_edge_tracker' by focusing on Pipeworx data and providing a comprehensive output structure.

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

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

The description explicitly states it is 'Built for "what should I bet on today"' and mentions that agents 'discover opportunities without paging hundreds of markets.' It provides context on when to use it but does not explicitly compare with alternatives or state when not to use it, which would be a minor improvement.

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

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

Annotations (readOnlyHint, idempotentHint) are consistent. The description adds significant detail: how trend/decay are computed, snapshot gaps from cache-miss, that decay uses daily closes not intraday, and the meaning of negative signs. No contradictions.

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

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

The description is dense but efficiently uses sentences to convey purpose, behavior, and limits. Every sentence adds value, and the structure front-loads the core purpose before detailing response fields and constraints.

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 thoroughly explains the response structure (tracked[], expired[], snapshot_dates[]) and key fields (trend, decay_pp_per_day, lifespan_days). It also covers limitations like 60-day TTL and gap behavior, making the tool fully understandable.

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

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

Both parameters are fully documented in the schema (100% coverage). The description adds default values (days default 14, max 30; window default '1wk'), explicit clamp ranges, and explains 'window' as snapshot family, enhancing utility 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 the tool provides 'edge persistence and decay telemetry' from daily snapshots, answering specific questions about edge age and decay. It clearly differentiates from siblings like polymarket_edges by focusing on historical analysis.

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

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

The description gives a concrete use case ('a fresh wide edge and a 3-week-old wide edge are different trades') and explains when to use it for historical context. It also notes limits (60-day TTL) but lacks explicit 'when not to use' instructions.

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, idempotentHint, etc. Description adds significant behavioral details: walks ladder, returns specific fields, explains verdict levels (clean|degraded|cannot_fill), and highlights forced directional risk. 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 lengthy but well-structured with bullets and bold. Front-loads key info but could be more concise. The complexity justifies the length, though some repetition 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?

No output schema, so description fully explains return values for both modes, including edge cases like thin legs and forced directional risk. Covers dominant loss mode and practical usage context.

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

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

Schema has 100% coverage with descriptions. Description adds meaning beyond schema: clarifies size_usd interpretation for buys vs sells and basket settlement notional, default values, and mode-specific usage of market and event parameters.

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 checks realizable-vs-theoretical edge against live CLOB order-book depth. Distinguishes single-market and basket modes with explicit output fields. Differentiates from sibling tools by specifying when to use it before polymarket_arbitrage or polymarket_edges.

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

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

Explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Includes rationale about thin books and partial basket fills causing unhedged positions.

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

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

The description goes beyond annotations (which already indicate safe read-only behavior) to detail compatibility warnings, temporal alignment, skipped cross types, and the conditions under which spreads are meaningful or not. 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?

Despite being lengthy, every sentence adds critical information. The structure uses clear headings for modes, response fields, and safety fields. The information density is high with no wasted words.

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

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

Given no output schema, the description thoroughly explains the response format (leg-by-leg prices, matched spreads, compatibility warnings, temporal alignment, skip counters). It covers all edge cases for a complex tool.

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

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

With 100% schema coverage, the description still adds value by explaining the two modes, override behavior, and providing examples. The schema covers each parameter, but the description augments with usage context.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It explains two modes (topic shortcuts and explicit tickers), and the specific verb 'spread' distinguishes it from sibling tools like polymarket_arbitrage.

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

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

The description explains when to use the tool (to compare prices across venues for the same question) and provides guidance on the two modes. It warns that real spreads are rarer than shortcuts suggest, but does not explicitly mention alternatives or when not to use.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds scoping detail and pairing with siblings, but no additional behavioral traits beyond annotations.

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

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

Four sentences, front-loaded with main action, no redundancy. 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?

For a simple read-only tool with one param, the description fully explains behavior, scoping, and pairing with siblings. No output schema needed given simplicity.

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

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

Schema has 100% coverage with one optional 'key' parameter. Description adds that omitting key lists all keys, which is not evident from 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 retrieves a saved value or lists all keys, with specific verb-resource pairs. It distinguishes from siblings '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?

Explicitly says 'Use to look up context stored earlier... without re-deriving it from scratch.' Implies when not to use (use 'remember' or 'forget' for save/delete operations). Mentions scoping.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds behavioral context such as mark_read interaction, polling behavior, and alternative access endpoint, providing value beyond annotations.

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

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

Description is well-structured with a clear first sentence stating purpose, followed by details. It is informative without being overly verbose, though slightly longer than minimal.

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 fields (source, citation_uri, payload). Parameters are fully covered. The addition of alternative endpoint adds completeness for real-world use.

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

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

Schema coverage is 100% with descriptions for all 5 parameters. Description adds meaning by giving examples (e.g., 'sec_8k' for type) and explaining mark_read effect, enhancing understanding.

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

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

The description clearly states it pulls fired events from the subscription feed and returns the most recent alerts with key fields. However, it does not explicitly differentiate from sibling tools like list_subscriptions, though the resource (alerts vs subscriptions) is distinct.

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

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

Provides clear context for usage: filter options, polling, alternative endpoint. Does not explicitly state when not to use or alternatives, but implies usage scenarios effectively.

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, destructiveHint=false. Description adds the crucial fan-out behavior to SEC, GDELT/GNews, and USPTO, including fallback logic (GDELT preferred, GNews when rate-limited) and a soft-fail note about PatentsView API sunset. 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?

One dense paragraph, front-loaded with examples. Every sentence adds value. Slight opportunity to break into sections for readability, but no fluff.

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

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

Covers multi-source aggregation, fallback behavior, date format notes, soft-fail context, return structure (changes[], total_changes, citation URIs), and clear sibling differentiation. No gaps given the complexity and lack of 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%, so baseline is 3. But description adds significant meaning: explains relative shorthand for 'since' (e.g., '30d', '1y'), acceptable formats (ISO date vs relative), and example usage. Notes 'value' can be ticker or CIK, and 'type' is only 'company'. 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?

Description opens with concrete user queries and immediately declares it's a change feed for companies over time windows. It names the verb 'change feed' and distinguishes from sibling 'entity_profile' by contrasting static vs windowed data.

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

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

Explicitly states 'Use entity_profile instead when you want the static profile', giving a clear alternative. The examples ('What's new with X') signal the tool is for monitoring recent activity, and the fallback logic for news sources indicates when GDELT vs GNews is used.

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 behavioral details beyond annotations: key-value store scoped by identifier, persistence differences (authenticated vs anonymous), and that anonymous sessions retain memory for 24 hours. 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?

Concise (~80 words) and front-loaded with key verb 'Save'. Every sentence adds value, covering purpose, usage, persistence, and sibling tools.

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 schema coverage and annotations, the description is complete. It explains scoping, persistence, and pairing with recall/forget. No output schema is needed.

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

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

Schema covers 100% of parameters with descriptions. Description adds usage examples but does not significantly augment parameter semantics. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later'. It specifies the action (save) and resource (data), and includes examples like resolved ticker and target address. It also distinguishes from siblings recall and forget.

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

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

Explicit guidance on when to use: 'when you discover something worth carrying forward'. It also mentions alternatives recall and forget, and provides context on persistence (authenticated vs anonymous).

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. The description adds that each call cascades through several lookup endpoints, replacing 2-3 manual lookups, which provides useful behavioral context beyond annotations.

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

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

The description is front-loaded with trigger phrases and efficiently details supported types. Every sentence adds value without repetition.

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

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

Despite no output schema, the description fully explains return values per type (ticker, CIK, RxCUI, citations). Covers purpose, usage, parameters, and return format completely.

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

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

Schema coverage is 100%, but the description adds significant meaning: it explains accepted input formats (ticker, CIK, name for company; brand/generic for drug), mentions auto-disambiguation, and details what is returned for each 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 clearly states the tool resolves a name to a canonical identifier for companies or drugs, with specific trigger phrases. It distinguishes from siblings by noting it provides IDs other tools require.

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 FIRST whenever you have a name but need an ID.' This gives clear context for when to use, though it doesn't explicitly mention when not to use or list alternatives.

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

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

Annotations already indicate readOnly, openWorld, idempotent. Description adds behavioral details: probes each entity with ai_visibility_check, ranks results, returns ranked list with score/confidence/signal density. 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?

4 sentences, front-loaded with purpose, no fluff. Every sentence adds value: purpose, method, use case, return format. Efficiently structured.

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

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

Despite no output schema, description specifies return structure (ranked list with score, confidence, signal density). Given annotations and schema richness, description provides complete context for agent to use 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%, but description adds meaning beyond schema: explains entities order (first is subject), context disambiguation, models list semantics. This helps agent understand parameter roles beyond type/required.

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 'Compare AI visibility across multiple entities side-by-side' with specific verb 'compare' and resource 'AI visibility'. Distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison).

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

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

Description provides explicit use case: 'Useful for competitive AI-marketing audits...' and example question. Does not explicitly state when not to use, but purpose is clear enough to infer appropriate contexts.

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: partial failure handling, latency explanation for new versions (5-30s), and graceful degradation with sources_failed. 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 dense but well-structured in one paragraph. Every sentence adds value. Minor improvement could be breaking into multiple sentences for readability, but it's concise overall.

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

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

No output schema exists, so description must explain return values. It does so thoroughly, listing all fields in the summary block and noting per-advisory details and links. Also covers edge cases like partial failures.

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

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

Schema coverage is 100%, so baseline is 3. Description adds minimal extra detail beyond schema (e.g., version defaults to latest), but does not need to elaborate further.

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 composite check for npm packages, lists specific data sources (deps.dev, bundlephobia) and what it returns, and distinguishes from sibling tools by noting ecosystem limitations.

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

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

Explicitly says when to use (agent asks about safety/popularity/size) and when not to use (other ecosystems fall under different tool), providing clear alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by explaining the nature of the data (federal lobbying disclosures) and the income vs expenses distinction. It does not contradict annotations and provides additional context about the tool's behavior.

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

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

The description is three sentences, each serving a clear purpose: explaining the domain, clarifying key concepts, and giving a usage requirement. It is front-loaded and contains no unnecessary words.

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

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

The description explains the domain and provides usage hints, but since there is no output schema, it could have described what the response contains. For a search tool, this is a gap. However, given the rich schema coverage and annotations, it is moderately 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 the schema already documents all parameters. The description adds value by giving examples (e.g., 'TAX', 'HCR' for issue) and explaining the income/expenses distinction, which aids parameter use. This goes 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 searches US Senate Lobbying Disclosure Act filings, specifying who is lobbying, for which client, on what issues, and for how much. It differentiates between lobbying firms and in-house lobbyists. This distinguishes it from siblings like 'get_filing' and 'list_issue_codes'.

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 'Provide at least one filter,' which is a clear usage guideline. It also explains the difference between income and expenses, informing parameter semantics. While it does not explicitly mention when not to use, the context implies alternatives like 'get_filing' for specific filings.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds significant behavioral details: embedding model (BGE-base-en), similarity metric (cosine), window size (500-char overlapping), character cap (200K chars), truncation behavior, and output format (offsets). 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 slightly verbose but every sentence adds value. It is well-structured: purpose first, then usage, then technical details. Could be trimmed slightly (e.g., redundant phrases) but overall efficient.

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

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

Given the tool's complexity (semantic search with embeddings, offsets), the description covers behavior, output format, truncation, and pairing with a sibling. No output schema, but description adequately explains return values.

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 all parameters are described. The description adds some context (natural-language query examples, top-N passages) but mostly reiterates schema information. Baseline 3 is appropriate.

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

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

The description clearly states the tool performs semantic search within a fetched record, specifying input (text + query) and output (top-N passages with offsets and similarity scores). It distinguishes itself from siblings like ask_pipeworx_grounded by explicitly pairing with it.

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 the record is too big to cram into the prompt') and describes its benefit (saves context, returns relevant passages). It also pairs with ask_pipeworx_grounded, providing an 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?

Annotations indicate readOnlyHint=false, destructiveHint=false, idempotentHint=true, openWorldHint=true. The description adds rich behavioral context: requires OAuth account, type-specific parameters, delivery constraints (phone verification required, SMS limit of 10/day, webhook auto-disable after 10 failures, signing secret returned once). 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: purpose, prerequisites, type list with examples, delivery options. Every sentence adds value. It could be slightly more concise, but the structure and front-loading of key information make it effective.

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

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

Given no output schema, the description covers the return value (subscription id). It addresses prerequisites, type-specific params, and delivery constraints. Missing details on idempotency behavior (though hinted) and subscription duration/cost, but overall complete for a subscription creation 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 nested objects. The description adds substantial meaning beyond schema: it explains each type's parameters (e.g., sec_8k items for officer changes, polymarket_edge topic, fred_series series_id) and delivery channel details (email/sms/webhook with HMAC signing and one-time secret). This greatly aids correct parameter usage.

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

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

The description clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It uses specific verbs and resources, and distinguishes from siblings like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation and returning an id.

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

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

The description provides clear context on when to use (e.g., for specific event types sec_8k, polymarket_edge, etc.) and prerequisites (Pipeworx OAuth account, not anonymous/BYO). It gives examples for each type but does not explicitly state when not to use this tool (e.g., for one-time data queries), though the guidance is sufficient for correct selection.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, so the description adds value by detailing the output (category-bucketed example questions with exact tool+argument shape). No contradictions; builds trust.

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 common phrases ('What can I ask Pipeworx?') and structured with bullet-like details. Slightly verbose but every sentence adds value; could be tightened without losing meaning.

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

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

For a simple onboarding tool with 1 optional parameter and no output schema, the description fully explains its purpose, usage, and output format (category-bucketed examples with tool+argument shape). Sufficient for agent selection.

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

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

Schema coverage is 100%, with parameter 'topic' described. Description adds nuance: 'Call with no arguments for the full spread, or pass topic to focus', plus enumerates valid topics (finance, pharma, etc.), enriching 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 title and description clearly state it's an onboarding tool that returns categorized example questions for Pipeworx. It distinguishes from sibling tools like ask_pipeworx, entity_profile, etc., which are meta-tools mentioned in the description.

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

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

Explicitly advises to use this tool first when unaware of Pipeworx's capabilities, and provides alternative tools (ask_pipeworx, entity_profile, compare_entities) for further learning. Also explains the optional topic parameter for focus.

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 it's not read-only (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds that the row is deactivated rather than deleted, preserving historical events, which clarifies the non-destructive nature. 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 two sentences, front-loaded with the main action, and every sentence provides essential information without redundancy.

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

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

For a tool with a single required parameter and no output schema, the description sufficiently explains the action, ownership restrictions, and data persistence 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% and the schema description for 'id' is clear ('Subscription id (uuid) returned by subscribe'). The description does not add new meaning to the parameter beyond mentioning it in context.

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

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

The description begins with 'Cancel a subscription by id', clearly stating the verb (cancel) and resource (subscription by id). It distinguishes this from siblings 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?

The description notes ownership enforcement ('you can only cancel your own subscriptions') and explains the effect ('deactivated, not deleted'), providing context for appropriate use. However, it does not explicitly state when not to use the tool or compare to alternatives.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description adds significant behavioral detail: it explains the two processing paths (SEC EDGAR vs. grounded pipeline), lists possible verdicts, and mentions citations. 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 packed with information but is slightly verbose. It is front-loaded with trigger phrases and key terms, though some sentences could be tightened 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?

Given the tool's complexity (two paths, multiple verdict types, citation details), the description covers all necessary aspects: input, process, output, and use cases. No output schema, but the description adequately explains return values.

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

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

Schema coverage is 100%, and the description adds meaning beyond schema definitions. For 'claim', it provides example formats; for 'tolerance_pct', it explains default behavior, override usage, and typical ranges (1-2 for hallucination detection).

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: verifying natural-language factual claims against authoritative sources. It provides specific trigger phrases and distinguishes between company-financial and other claims, making it easily identifiable.

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

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

The description explicitly tells when to use the tool ('Use whenever the agent needs to check...') and provides examples. However, it does not compare to sibling tools or state when not to use it, which would enhance clarity.

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