Sec Xbrl

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds value by detailing return structure (per-model score, confidence, signals, raw_response + combined view) and pricing model (free default, BYO key for Anthropic). 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 three sentences, front-loaded with the core function, then details, then use cases. Every sentence is substantive and adds unique value. No redundant or filler content.

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

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

The tool has 4 parameters with full schema coverage, no output schema, and moderate complexity. The description explains the return structure and provides usage context. A usage example would improve completeness, but it is already sufficient for most agents.

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%, but the description adds meaning beyond the schema: it specifies the default model (Workers AI Llama-3.3-70b), explains that _apiKey is for Anthropic and passed through, and clarifies that 'context' helps disambiguate. Examples like 'Pipeworx' provide additional clarity.

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 knowledge about an entity and scores visibility (0-100). It distinguishes from sibling tools, which are mostly Pipeworx-specific or generic research tools, by focusing on AI visibility auditing.

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

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

The description explicitly lists use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains when to provide an API key for Anthropic. It does not explicitly exclude other uses, but the context is clear.

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

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

Annotations already declare safe read-only behavior (readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false). The description adds the fact that it internally routes, fills arguments, and returns pipeworx:// citation URIs, plus reveals it works on every tier and is a fast single call. This goes beyond annotations, though it doesn't discuss error behavior or rate limits.

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

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

The description is longer than average but densely informative; every sentence adds either use cases, examples, or escalation guidance. It is front-loaded with the most important instruction ('PREFER OVER WEB SEARCH') and structured logically from general advice to specifics and then to alternatives. Could be slightly trimmed for brevity but is well-organized.

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

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

At ~220 words, it covers purpose, scope, triggers, examples, escalation paths, and internal routing behavior—impressively complete for a tool with no output schema and a single required parameter. Minor gaps include return-format details (beyond 'structured answer') and what happens if the question is unanswerable, but these are not critical for selection and invocation.

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

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

Schema coverage is 100% for the single required parameter, with aliases documented. The description adds real semantic value by explaining the type of questions to ask (factual, real-world) and providing six vivid examples that clarify the intended input format beyond the schema's bare definition.

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 role: it routes natural-language questions to 5,439 tools across 1,412 verified sources and returns structured answers with citation URIs. It distinguishes itself from siblings by explicitly positioning it as the default entry point and contrasting it with ask_pipeworx_grounded and deep_research.

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

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

Provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH' for factual questions, lists trigger phrases ('what is', 'look up', 'get the latest'), includes six concrete examples, and says when to escalate to ask_pipeworx_grounded or deep_research. Also clarifies that breaking-news questions are covered internally.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Beyond that, the description adds valuable context: candidate routing improvements are enabled live when under test, currently no candidate is active so it matches ask_pipeworx exactly, and it does not fall back to another tool—it is a full working router. This goes beyond annotations to disclose the experimental nature and current behavior.

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

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

The description is four sentences, front-loaded with the beta/identical status, then gives current state, usage instruction, and a clarifying statement. It's slightly verbose with some redundancy (e.g., 'identical' plus 'same 5,439 tools, same arguments, same response shape'), but every sentence contributes useful context.

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

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

Given the annotations cover safety and the output shape is explicitly stated as identical to ask_pipeworx, the description is complete. It explains current behavior, experimental purpose, usage expectations, and the relationship to the stable router, leaving no significant gaps.

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

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

Schema coverage is 100%, with all six parameters being aliases for 'question'. The description mentions 'same arguments' as ask_pipeworx but adds no extra semantic detail beyond the schema. Baseline 3 is appropriate since the schema fully documents the 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?

The description states this is a beta version of ask_pipeworx, an identical universal router with the same 5,439 tools, arguments, and response shape, but with candidate routing improvements. It clearly distinguishes itself from the stable ask_pipeworx sibling by emphasizing the experimental edge and current inactive state.

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

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

It explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router for merge decisions. This provides a clear when-to-use condition and implies the alternative (stable ask_pipeworx), even though it doesn't explicitly state exclusions.

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

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

Beyond the readOnly/idempotent/openWorld annotations, the description discloses key behaviors: it returns an explicit refusal with specific refusal_reason values when data doesn't answer, it only uses tool result content, and it costs one extra LLM call. This adds substantial context beyond the annotations and helps the agent anticipate failure modes.

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

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

The description is dense but every sentence earns its place: it states the purpose, mechanism, return format, use cases, and comparison to ask_pipeworx. It is front-loaded with the key differentiator ('Hallucination-resistant answer mode') and organized with clear sections for success and refusal shapes.

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

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

Even though there is no output schema, the description fully explains the return structure on both success (answer, evidence, confidence, source, fetched_at) and refusal (answer:null, refusal_reason with enumerated values). It also addresses cost, routing, and high-stakes scenarios, making it complete for an agent deciding when and how to use this tool.

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

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

Schema coverage is 100%: all parameters are aliases for 'question' and are fully described in the schema. The description does not add further parameter-level detail, which is acceptable given the high schema coverage. The tool's core input is simply a natural-language question, already well captured.

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

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

The description clearly defines the tool as a 'hallucination-resistant answer mode' that routes like ask_pipeworx but extracts answers strictly from tool results. It distinguishes itself from the sibling tool ask_pipeworx by emphasizing grounded, evidence-backed answers with specific return fields (answer, evidence, confidence, etc.).

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

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

Explicit guidance is provided: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' (financial verdicts, legal claims, medical lookups, public statements). It also tells when NOT to use it: 'prefer ask_pipeworx for casual lookups' and highlights the extra LLM call cost, making the trade-off clear.

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

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

The description extensively discloses behavioral traits beyond annotations, including status codes (low_confidence_match, market_closed_or_inactive), tradeability warnings, resolution-rule risk, news fallback fields, market_match_confidence inspection requirement, parallel fan-out, response size control via include_raw, and safety short-circuits. No contradiction with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint).

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

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

The description is very long and dense, but it is front-loaded with the main purpose. It contains many details that are valuable but could be more concisely organized. Every sentence adds information, but the length may overwhelm an agent. Structure is somewhat haphazard (e.g., classifier list, fan-out examples, response shapes mixed together).

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

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

Despite no output schema, the description thoroughly explains all key response fields (result.market, result.analysis, result.evidence, result.market_match_confidence, parent_event, news fields, status codes, cancellation rules). It covers safety, edge cases (closed markets, wide spreads), and resolution risks, providing a complete picture for an agent to use the tool effectively.

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

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

Schema coverage is 100%, with all three parameters described. The description adds context: depth's 'quick' vs 'thorough' behavior, market input types (slug, URL, question text), and include_raw's rationale (response size control). This goes beyond the schema's descriptions, providing actionable guidance.

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's action: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It lists three input forms (slug, URL, question text) and provides example use cases. It clearly distinguishes from sibling tools like ask_pipeworx (general Q&A) and polymarket_arbitrage (arb opportunities) by focusing on researching a specific bet.

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

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

The description gives explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also includes examples of when it applies. However, it does not explicitly state when not to use it or mention alternative tools, though sibling tool names provide context.

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

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

Annotations already declare readOnlyHint true, idempotentHint true, etc. The description adds detailed behavioral context: data sources (SEC EDGAR/XBRL, FAERS), fiscal year handling, sorting by primary metric, citation URIs, and efficiency claims, 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 somewhat long but each sentence adds meaningful information, front-loaded with trigger phrases and clear directives. Slightly verbose but efficient relative to 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, the description explains return format (paired data + citation URIs) and covers nuanced behaviors (off-calendar fiscal years). Everything the agent needs to use it correctly is present.

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 by explaining that 'values' are tickers/CIKs for company and drug names for type, with concrete examples, enhancing the agent's 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 does side-by-side comparison of 2-5 companies or drugs, listing trigger phrases and specifying what data is pulled for each type, distinguishing it from sequential lookups.

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

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

Explicitly instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', with clear trigger examples and no ambiguity about when to use.

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

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

Discloses account prerequisites, payment tiers, parallel routing behavior, findings packet structure (evidence, confidence, gaps[], contradictions[], hop field, citation_uri), semantic excerpting, and timing (15-60s, ~90s for thorough). This goes far beyond the basic annotations (readOnly, openWorld, idempotent, non-destructive) and provides rich operational context without contradicting annotations.

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

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

The description is long but information-dense and logically structured: prerequisites first, then purpose, usage guidance, output details, and timing. Every sentence earns its place with unique operational specifics, though a few phrases (e.g., 'in ONE call', 'not open-web search') are repeated for emphasis.

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 there is no output schema, the description fully explains return values: findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], and hop fields. It covers prerequisites, exclusions, alternatives, depth behavior, and timing—complete for a complex research tool.

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

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

Schema coverage is 100% with detail on 'question' and 'depth'. The description adds extra usage context: broad/multi-part questions are fine, exact meanings of depth tiers (gap recovery, lead chasing), and expected latency. This adds value beyond the schema, though the schema already carries substantial explanatory weight.

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

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

The description clearly states the tool's core function: grounded multi-source research across Pipeworx's structured data sources, decomposing questions into facets and routing to tools in parallel. It distinguishes itself from open-web search and sibling tools like ask_pipeworx with specific verb+resource+scope (e.g., 'NOT open-web search', 'ONE call').

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

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

Provides explicit when-to-use and when-not-to-use guidance: use ask_pipeworx if not signed in, for single lookups, or for breaking/current news; use deep_research for broad/multi-part structured data questions. Also explains depth tier differences (standard vs thorough) and paid plan requirements.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by stating it returns top-N most relevant tools with full schemas and examples, 'ready to call directly,' which is 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 a single paragraph front-loaded with purpose, then usage, then details. It is efficient without being overly terse. Minor improvement could be better sentence structure.

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 sufficiently explains that output includes tool names, descriptions, and full schemas with examples. It covers key aspects but lacks details on error cases or pagination.

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 parameters. The description adds examples and explains aliases, but these are also listed in the schema. With high schema coverage, the description provides marginal additional 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 'Find tools by describing the data or task,' specifying the verb (find/discover), resource (tools), and scope. It distinguishes itself from sibling tools like search_filings or get_company_facts by being a meta-tool for discovery.

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

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

The description explicitly says 'Call this FIRST when you have many tools available and want to see the option set,' providing clear usage context. It also lists example queries, implying when to use. Could be more explicit about alternatives like directly calling specific tools when already known.

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

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

Adds context beyond annotations: documents USPTO sunset (May 2025, soft-fails), news fallback chain (GDELT→GNews), and parallel fan-out across sources. Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint.

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

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

Single paragraph is dense but could benefit from bullet points for easier scanning. However, it front-loads examples and is efficient overall.

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

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

Covers all key behaviors: data sources, outputs, constraints, and fallbacks. With no output schema, description fully explains return structure.

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

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

Schema coverage is 100% and description explains value should be ticker or zero-padded CIK, names not supported, plus upcoming types. Adds meaning beyond schema descriptions.

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

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

The description clearly states the tool provides a full cross-source profile of a US public company with specific examples like "Tell me about X" and lists outputs (cik, recent_filings, fundamentals, patents, news, LEI). It distinguishes itself from siblings such as resolve_entity and compare_entities.

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 to prefer this over chaining single-pack lookups when a holistic view is needed. Also notes names are not supported and advises using resolve_entity first if only a name is available.

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 and idempotentHint. Description aligns and adds context about sensitive data, but doesn't expand beyond.

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

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

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

Simple tool with one parameter, good annotations, no output schema needed; description is complete for usage.

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

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

Schema coverage is 100% with clear description of 'key'. Description adds no extra meaning beyond schema.

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

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

Specific verb 'Delete' and resource 'memory by key', clearly distinguishes from siblings like 'remember' and 'recall'.

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

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

Explicitly states when to use: 'context is stale, task is done, clear sensitive data', and suggests pairing with related tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds detail about fetching the page, extracting title/description/key links, and emitting standard markdown format. This provides useful behavioral context beyond annotations, such as the read operation and output format.

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

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

Two sentences: first states the core purpose and action, second adds output detail and use cases. No wasted words; front-loaded with essential information.

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

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

Given no output schema, description explains output is a single text blob ready for root placement. Tool is simple with rich annotations (readOnly, idempotent, openWorld). All necessary context is provided for an agent to invoke correctly.

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

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

Schema coverage is 100%, so schema already documents both parameters. Description implicitly mentions URL and max links but doesn't add new meaning beyond the schema's descriptions. Baseline score of 3 is appropriate.

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

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

Description clearly states it generates a production-ready llms.txt file for any URL, extracting title/description/key links. The specific verb 'generate' and resource 'llms.txt' makes it distinct from siblings like scan_competitor_ai_presence which audits AI presence more broadly.

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 cases: indexing a client's site, drafting for own project, auditing competitor. Context is clear but no explicit exclusion or comparison to sibling tools (e.g., scan_competitor_ai_presence could be 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?

Beyond the readOnlyHint and idempotentHint annotations, the description discloses key interpretive cautions: a filing event 'does not prove securities were sold or quantify remaining shelf or ATM capacity', and an empty result is scoped to the requested years. This is valuable behavioral context that prevents misuse.

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 information-dense sentences. The first front-loads the action and scope, the second lists answerable questions and caveats. No fluff, and every clause serves a purpose.

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

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

The tool has no output schema, but the description fully compensates by listing filing types, the strategic questions it answers, and critical limitations regarding shelf capacity and year scoping. This is complete enough for an agent to choose and invoke the tool correctly.

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

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

Schema coverage is 100%, so all parameters are documented. The description adds semantic richness to the 'years' parameter by explaining that an empty result only covers the years requested, and the 'company' parameter is flexible (ticker/name/CIK) in the schema. This goes slightly beyond the baseline.

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

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

The description opens with a specific verb+resource+scope: 'List recent SEC capital-markets filings for a company', then enumerates exact filing types (S-1, S-3, 424, etc.). This level of detail clearly distinguishes it from broader siblings like search_filings or get_company_facts.

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 the questions it answers ('has this company filed a shelf', 'what has it registered recently', 'is there an active ATM programme on file'), providing clear use-case context. It also warns about the 'empty result covers only the years requested' limitation, but does not explicitly name alternative tools for other filing types.

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

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

Annotations already declare readOnly, idempotent, etc. The description adds that data comes from 'across all filings', which is useful context not in annotations.

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

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

Two sentences and an example with no fluff. Every word adds value.

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

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

Given the output schema exists and annotations cover safety, the description is complete enough. No missing context for effective 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 good descriptions for each parameter. The description provides an example with real values, helping the agent understand parameter usage 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 gets a specific financial metric for a company across all filings, with a concrete example. It distinguishes from siblings like get_company_facts and get_company_financials by focusing on a single concept tag.

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

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

It explicitly says to use this to track metrics like revenue or net income over time. While it doesn't mention when not to use it, the example and context provide 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 already declare readOnlyHint, idempotentHint, and destructiveHint; the description adds that it returns up to 20 tag names per taxonomy, a useful behavioral detail. No contradictions.

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

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

Two sentences, minimal waste, front-loaded with purpose and return details.

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

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

With a single parameter, good annotations, and an output schema, the description is sufficiently complete: it explains the output (entity name, taxonomy names, count, sample tags) and differentiates from 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% for the single parameter 'cik', which has a clear description. The description adds no additional meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the verb 'List' and the resource 'XBRL taxonomies and concept tags filed by a company', and distinguishes from siblings by directing to get_company_concept or get_company_financials for actual numeric values.

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

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

It explicitly requires CIK, and provides clear alternatives: 'Use get_company_concept or get_company_financials to retrieve actual numeric values', telling the agent when not to use this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructiveHint. The description adds context about return format (clean numerical values, XBRL tag, period-end date) and auto-resolution of ticker to CIK, providing additional behavioral insight without contradicting annotations.

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

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

The description is short (three sentences) and front-loaded with the core purpose. Every sentence adds value: what it returns, how to specify the year, and sibling preference. 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?

Given the tool's simplicity (2 params, output schema exists), the description covers inputs, output nature, and sibling alternatives. It implicitly restricts to US public companies but could explicitly state that limitation. Output schema likely explains return values, so no missing critical info.

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

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

Schema coverage is 100%, so baseline 3. The description adds meaning by explaining the 'company' parameter accepts CIK or ticker with auto-resolution, and the 'fiscal_year_end' parameter accepts 4-digit year or specific date, with default behavior detailed. This goes beyond the schema's basic description.

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

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

The description clearly states it provides a high-level summary of a public US company's annual (10-K) financials with specific metrics. It explicitly distinguishes itself from siblings get_company_facts and get_company_concept by stating preference for single-company snapshot questions.

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

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

The description gives explicit guidance: 'Prefer this over get_company_facts/get_company_concept for any single-company financial snapshot question.' It also explains how to specify the fiscal year and default behavior, effectively telling the agent when to use this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context about share-count dates not aligning with quarter end and tag variability across filers, which are important data quality caveats beyond the annotations.

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

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

The description is two sentences, with the main action front-loaded. It efficiently communicates the tool's scope and limitations without unnecessary detail, earning a perfect score.

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

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

Given the tool's low complexity (one parameter, no output schema), the description is fairly complete. It explains what is summarized and notes key caveats, though it could explicitly mention the return format or structure.

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 'company' is fully described in the schema with accepted formats (ticker, name, or CIK) at 100% coverage. The description does not add additional parameter semantics, but the schema already handles it, so baseline 3 is appropriate.

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

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

The description clearly states the tool summarizes SEC-tagged common shares outstanding, approximate year-over-year share change, and equity issuance proceeds. It also explicitly differentiates itself by noting it is not a fully diluted capitalization table, distinguishing it from related 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 implies usage for dilution-related queries but does not explicitly state when to use this tool versus alternatives like get_company_financials or get_liquidity_runway. No exclusions or comparative guidance is provided.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds value beyond annotations by explaining the mechanical/screening nature of the estimate and the specific inputs used, while listing exclusions that affect interpretation. This is valuable context for the agent's expectations.

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, both informative. The first states the main action and methodology, the second clarifies important limitations. No repetition, no filler. Highly 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 read-only tool with one parameter and no output schema, the description fully covers its scope, calculation basis, and limitations. The exclusions are especially valuable for setting expectations. No significant gaps remain.

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

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

The input schema covers 100% of parameters: a single required 'company' field with description 'Ticker, company name, or CIK.' The description adds no additional parameter-level detail, but that is unnecessary given the schema's completeness. Baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Estimate a company’s mechanical liquidity runway' and clearly defines the methodology (SEC-tagged cash/current investments and trailing-twelve-month operating cash flow). This distinguishes it from sibling tools like get_rnd_burn_profile or get_company_financials by focusing on liquidity runway as a distinct analytical output.

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 and boundaries: it is a 'screening calculation—not management guidance' and explicitly lists exclusions (future financing, commitments, restricted access, working-capital timing, forecast changes). This tells the agent when not to treat the result as authoritative, though it does not name alternative tools for more comprehensive analysis.

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?

With annotations already indicating read-only and idempotent behavior, the description adds value by explaining the return behavior (periods used, null when no defensible bridge) and the exact calculation logic. This goes beyond the annotations.

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

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

The description is a single, well-structured sentence. It front-loads the purpose, includes the calculation method, and notes the null condition, 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?

The tool has only one parameter and no output schema. The description covers the calculation methodology, the return value (periods used), and the null condition, making it complete for an agent to understand expected 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% for the single 'company' parameter (Ticker, company name, or CIK). The description does not add additional parameter semantics beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description specifies a clear verb ('Calculate') and resource ('trailing-twelve-month SEC-tagged R&D expense and operating cash flow'), and outlines the methodology. It distinguishes itself from sibling tools like get_company_financials by focusing on a specific derived metric.

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

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

The description implies the tool is for computing TTM R&D burn from SEC filings, which is clear context. It does not explicitly list alternatives or exclusions, but the context is evident given sibling tools like get_liquidity_runway. A 4 is appropriate for clear context without exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows it's a safe, non-mutating operation. The description adds that it returns specific fields and defaults to active subscriptions only, which aligns with and slightly supplements the annotations. No contradictions.

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

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

The description is two sentences: the first concisely states purpose and return fields, the second provides usage guidance. Every sentence earns its place, and the description is appropriately sized 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?

Given the tool's simplicity (one optional boolean parameter, no output schema, clear annotations), the description covers all necessary context: purpose, return fields, default behavior, and when to use it. It is complete and sufficient for an AI agent to select and invoke correctly.

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

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

The input schema has 100% description coverage for the single optional parameter (include_inactive). The description states 'active subscriptions' implying the default, but does not provide additional semantic nuance beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states that the tool lists the caller's active subscriptions and enumerates the exact fields returned (id, type, params, created_at, last_fired_at, fire_count). It distinguishes itself from sibling tools like subscribe and unsubscribe by focusing on listing rather than creating or canceling.

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 guides when to use the tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This provides clear context for invocation and differentiates it from 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 provide minimal safety hints (all false). The description adds meaningful behavioral context: rate-limited to 5 per identifier per day, free and not counted against quota, daily review by the team, and guidance to describe issues in terms of Pipeworx tools rather than pasting user prompts. These details go well beyond the structured annotations and set accurate expectations.

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 structured, front-loaded paragraph. The primary purpose is stated first, followed by concrete use cases, exclusions, and practical tips. Every sentence adds essential context (scope limitation, rate limit, quota behavior, guidance on content). Nothing is redundant or superfluous.

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 3 parameters, a nested context object, and no output schema, the description is remarkably complete. It covers usage scenarios, exclusions, submission quality, rate limits, and the human impact of feedback. There is no missing information that would prevent an agent from invoking this 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% — every parameter has a description, so the schema already carries most semantic weight. The description adds extra guidance on message content ('don't paste the end-user's prompt') and ties the context object to Pipeworx packs/tools, which adds value beyond the schema. A slight deduction because some of the schema descriptions already convey similar information.

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

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

The description opens with a specific verb-plus-resource statement: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly identifies the tool's function and distinguishes it from all sibling tools, none of which are feedback-related. The title 'Send Pipeworx Feedback' is reinforced rather than merely restated.

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: for bugs, feature/data gaps, or praise, with concrete examples. It also provides a clear exclusion: feedback about non-Pipeworx MCP servers should be filed elsewhere. This is excellent when/when-not guidance with an explicit alternative behavior.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral details: data source (CF analytics-engine), no PII, and caching window (5min-1h). No contradictions with annotations.

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

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

The description is concise: three sentences plus bullet points for use cases. Every sentence adds value without redundancy. Well-structured and easily 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 the simple input schema (1 optional param, no output schema), the description covers all necessary aspects: return values, use cases, data source, caching, and privacy. No gaps for an agent to invoke correctly.

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

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

Schema coverage is 100% with one enum parameter 'window' described as '24h (default) | 7d | 30d'. The description adds semantic context: shorter windows surface hot trends, longer windows show steady-state demand. This enhances 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 it returns top tools, packs, and call volume over a window. The verb 'returns' and resource specification make the purpose unambiguous. It distinguishes from sibling tools by focusing on trending/aggregate data rather than individual queries or searches.

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 three explicit use cases: discovering hot data sources, confirming canonical tools, and checking use-case alignment. It provides clear context for when to use this tool, though it does not explicitly mention when not to use it or suggest alternatives.

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

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

The description provides extensive behavioral details beyond annotations: monotonicity checks, partition_sum logic, semantic anchor, placeholder filtering, fill check with live depth. It explains response structure and edge cases. Annotations (readOnlyHint, idempotentHint) are consistent and the description adds rich 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 dense with essential information, front-loaded with main purpose and modes. Every sentence adds value, though formatting (e.g., bullet points) could improve scannability. 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?

Despite lacking an output schema, the description thoroughly documents the response structure (opportunities[], partition_check, fill_check) and handles edge cases (low similarity, placeholder filtering, thin legs). 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 coverage is 100% with descriptions for both parameters. The description adds significant meaning: e.g., event accepts full Polymarket URLs, topic triggers a search across the platform. It enriches the schema without redundancy.

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

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

The description clearly identifies the tool's purpose: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (trending_scan, event, topic) and contrasts with siblings like polymarket_edges and 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?

The description explicitly states when to use each mode: no args for trending_scan, event for a specific market, topic for cross-event scanning. It provides examples and recommends event mode. However, it does not explicitly state when not to use the tool or mention alternatives.

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

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

The description goes far beyond the annotations, detailing model families, edge calculation, caching (1h KV level), diagnostics, and filter skip behavior. It provides rich behavioral context such as the 24h move warning and Kelly fraction caps. No contradictions with annotations.

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

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

The description is lengthy but well-structured with section headings and bullet-like lists. Every sentence adds value, covering output structure and behavioral nuances. While comprehensive, it could be slightly more concise, but the complexity warrants the length.

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

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

Despite no output schema, the description thoroughly explains the response structure (by_segment, fed_candidates, diagnostics). It covers return values and caching, making the tool self-contained. High complexity is matched with complete explanation.

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 adds significant meaning beyond the schema. It explains defaults, edge cases (e.g., min_partition_leg_kelly) and behavioral impacts (e.g., slippage_pp explains execution context). Each parameter is well contextualized.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. It uses specific verbs (scan, return) and identifies the resource (Polymarket markets). It distinguishes itself from sibling tools by specifying the unique data source and purpose.

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 the tool is built for "what should I bet on today" and that agents discover opportunities without paging hundreds of markets. It provides guidance on knobs like min_liquidity and max_spread_pp. However, it does not explicitly mention when not to use or compare to siblings.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds valuable behavioral context: history depth bounded by 60-day TTL, decay numbers from daily closes (not intraday), and snapshot gaps when no scan occurred. 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 well-structured with a clear purpose, parameter details, response format, and limitations. Each sentence contributes meaning. It is somewhat lengthy but efficiently packed with information. Minor redundancy with schema could be trimmed.

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

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

No output schema exists, so the description fully explains return values (tracked, expired, snapshot_dates) with field details. It also covers limitations and data sources. Complete for the tool's complexity.

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

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

Schema coverage is 100% with both parameters having descriptions. The description essentially repeats the same information (defaults and ranges) without adding new meaning beyond the schema. 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: tracking edge persistence and decay from daily snapshots, answering a specific question about edge lifespan. It uses specific verbs (track, answers) and resource (edge persistence telemetry). It is easily distinguishable from sibling tools like polymarket_edges and 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 implies usage context by stating the question it answers, but does not explicitly provide when-to-use vs alternatives or exclusion criteria. No mention of when not to use or sibling differentiation beyond the name. Minimal guidance.

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

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

Annotations indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which are consistent with the description. The description adds behavioral details beyond annotations, such as ladder walking, return fields (top_of_book, VWAP, slippage), and warnings about forced directional risk, providing full transparency.

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

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

The description is detailed and well-structured with separate paragraphs for modes, but it is lengthy. While every sentence adds value, it could be slightly more concise. Front-loading with the core purpose is good, but the overall length reduces 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?

Since no output schema exists, the description fully explains return values for both modes, including edge cases like thin legs and forced directional risk. It covers all aspects needed for an agent to use the tool correctly, from input parameters to expected outputs and failure modes.

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 the difference between market and event parameters, default values for side and size_usd, and constraints like 'clamp 10–1,000,000'. This goes well beyond the schema's simple descriptions.

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

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

The description clearly defines the tool as a 'realizable-vs-theoretical edge check against live CLOB order-book depth', with distinct modes for single-market and basket operations. It uses specific verbs ('checks') and resources ('order-book depth'), and differentiates itself from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

The description explicitly states when to use the tool: 'before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also provides reasoning about risks like uncapturable overround and directional position from partial fills, making the guidance actionable.

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

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

The description extensively discloses behavioral traits beyond annotations: compatibility_warning scenarios, temporal alignment, skipped cross-type/subtype counters, and the real meaning of the spread. Annotations already indicate safe read-only, idempotent behavior; the description adds crucial caveats about when spreads are meaningful.

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

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

The description is thorough and well-structured with 'TWO MODES' and 'SAFETY FIELDS' headers, front-loading the core purpose. It is verbose but every sentence serves a purpose for a complex tool. Minor reduction could improve conciseness without losing clarity.

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

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

Given the lack of output schema and three parameters, the description is exceptionally complete: it explains the response format (leg-by-leg prices, spreads, safety fields), temporal alignment, and edge cases (compatibility_warning conditions). An agent can fully understand invocation and result 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?

With 100% schema coverage, the description enriches parameter understanding: it lists each topic shortcut, clarifies that explicit tickers override topic defaults, and provides concrete examples (e.g., 'kalshi_event_ticker: "KXFED-26OCT"'). The safety fields section helps interpret results tied to 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?

The description clearly states the tool's purpose: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It specifies two modes (topic shortcuts and explicit tickers) and differentiates itself from sibling tools like polymarket_arbitrage by focusing on cross-venue spread rather than single-venue 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 each mode: topic for 10 pre-mapped macros, explicit for custom pairings. It also warns that most pre-mapped topics return compatibility_warning, implying limited tradability. However, it does not explicitly state when not to use the tool, though the warning provides implicit guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds scoping and pairing context but does not disclose additional behavioral traits beyond what annotations provide.

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

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

Three sentences, front-loaded with the core action, no redundant information. Every sentence earns its place.

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

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

Given one optional parameter, existing annotations, and no output schema, the description fully covers functionality, modes, scoping, and pairing with other tools. No gaps.

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

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

Schema coverage is 100% with a one-line description per parameter. The description reinforces the dual behavior (omit for listing) but adds minimal extra meaning beyond the schema.

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

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

The description clearly states the verb 'Retrieve' and identifies the resource as values saved via 'remember', with two distinct modes (with key or omit for listing). It explicitly differentiates from sibling tools by naming '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?

Provides concrete examples of when to use (look up target ticker, address, research notes) and explains scoping by user identifier. Does not explicitly state when not to use, but the guidance is clear enough.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds key behavioral details: the mark_read parameter affects subsequent calls, and the feed is persistent. This goes beyond what annotations provide, but the core behavioral safety is well-covered by annotations.

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

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

The description is concise and well-structured. It starts with the core purpose, then details return fields, filtering options, and usage notes. Every sentence is informative and earns its place, with 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?

Despite lacking an output schema, the description mentions return fields and the mark_read behavior. All parameters are covered, annotations are complete, and the tool's simplicity means no additional context is needed. The description is fully adequate.

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?

All 5 parameters are described in the schema (100% coverage). The description adds useful context: e.g., 'sec_8k' example for type, ISO timestamp format for since, and the effect of mark_read. This enhances understanding beyond the schema definitions.

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

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

The description clearly states the tool pulls fired events from the subscription feed with specific fields (source, citation_uri, raw event). It distinguishes itself from sibling tools by focusing on alerts retrieval and even mentions an alternative access method (GET endpoint), making the purpose unambiguous.

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

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

The description provides clear usage guidance: filter by type and since, set mark_read for read tracking, and notes that polling works fine. It does not explicitly exclude scenarios but implies repeated polling is acceptable. The alternative GET endpoint is mentioned, adding context.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description details the tool's internal fan-out to multiple sources, the fallback from GDELT to GNews, the USPTO PatentsView API sunset causing soft-failures, and that it returns 'structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs'. This adds significant behavioral context not available from annotations alone.

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 dense single paragraph that packs essential information without redundancy. It front-loads with natural language query examples but could benefit from clearer structure (e.g., bullet points for sources). Every sentence contributes value, so no waste.

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

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

Given the tool has 3 parameters, no output schema, and no nested objects, the description provides thorough coverage: it explains data sources, fallback mechanisms, return format (structured changes, counts, citation URIs), parameter usage suggestions, and a pointer to the sibling tool for static profiles. Users have sufficient context to decide when and how to use the tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds practical usage tips for the `since` parameter (recommends '30d' or '1m') and clarifies that `value` accepts ticker or CIK, but the schema already provides these explanations. The added value is moderate, raising the score to 4.

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

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

The description clearly states the tool serves as a 'change feed for a company in the last N days/weeks/months in ONE parallel call' and explicitly distinguishes from sibling 'entity_profile' by directing users to that static profile tool. It provides concrete query examples like 'What's new with X' and names the three data sources (SEC EDGAR, GDELT/GNews, USPTO).

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 specifies when to use the tool (e.g., 'latest on Y', 'what happened to Z') and when to use the alternative sibling tool ('Use entity_profile instead when you want the static profile...'). It also provides guidance on the `since` parameter ('Use "30d" or "1m" for typical monitoring') and explains the GDELT→GNews fallback behavior under rate limits or 5xx errors.

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 idempotentHint=true and destructiveHint=false. The description adds context on key-value scoping, session vs. authenticated storage (24-hour vs. persistent), which goes beyond annotations. No contradictions.

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

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

The description is four sentences, front-loaded with the main purpose, and every sentence adds value without redundancy.

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

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

Given the tool's simplicity (2 params, no output schema), the description covers purpose, usage, persistence, and pairing with other tools 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% and description provides examples for key (e.g., 'subject_property') and value ('any text'), adding semantics beyond the schema.

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

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

The description specifies the verb 'save data' and the resource 'data the agent will need to reuse later', with clear examples and differentiation 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?

The description explicitly states when to use (discover something worth carrying forward) and pairs with recall/forget. It provides context on scoping and persistence, but does not explicitly state when not to use, though this is implied.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds that each call cascades through multiple endpoints internally, replacing 2-3 manual lookups. This additional context is helpful 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 front-loaded with examples and clearly structured. While it is a bit lengthy, every sentence contributes useful information. It is easy to scan and understand.

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

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

Despite no output schema, the description thoroughly explains return values for both entity types, including citations. It also covers internal cascading behavior, making the tool's functionality fully transparent. The description is complete for a lookup tool of this complexity.

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

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

Schema coverage is 100%, but the description adds significant meaning: it explains the return values (ticker + CIK + company_name + citation for company; RxCUI + ingredient + brand + citation for drug) and acceptable input formats (ticker, CIK, or name for company; brand or generic for drug). This provides 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 starts with clear example queries ('What's the ticker for…', 'find the CIK for…') and states the core purpose: resolving a name to a canonical identifier. It distinguishes from sibling tools by emphasizing it is the first step when needing an ID, and specifies supported types (company, drug) with details on output.

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

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

The description explicitly advises 'Use FIRST whenever you have a name but need an ID.' It gives concrete usage examples (ticker, CIK, RxCUI) and describes input formats for each type. While it does not list when not to use, the guidance is clear and sufficient.

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

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

Annotations already indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral details: it probes each entity with ai_visibility_check, ranks results, and returns score, confidence, and signal density. This adds value beyond 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?

Two sentences, front-loaded with key action and resource, no extraneous content. Every sentence earns its place, making it highly efficient for an AI agent to parse.

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

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

Despite having no output schema, the description fully explains the return format (ranked list with score, confidence, signal density). It also clarifies the probe mechanism and parameter roles, making the tool's behavior and outputs completely understandable for an AI agent.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds additional meaning by explaining that the first entity is treated as the 'subject' for narrative and that context disambiguates common names. This enhances understanding beyond parameter descriptions.

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

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

The description clearly states the verb 'Compare' and the resource 'AI visibility across multiple entities'. It explicitly distinguishes itself from sibling tools like ai_visibility_check by mentioning aggregation and ranking, making its unique value clear.

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

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

The description provides a concrete use case ('competitive AI-marketing audits') and an illustrative question. It implies when to use this tool (multi-entity comparison) but does not explicitly state when not to use it or list alternatives beyond the sibling context.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description discloses key behaviors: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and the sources_failed parameter indicates timeouts. 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 single-paragraph but dense with information. It front-loads the composite nature. While it could use bullet points for brevity, it remains clear and concise without redundancy.

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

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

Given the two parameters, no output schema, and rich annotations, the description fully accounts for return structure (summary, advisories, links, alternatives), partial failure handling, and timing caveats. No gaps in understanding the tool's behavior.

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

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

Schema coverage is 100% with both parameters documented (package name format, version default behavior). The description adds no additional semantic meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description specifically states the tool performs a composite check for adding an npm package, combining deps.dev and bundlephobia data. It clearly distinguishes the scope (npm only) and provides a verb+resource description that differentiates from unrelated siblings.

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

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

Explicitly states usage: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also clarifies when not to use by directing other ecosystems to deps.dev:version directly, providing clear contextual guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds that filings are 'recent' and returns specific fields, but does not define 'recent' (e.g., timeframe) or disclose any rate limits. For a safe, read-only tool with annotations, this is adequate but not above baseline.

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

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

Two sentences, front-loaded with the core purpose and optional filter. No extraneous information. Every word serves a clear function.

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

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

Given the tool's simplicity (2 params, 1 required) and the presence of an output schema, the description sufficiently covers input scope and returned data. It explicitly mentions the return fields (dates, types, accession numbers). The annotations cover safety and idempotency, making the description complete for an agent.

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

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

Schema coverage is 100% (both parameters have descriptions). The description only restates the optional type filter without adding new meaning. It correctly mentions CIK as identifier but does not add constraints or examples beyond the schema's examples.

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

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

The description clearly states the verb 'search', the resource 'SEC filings', the scope 'recent' and 'by CIK', and optional filtering by type. It distinguishes itself from siblings like 'get_company_facts' which retrieves standardized financial data rather than raw filings.

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

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

The description implies usage for searching SEC filings, but lacks explicit guidance on when to prefer this tool over siblings like 'get_company_facts' or 'deep_research'. No exclusions or alternative recommendations are provided.

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 behavioral traits beyond annotations: uses BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation and flagging. Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. Description adds significant behavioral context 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?

Description is compact (4-5 sentences), front-loaded with the core action and examples. Every sentence adds information: purpose, use case, output details, technical specifics. No fluff or repetition.

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

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

Tool has 3 parameters, no output schema, but description explains return format (passages with character offsets and similarity scores). It covers pairing with sibling, constraints, embedding model, and truncation behavior. Complete for a search-within-text tool given the annotations and schema richness.

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, so baseline is 3. Description adds value by clarifying text's max length (~200K chars), providing example queries, and explaining limit's range (1-20, default 5). This goes beyond the schema definitions.

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

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

The description clearly states it performs semantic search inside a fetched record, using verbs like 'search' and 'get back'. It gives concrete examples (SEC 10-K, article, long tool result) and explains output (passages with offsets and similarity scores). It distinguishes itself from sibling tools like ask_pipeworx_grounded by specifying its niche of searching within already-fetched text.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt — search_within saves context'. It also pairs with ask_pipeworx_grounded, indicating an alternative workflow. While it does not explicitly list when not to use, the context is clear. Slight room for improvement: could add when to prefer the sibling tools.

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

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

The description covers behavioral traits beyond annotations: account requirements, type-specific parameters, delivery channels, webhook signing, SMS cap, and auto-disable after 10 failing runs. However, the idempotentHint annotation (true) is not addressed in the description, which could be misleading if the agent assumes safe retries.

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 front-loaded with the core purpose and return value. Every sentence adds value, though the list of types could be more systematically presented. Slight redundancy in the delivery section on SMS cap and webhook details.

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

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

Given the complexity (nested objects, multiple types, delivery channels) and no output schema, the description is quite complete. It covers account requirements, type-specific filters, delivery options, and failure conditions. Missing two types from the description reduces completeness slightly.

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 coverage is 100%, and the description adds significant value with examples and details for most parameters. However, the description lists only three of the five enum values for 'type' (missing 'patent_grant' and 'clinical_trial'), causing incomplete parameter semantics.

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

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

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

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

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

The description specifies prerequisites ('Requires a Pipeworx OAuth account; anonymous + BYO cannot persist subscriptions') and lists all supported types with examples. It does not explicitly state when not to use this tool or mention alternative tools, but the context is clear enough.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds behavioral context about return format (category-bucketed examples), argument effects (full spread vs. focused topic), and that results are drawn from a live catalog. No contradiction with annotations.

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

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

The description is front-loaded with common user queries, then explains the output and usage. While somewhat lengthy, every sentence adds value and the structure is clear. Could be slightly trimmed but remains effective.

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

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

Given the tool's simple interface (one optional param, no output schema), the description adequately covers its purpose, input, and output. It explains when to use and what to expect, making it complete for an onboarding tool.

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

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

Schema coverage is 100% for the single optional parameter 'topic'. The description adds meaning by explaining the default behavior (cross-category spread) and listing example focus areas, enhancing the schema's minimal description.

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

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

The description clearly states the tool returns category-bucketed example questions with associated tool+argument shapes. It explicitly positions itself as the onboarding entry point, distinguishing it from siblings like ask_pipeworx or discover_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 advises using this tool first when unfamiliar with Pipeworx and explains when to omit or supply the topic argument. It provides clear context but does not explicitly list alternative tools for similar tasks, though the sibling names imply other discovery tools.

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

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

Beyond annotations (idempotentHint=true, destructiveHint=false), the description adds that the row is deactivated (not deleted) and historical events remain accessible via recent_alerts, providing valuable 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?

Two sentences, concise and front-loaded. Every sentence adds essential information 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 one parameter and no output schema, the description fully covers purpose, constraints (ownership), and side effects (deactivation, historical data retention). It is complete.

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

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

Parameter 'id' is documented in the schema with description 'Subscription id (uuid) returned by subscribe.' The description repeats 'by id' without adding further semantics. Since schema coverage is 100%, 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 verb (cancel), the resource (subscription by id), and the action's effect (deactivation). It distinguishes itself 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 implicitly indicates when to use (to cancel a subscription) but does not explicitly mention when not to use it or provide alternatives among sibling tools. It does note ownership enforcement, which guides usage.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context: it performs lookup and comparison, returns verdict with evidence, and replaces multiple sequential calls. It also explains that claims fall through to different pipelines automatically. With strong annotations, this additional context is valuable but not essential.

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 front-loaded with example queries and a clear purpose. Every sentence adds unique value (pipelines, return fields, efficiency claim). Slightly verbose in listing example queries, but overall well-organized and efficient.

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

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

For a tool with no output schema, the description thoroughly explains what is returned (verdict, actual value with citation, reasoning). It also covers why this tool is advantageous (replaces 4-6 sequential calls). The tool has 2 params (1 required), low complexity, and the description fully covers usage and behavior.

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

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

Schema coverage is 100%, with parameter descriptions already present. The description adds meaning by explaining tolerance_pct's default behavior (implied by wording, capped at 5) and use case for hallucination detection, and provides concrete examples for the claim parameter. This adds significant value beyond the schema.

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

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

Description clearly states the tool verifies factual claims, provides example queries, and distinguishes between company-financial and other claims. It uses specific verbs like 'check', 'verify', 'confirm or refute' and uniquely positions itself among sibling tools as the dedicated claim-verification tool.

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

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

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct.' It describes two distinct pipelines (structured SEC EDGAR for financial claims, grounded pipeline for other facts) and explains when to set tolerance_pct for hallucination detection. This provides clear when-to-use guidance.

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