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 readOnlyHint, openWorldHint, idempotentHint, and no destructive actions. The description adds behavioral context beyond that: it returns a structured answer with stable pipeworx:// citation URIs, works on all tiers, and is a single fast call. It also discloses that it routes to numerous sub-tools. This enriches the agent's model of expected behavior 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 every sentence carries weight: it front-loads the critical 'PREFER OVER WEB SEARCH' directive, then covers scope, examples, and sibling differentiation. Structure is logical (purpose → scope → examples → escalation path). Slightly verbose but not padded.

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

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

Given the tool's complexity as a router over thousands of sources and no output schema, the description is exceptionally complete. It specifies the types of questions supported, the return format (structured with citations), performance expectations, and how it relates to alternatives. No critical operational details are missing for an agent to correctly invoke it.

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

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

Schema coverage is 100% with the 'question' parameter well documented, including all five aliases. The description adds value by providing concrete question examples and clarifying the accepted input patterns. Though the schema is already thorough, the description reinforces real-world usage, justifying a score above the baseline 3.

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

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

The description states a precise purpose: route a natural-language question to the correct tool among 5,706 and return a structured answer with citation URIs. It explicitly contrasts with siblings like ask_pipeworx_grounded and deep_research, and defines the scope (SEC filings, FDA data, FRED, etc.), making it unambiguous what this tool does and how it differs.

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

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

The description gives explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', 'Use whenever the user asks...' with example phrasings, and clearly demarcates when to step up to ask_pipeworx_grounded or deep_research. It even notes breaking news scenarios. This is exemplary guidance with no ambiguity.

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

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

Annotations already mark it read-only, idempotent, and non-destructive, and the description adds valuable behavioral context: beta status, live candidate routing may change behavior, no candidate is currently active, and it is a full working router with no fallback. This goes well beyond what annotations alone communicate.

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 front-loaded with the beta/identical-router message and each sentence adds meaningful context about status, usage, or fallback behavior. There is minor redundancy between 'identical universal router' and 'same tools, same arguments, same response shape,' but the overall length is still reasonable and focused.

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

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

For a complex universal router with no output schema, the description covers the key practical points: identical behavior to ask_pipeworx, current no-candidate state, no fallback, and usage intent. It does not detail the response shape or give examples, but referencing the stable sibling's identical response shape compensates given the rich schema and annotations.

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

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

Schema description coverage is 100%, with six documented aliases for the single required question parameter, so the schema fully explains parameter meaning. The description adds no parameter-specific details beyond saying the arguments match ask_pipeworx, which is consistent with the baseline of 3.

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

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

The description states the tool is a beta universal router with the same 5,706 tools, arguments, and response shape as ask_pipeworx. It clearly differentiates it from the stable ask_pipeworx by emphasizing its experimental routing edge, so an agent understands exactly what it does and how it relates to 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?

It explicitly tells the agent to use this tool exactly like ask_pipeworx when the newest routing is desired, and explains that results are compared against the stable router to inform merges. This gives concrete when-to-use guidance and implies that the stable router is the alternative for non-experimental use.

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

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

Annotations already provide readOnlyHint and idempotentHint, but the description adds substantial behavioral context: it uses only the tool result, returns an explicit refusal with enumerated reasons, and costs one extra LLM call. There is no contradiction with the annotations.

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

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

The description is long but information-dense: purpose is front-loaded, followed by the exact success object, refusal reasons, use cases, and cost trade-off. Every sentence serves a distinct purpose and no content is redundant.

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

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

Since there is no output schema, the description fully compensates by specifying the exact success fields and the full refusal_reason enum. Combined with the annotations, an agent has everything needed to invoke this tool correctly and interpret its results.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds no parameter-level detail beyond 'fills arguments'; the schema already documents that all six parameters are aliases for the natural-language question.

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

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

The description states a specific verb ('extracts the answer') and resource ('grounded answer mode'), and explicitly contrasts it with ask_pipeworx by emphasizing evidence and refusals. An agent can distinguish this from ask_pipeworx and ask_pipeworx_beta without opening the schema.

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 gives explicit when-to-use guidance: whenever the answer will be quoted, cited, or acted on, with concrete high-stakes domains like financial verdicts, legal claims, medical lookups, and public statements. It also names the alternative and gives the condition to prefer it: 'prefer ask_pipeworx for casual lookups.'

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

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

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?

Beyond annotations, the description discloses the account/paid-tier requirement, parallel facet routing, the findings-packet shape (verbatim evidence, confidence, source, fetched_at, citation_uri), gaps[] and contradictions[] behavior, latency expectations, and semantic excerpting rather than head-truncation. Nothing in these statements conflicts with the annotations.

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

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

Although long, the description is front-loaded with the most decision-critical constraints (account, sign-in alternative) and each subsequent sentence adds a distinct behavioral or usage fact. No filler or repetition is present.

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

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

With no output schema and high operational complexity, the description carries the full burden of explaining what the agent will receive and how long it will take. It covers return packet contents, citation resolvability, gap/contradiction semantics, depth differences, and timing, so the agent has enough to select and invoke the tool correctly.

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

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

Schema coverage is already 100%, so the baseline is 3; the description adds value by clarifying that question may be broad/multi-part because decomposition is the point, and by tying the depth enum to account tier and recursion behavior. It does not redefine parameter syntax but gives them decision-relevant context.

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

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

The description states a specific verb and resource: grounded multi-source research across Pipeworx's 1493 structured data sources in one call, and explicitly distinguishes itself from open-web search. It also names representative use cases, making its scope unmistakable.

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

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

There are explicit when-to-use and when-not-to-use rules: use for broad/multi-part structured-data questions; prefer ask_pipeworx for single lookups, breaking/current-news topics, and when not signed in. Depth-tier semantics are explained, including what standard vs thorough add.

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?

The description discloses rate limiting ('Rate-limited to 5 per identifier per day'), the claim token mechanism ('Filing without an account returns a claim_token; pass it back later...'), and the fact it's free and doesn't count against quota. These behaviors go beyond the annotations (readOnlyHint=false, etc.) and provide valuable operational 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 longer than the top-tier examples but every sentence carries useful information. It is front-loaded with the core purpose and structured logically: purpose, usage conditions, exclusions, claim token behavior, rate limits. Could be slightly more concise, but none of the content is redundant.

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

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

The description is fully complete for a tool with no output schema. It explains the claim token response behavior, the rate limiting, the exclusions, and the expected message format. Combined with the rich schema and annotations, an agent has all necessary information to 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 baseline is 3. The description adds guidance for the message parameter ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt') and explains the claim_token usage in a way that clarifies its role as a lookup mechanism. This adds meaning beyond the schema's field-level descriptions.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies the resource (Pipeworx team) and the actions (report bug, feature, data gap, praise). It also distinguishes itself from sibling tools by explicitly limiting to Pipeworx tools, making it clear this is for feedback, not data queries or research like ask_pipeworx.

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

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

The description provides explicit when-to-use conditions: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives exclusions and alternatives: 'ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server... file it with that server instead.' This is 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, 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?

Annotations already mark the tool as read-only, open-world, idempotent, and non-destructive, and the description adds substantial behavioral transparency beyond that: compatibility_warning, compatibility_codes, per-pair flags, skipped_unclassified legs, low_confidence_pairs, temporal_alignment, and skipped cross-type/cross-subtype counters. It honestly communicates that matching is imperfect and that warnings should be read even when matched_pairs > 0.

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

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

The description is long but every sentence earns its place: it front-loads the core purpose, then organizes modes, response shape, safety fields, compatibility codes, and caveats in a logical flow. Despite its length, it avoids filler and repetition, and the structure makes the dense information easy to scan.

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

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

For a complex comparison tool with no output schema, the description covers the essential response elements, safety codes, skipped categories, temporal alignment, and a realistic caveat about pre-mapped topics. An agent has enough information to invoke the tool correctly and interpret even warning-laden results.

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

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

Schema coverage is 100%, and the description meaningfully enriches those semantics by explaining how the topic parameter maps to auto-fetched events and how explicit ticker/slug parameters override the topic-mapped side. It also connects parameters to response behavior, such as which pairs are safe to compare and how warnings are attached, which goes well beyond the basic schema text.

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 computes the cross-venue spread between Kalshi and Polymarket for the same resolving question, distinguishing it from related comparison tools by naming the specific venues and output. It also breaks out two concrete modes, topic shortcuts and explicit pairings, which makes the purpose actionable and distinct.

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

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

The description gives explicit usage context: use the pre-mapped topic shortcuts when available, or provide a custom kalshi_event_ticker/polymarket_event_slug pair for custom comparisons. It also warns that most pre-mapped topics currently return compatibility warnings and that pre-mapped does not mean tradeable. It does not explicitly compare this tool against sibling tools or state when not to use it, so it stops short of a 5.

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 readOnly, openWorld, idempotent, and non-destructive behavior. The description adds substantial context beyond that: internal cascading through multiple endpoints, graceful degradation if GLEIF/OpenFIGI unavailable, and explicit handling of unresolved identifiers. 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 long but each sentence adds value, covering examples, purpose, supported types, input formats, fallback behavior, and internal efficiency. It is front-loaded with the core purpose and structured with clear labels, though it could be tightened without losing information.

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

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

Given there is no output schema, the description carries the burden of explaining what to expect. It details the resolution process, types of identifiers, sources, fallbacks, and explicit handling of unresolved items. For a tool with this complexity, it is remarkably complete.

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

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

Schema coverage is 100% with basic descriptions, but the tool description enriches both parameters significantly: it lists accepted formats for 'value' (ticker, CIK, ISIN, company name; brand/generic for drugs) and explains the meaning of each type in detail. This goes beyond the schema's minimal definitions.

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

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

The description clearly states the tool's function: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It explicitly lists the supported types (company, drug) and what each returns, and distinguishes itself from siblings by positioning as the first step for name-to-ID lookup.

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

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

The description provides explicit usage guidance: 'Use FIRST whenever you have a name but need an ID.' It gives concrete query examples and notes that the tool replaces 2-3 manual lookups, making it clear when to invoke it over alternative 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 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 readOnly/idempotent/open-world hints, but the description goes far beyond them. It explains the two execution paths (SEC EDGAR/XBRL vs. grounded pipeline), the full verdict list, the meaning of 'could_not_verify' as a non-evidence failure with error details, and the distinction from 'unsupported'. This is exemplary behavioral disclosure.

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 intentionally dense. It front-loads with example queries, then flows naturally through usage, routing, output, and error semantics. No sentence is wasted, and the structure mirrors the tool's decision logic. A slightly tighter structure would earn a 5, but this is already 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?

There is no output schema, so the description must explain return values—it does, listing all verdicts, the citation format, and reasoning. It also covers error semantics and edge cases (could_not_verify vs. unsupported). Given the tool's two-domain complexity, this is a complete and self-sufficient description.

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

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

Schema coverage is 100%, with clear descriptions for claim and tolerance_pct. The description adds context about claim routing and verification behavior, but does not add parameter-level details beyond what the schema already provides. Since the schema is sufficient, this is the baseline 3.

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

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

The description leads with natural-language trigger phrases and clearly specifies the action: verify factual claims against authoritative sources and return a verdict. It distinguishes itself from sibling tools like search_filings or entity_profile by focusing on claim verification with structured verdicts, making the purpose unmistakable.

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

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

Explicitly states 'Use whenever...' for checking factual correctness, and explains the routing logic for company-financial vs. other claims. It does not name alternative tools, but the guidance is clear and actionable. The note that it replaces 4-6 sequential calls gives a strong reason to prefer this tool.

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