Sec Form D

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds context on per-model return format, cost implications (free default, BYO key for Anthropic), and that the API key is passed through. It does not mention any side effects or error handling.

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 with no filler: front-loaded purpose, then model details and return structure, then use cases. Every sentence adds distinct value.

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

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

The description covers the tool's purpose, parameters, return shape, and use cases. Without an output schema, it provides enough detail for an AI agent. It could mention potential rate limits or error conditions, but otherwise 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 description coverage is 100%, providing a baseline of 3. The description adds value by explaining the default model, the necessity of _apiKey for Anthropic, and the purpose of the context parameter for disambiguation.

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 per model. It distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on generic entity visibility across models rather than competitive analysis.

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

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

The description specifies use cases (AI-marketing audits, pre-launch checks, competitive monitoring) and explains when to use the default vs paid model. However, it does not explicitly mention when not to use this tool or name alternatives among the many 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=true and idempotentHint=true, and the description adds valuable behavioral context: routing across 5,558 tools, automatic argument filling, structured answers with pipeworx:// citation URIs, and 'works on every tier, one fast call'. No contradictions with annotations; the description enriches the agent's understanding of what happens behind the scenes.

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 the most important guidance ('PREFER OVER WEB SEARCH') and packed with actionable details. It is somewhat long due to the extensive example list and repeated emphasis, but every sentence contributes to usage clarity. The structure flows from use-case to alternatives, making it easy 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?

This tool has no output schema, but the description compensates by stating the return format (structured answer with stable pipeworx:// citation URIs). It covers purpose, domain coverage, when to use alternatives, performance characteristics, and default status. Given the tool's broad scope, the description 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% — the only required parameter 'question' is thoroughly described with aliases in the schema, so baseline is 3. The description adds example queries but no additional parameter semantics beyond what the schema already states. It neither compensates nor detracts, so a 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 ask_pipeworx answers factual questions by routing to 5,558 tools across 1,461 verified sources and returning structured answers with citation URIs. It distinguishes itself from siblings by explicitly saying 'PREFER OVER WEB SEARCH' and by naming alternatives like ask_pipeworx_grounded and deep_research.

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

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

The description provides explicit when-to-use guidance: 'START HERE for most questions', 'PREFER OVER WEB SEARCH', and includes example queries. It also gives clear exclusions: step up to ask_pipeworx_grounded for hallucination-resistant single answers and to deep_research for broad/multi-part questions. This is exemplary usage guidance.

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

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

Beyond annotations, it adds significant context: experimental routing under live test, results compared to stable router, and the clarification that it is a full working router with no fallback. It also reveals the current state (no active candidate) and the retirement date, which helps the agent understand expected behavior.

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

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

The description is composed of four sentences, each carrying meaningful information. It is somewhat verbose but not wasteful; the front-loaded purpose is clear, and the experimental details are organized logically.

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 the tool's complexity (a universal router with experimental logic), the description covers what it is, how it differs from the stable version, current operational state, usage guidance, and its full routin capability. The simple input schema and annotations fill the rest.

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 aliases documented, so the description doesn't need to add much. It does mention 'same arguments' as ask_pipeworx, which is useful cross-reference, but adds no syntax or format details 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 identifies it as a beta version of ask_pipeworx with an identical universal router scope, listing the same 5,558 tools, arguments, and response shape. It explicitly distinguishes itself from siblings by the experimental 'candidate routing improvements' aspect.

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 states when to use it: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also provides context about the current state (no active candidate, matches stable) and comparison against the stable router. It lacks an explicit 'when not to use' statement, but the beta nature 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?

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses the exact success/refusal return shapes, refusal reasons, the extra LLM call cost, and the behavior of extracting only from the tool result. This is rich behavioral context that annotations alone do not provide.

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

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

The description is information-dense and front-loaded with purpose, but it is a bit long due to enumerating refusal reasons and return fields. However, every sentence carries important functional detail for a high-stakes tool, so it is mostly concise relative to its 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?

No output schema exists, but the description fully compensates by spelling out the success object (answer, evidence, confidence, source, fetched_at) and explicit refusal reasons. It also covers the routing mechanism, the cost difference, and the use case, making it self-sufficient 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 description coverage is 100% — all six parameters are aliases for the same natural-language question. The description adds no parameter-specific meaning beyond what the schema already documents, so the baseline of 3 applies.

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

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

The description opens with a clear specific verb+resource: 'hallucination-resistant answer mode' that 'extracts the answer' using only the tool result. It explicitly distinguishes itself from the sibling ask_pipeworx by describing the grounding mechanism, making its 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?

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts...' and when not to use: 'prefer ask_pipeworx for casual lookups.' It names the alternative and even includes the cost trade-off, giving clear decision criteria.

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 covers behavioral traits beyond annotations: low-confidence short-circuiting, closed market handling, wide spread warnings, resolution rule risk, parent extractor, news fallback, and response shapes. 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 well-structured: front-loaded with core purpose, then detailed behaviors and edge cases. Every sentence adds unique value, though density could be reduced.

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

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

Given no output schema, the description fully explains return shapes (market/analysis/evidence fields, market_match_confidence, parent_event, news fields) and all relevant edge cases, making it complete for an agent to understand and 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 coverage is 100% (baseline 3). The description adds significant meaning: market parameter accepts slug/URL/text, depth parameter explains quick vs thorough, include_raw explains size implications. Not fully comprehensive but adds value.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data in one call, specifying input types (slug, URL, question text). It differentiates from siblings like polymarket_edges by focusing on single bet fan-out and evidence packet.

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

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

Explicit usage examples ('should I bet on X', 'what does the data say about Y') guide appropriate queries. While it doesn't explicitly list alternatives, the context is clear for the agent's decision.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds significant behavioral details: correct handling of off-calendar fiscal years, sorting by primary metric, and return of paired data with citation URIs. 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, front-loading purpose with example queries and layering details logically. Each sentence adds value, though slight trimming could improve conciseness 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?

For a tool with two parameters, clear annotations, and no output schema, the description is fully complete. It covers purpose, usage context, data sources, edge cases, sorting, return format, and efficiency benefits, leaving no gaps for an agent to infer.

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 enriches both parameters: explains what each type pulls (revenue/net income for company; adverse events/drug approvals for drug) and provides concrete examples (tickers, drug names). It also clarifies the valid range and format for the 'values' array.

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: side-by-side comparison of 2-5 companies or drugs in one parallel call. It specifies the data sources (SEC EDGAR/XBRL for companies, FAERS for drugs) and explicitly distinguishes from sequential single-entity lookups, which are common among sibling tools like 'entity_profile'.

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

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

The description provides explicit example queries ('Compare X and Y', 'rank these companies') and strong guidance to prefer this tool over sequential lookups, stating it replaces 8-15 lookups. It also specifies constraints (2-5 entities, type required) and implies when not to use (single entity 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?

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description adds rich behavioral detail: account requirement and paid tier for thorough, return format (verbatim evidence + confidence + source + fetched_at + pipeworx:// citation), gaps[] for unanswered facets, contradictions[] for standard/thorough, citation_uri only when fetchable, semantic excerpting, and latency expectations. 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?

Long but front-loaded with the account requirement and alternative, and every section contributes operational detail. Some redundancy with the schema's depth parameter description (e.g., gap recovery and contradictions), but overall the structure is clear and purposeful. Slightly verbose, hence not a 5.

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

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

There is no output schema, so the description must explain return values and behavior—it does. It explains the findings packet, gaps[], contradictions[], hop field, citation_uri resolvability, semantic excerpting, latency, account prerequisites, and depth semantics. It is fully complete for a complex research tool with no gaps in practical understanding.

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

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

Schema description coverage is 100%, and the schema already documents both parameters thoroughly. The description adds the critical 'thorough needs a paid plan' detail and clarifies hop/recovery behavior, but largely restates what the schema already says. This is above baseline (3) because it adds extra operational context, but not maximally distinguished from the schema.

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

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

Description clearly states it performs 'Grounded multi-source research across Pipeworx's 1461 STRUCTURED data sources' in one call, decomposing questions into facets and routing them in parallel. It explicitly distinguishes itself from open-web search and from ask_pipeworx (single lookup), so an agent knows exactly what this tool does and how it differs from siblings.

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

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

Provides explicit when-to-use/when-not-to-use: 'If you are not signed in, use ask_pipeworx instead', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'. Also says 'Best for broad/multi-part questions over structured data', giving clear context and named alternatives.

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

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

Annotations already indicate safe, read-only, idempotent behavior. The description adds that results include full schemas and curated examples, ready to call, which is valuable 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 somewhat verbose with a long list of domains, but front-loaded with the core purpose. Could be more concise without losing value.

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

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

Despite no output schema, the description fully explains what is returned (top-N tools with schemas, ready to call). Parameter set is well-covered with aliases explained.

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. The description explains that query has multiple aliases and provides usage examples, adding context over the schema.

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

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

The description clearly states the tool's purpose: finding tools by describing a data or task, listing numerous domains. It distinguishes itself from sibling tools by being a discovery tool, not a specific data retrieval tool.

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

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

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set', providing clear when-to-use context and implying when not to use.

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

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

Annotations already indicate read-only, idempotent, open-world, and non-destructive behavior. The description adds valuable context: it fans out across multiple sources in a single parallel call, returns specific fields, and notes a patent sunset with soft-fail behavior. 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 dense but well-structured, starting with example queries, then usage guidance, then return details. Every sentence adds value, though it could be slightly more concise 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?

For a complex tool with no output schema, the description is remarkably complete. It enumerates data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), lists return fields, and acknowledges limitations (patent sunset). Fully equips the agent to understand what to expect.

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

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

Schema coverage is 100%, with both parameters described. The description adds context that the value parameter accepts ticker or zero-padded CIK and explicitly states names are not supported (directing to resolve_entity). This extra clarification lifts the baseline from 3 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 provides a full cross-source profile of a US public company, with example queries like 'tell me about X' and 'company profile for Microsoft'. It distinguishes itself from chaining single-pack lookups and from sibling tools like resolve_entity.

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

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

The description explicitly advises to prefer this tool over chaining multiple single-source lookups when a holistic view is needed. It also specifies when not to use it: if only a name is available, use resolve_entity first. This provides clear guidance for selection.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true; description adds context about clearing stale or sensitive data, enhancing transparency beyond annotations.

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

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

Two concise sentences with front-loaded purpose. Every sentence adds value without redundancy.

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

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

For a simple single-parameter tool without output schema, the description covers purpose, usage scenarios, and relationships with siblings, making it fully 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 describes the only parameter 'key' with 'Memory key to delete'. Description adds no significant detail beyond schema; high schema coverage means 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 states the specific action 'Delete a previously stored memory by key' and distinguishes it from sibling tools 'remember' and 'recall', making the purpose clear and 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?

Explicitly states when to use: when context is stale, task is done, or to clear sensitive data. Also mentions pairing with remember and recall, providing 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 indicate readOnlyHint/idempotentHint; description adds nuance about chain completion - incomplete SEC history causing missing originals, and implies grouping logic.

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

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

Two sentences with no filler; front-loaded purpose and caveat, efficient and clear.

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

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

Adequately describes grouping logic and a key limitation. Output schema exists but not shown, so return value details are not missed. Still could mention output structure briefly.

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

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

Description provides no parameter details. Schema covers only 50% (limit has a description, cik does not). The description lacks compensation for the undocumented cik parameter.

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

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

Clearly states the tool groups Form D notices into chains using previous accession numbers, distinguishing it from sibling tools like form_d_issuer_history or form_d_recent_raises by focusing on amendment tracking.

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?

Explains the benefit (prevents mistaken separate raises) and warns about incomplete history, but doesn't explicitly compare to alternative tools like form_d_recent_raises for raw filing lists.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context beyond annotations, such as the hydration from XML and the warning against summing amendments, which clarifies behavior.

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

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

The description is two sentences, front-loaded with the core purpose, and every sentence adds necessary information without 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 that there is an output schema (not shown but indicated), the description is fairly complete. It covers purpose, hydration method, and a key behavioral note. Minor gaps: could mention that results are listed chronologically or paginated, but overall 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?

Schema coverage is 100%, so the schema already documents both parameters. The description does not add additional meaning about the parameters beyond the schema; the warning about amendments is behavioral rather than parametric.

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', the resource 'Form D filing and amendment history', and the scope 'one private issuer'. It is specific and distinguishes from sibling tools like 'form_d_amendment_chains' and 'form_d_offering_detail'.

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 includes a useful caution about not summing amendments, but it does not explicitly state when to use this tool versus alternatives like 'form_d_amendment_chains' or 'form_d_offering_detail'. The usage context is implied but not fully articulated.

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, so the description adds value by explaining the data's nature as a 'normalized regulatory snapshot' and its limitations. This provides context beyond the annotations without contradicting them.

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

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

Two sentences with zero waste: the first clearly states the core function, the second adds crucial behavioral caveats. Every word earns its place, making it highly efficient 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 output schema exists and annotations cover safety and idempotence, the description provides sufficient behavioral context for a normalized regulatory snapshot. The only gap is parameter documentation, but the tool is simple (cik and limit), so overall completeness is high.

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

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

Schema coverage is 0% and the description does not explain the parameters cik or limit. The description only implies that it works per issuer, but does not specify the meaning or range of limit. Without compensation from the description, agents lack clarity on 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 tool returns the latest filing state per amendment-aware Form D chain for an issuer, using specific verbs and nouns. It also distinguishes itself from siblings by emphasizing 'normalized regulatory snapshot' and clarifying what it does not prove, effectively differentiating from related tools like form_d_amendment_chains.

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 important caveats about interpretation ('not proof that the amount sold closed') but does not explicitly state when to use this tool versus alternatives. It implies usage for obtaining latest states per chain but lacks explicit when-not-to-use guidance or sibling comparisons.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and no destruction. The description adds context by specifying 'normalize' and listing the exact fields returned (offering amounts, first sale, etc.), which goes beyond the annotation hints. 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, front-loaded with action and input, then listing outputs. No unnecessary words or repetitions.

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 tool with 1 parameter and an output schema, the description fully covers the tool's purpose and return value. 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%, and the schema description already explains the parameter. The description adds no new detail about the parameter beyond 'by SEC accession number'. 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?

The description clearly states the tool retrieves and normalizes one official Form D XML filing by SEC accession number, listing the specific data points returned. This is a specific verb+resource with clear scope, distinguishing it from sibling tools like form_d_amendment_chains or form_d_search_issuers.

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 use when needing a single Form D filing by accession number, but does not explicitly state when to use or not use this tool, nor does it mention alternatives. The guidance is adequate but minimal.

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 non-destructive, read-only, open-world behavior. The description adds that results are 'newest first' and 'hydrated from official filing XML', which is useful context beyond the annotations.

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

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

The description is two sentences long, perfectly front-loaded with the key action and resource, and every sentence adds value. No filler or redundancy.

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

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

With six parameters and an output schema, the description provides essential context about the data source and ordering. It could mention pagination or scope limitations, but overall it is complete enough for selection and invocation.

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

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

Schema coverage is 100% with good parameter descriptions. The tool description does not add new meaning about parameters, but the schema already covers them adequately. 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?

The description explicitly states it provides 'Recent SEC Form D exempt-offering notices, newest first' with specific fields like offering amount, amount sold, investors, etc. It also explains what a Form D is and warns about amendments, making it distinct from sibling tools.

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

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

The description cautions that Form D is self-reported and not proof of a financing round, and that amendments should not be double-counted. However, it does not explicitly guide when to use this tool versus related tools like form_d_offering_detail.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive. The description adds context by defining related persons as executives, directors, promoters, and noting it includes filing and chain counts. 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?

Two sentences with no extraneous information. The definition is front-loaded and efficient.

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

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

The description lacks parameter explanations and detailed output structure, though an output schema exists. For a tool with 2 parameters and moderate complexity, it is minimally complete but could better guide 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?

With 0% schema coverage and no parameter descriptions, the description does not explain what 'cik' or 'limit' mean. It mentions 'filing and chain counts' but does not link to parameters, leaving semantics unclear.

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 summarizes filer-reported related persons across one issuer's Form D history with filing and chain counts. It distinguishes from sibling 'form_d_related_person_search' by specifying per-issuer scope and excluding investors.

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 it applies to one issuer's recent Form D history and clarifies that related persons exclude disclosed investors. However, it does not explicitly compare with other Form D siblings or provide when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false. The description adds context by explaining that returned results are based on a parsed related-person list and that relationships are filer-supplied, which goes beyond the annotations without contradicting them.

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

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

The description is two sentences with no redundant words. It front-loads the action and purpose, making it easy for the agent to quickly understand the tool's 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 presence of annotations, full schema coverage, and an output schema, the description is complete. It covers the tool's use, matching behavior, and data source, leaving no obvious gaps for the agent.

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

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

Schema coverage is 100%, so parameters are well-documented. The description adds meaning by explaining that the 'person' parameter is used to match after parsing, which clarifies the matching logic beyond the schema's description of the parameter.

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 action: finding Form D notices mentioning a related person and returning only filings where the parsed related-person list matches the given name. It distinguishes this from sibling tools like form_d_search_issuers by specifying the focus on related persons.

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 clear use case ('mapping repeat founders and fund managers') and implies when to use it. However, it does not explicitly exclude alternatives or state when not to use it, leaving some guidance for the agent to infer.

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 that it searches 'live' filings and returns notices (not verified rounds), which provides useful nuance 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 two sentences long with a trailing caveat, all front-loaded and free of extraneous information. Every sentence 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?

Given the presence of an output schema and rich annotations, the description effectively covers the tool's purpose, data source, use case, and a data quality warning. Minor omissions (e.g., pagination, sorting) are acceptable given the schema coverage.

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 parameters are described in the schema (100% coverage). The description adds context for the 'query' parameter (searchable types) and mentions default for 'since'. This adds modest value beyond the schema, leading to a baseline-appropriate score of 3.

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

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

The description clearly states the verb 'search' and the resource 'live SEC Form D filings', specifying the searchable entities (issuer, executive, fund, filing text) and the output (normalized offering notices). It distinguishes from sibling tools that focus on specific filings or history.

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 usage context ('private-company financing diligence and VC market scans') and a caveat about the data's verification status. However, it does not explicitly contrast with sibling tools or state when not to use it, which is a minor gap.

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?

Describes that it fetches the page, extracts title/description/key links, and emits standard markdown format. This adds value beyond annotations (readOnly, idempotent) by explaining the actual process. 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?

Three sentences with no wasted words. The main action is front-loaded, and all information is relevant and compact.

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 purpose, usage, output, and basic behavior. Lacks details on error handling (e.g., invalid URLs) but is otherwise complete for a tool with few parameters and strong annotations.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context about default max_links (25) and the extraction process, but does not significantly enhance parameter 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 'Generate a production-ready llms.txt file for any URL', providing a specific verb and resource. It distinguishes itself from sibling tools, which are mostly unrelated.

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?

Includes a 'Useful for:' section with concrete examples (e.g., getting indexed, drafting, auditing), giving clear context. Does not explicitly mention when not to use or alternatives, but the usage is well-explained.

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, destructiveHint. Description adds value by listing return fields (id, type, params, etc.) which annotations do not cover, but does not disclose any behavioral traits beyond annotations.

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

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

Two sentences, front-loaded with purpose, no unnecessary words. Efficient and well-structured.

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

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

Given low complexity (1 optional param), presence of annotations, and no output schema, the description adequately covers purpose, usage, and return fields. No gaps.

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

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

Schema coverage is 100% (single parameter with description). Description does not add further meaning to the parameter, so baseline 3 applies.

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

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

Description clearly states the verb 'list' and resource 'subscriptions', specifies 'caller's active' to scope. Return fields are enumerated. It distinguishes from sibling tools like subscribe and unsubscribe.

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

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

Explicitly advises using this tool to 'review what you're monitoring before adding more or to find an id to cancel', providing clear use cases. Does not include explicit when-not-to-use, but context is sufficient.

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

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

Annotations are all false, so the description carries full burden. It discloses rate limiting ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), account behavior ('Filing without an account returns a claim_token'), token lifecycle, and team response cadence. 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?

Though a single dense paragraph, every sentence earns its place. It front-loads the core action, then flows naturally through usage, exclusions, mechanics, and limits. No filler or repetition; the length is justified by the richness of needed guidance.

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

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

For a simple feedback tool with no output schema, the description covers all essential contexts: what to report, what not to report, how to follow up, rate limits, and cost. It is fully self-contained and leaves no major ambiguity for an agent deciding when and how to 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%, but the description adds meaning beyond the schema: it explains how claim_token works ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"}) to read whether it was fixed'), and clarifies type values. It doesn't need to restate every param, but the token lifecycle guidance adds genuine 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 opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this from sibling tools (ask_pipeworx, discover_tools) by focusing on feedback to the team rather than querying data or discovering capabilities.

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

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

Explicit when-to-use guidance is given: '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 provides a clear exclusion: 'if the tool came from a different MCP server... file it with that server instead,' naming the alternative action.

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

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

Description provides several behavioral details beyond annotations: caching duration (5min-1h depending on window), data source (CF analytics-engine), privacy (no PII), and the self-aggregating nature. Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint, and the description adds complementary 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?

Three sentences plus bullet-pointed use cases. Every sentence adds value. The core purpose is front-loaded. No redundant or filler content. Highly concise and well-structured.

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

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

For a read-only trend tool with one optional parameter and no output schema, the description fully covers input, expected output shape, caching behavior, data provenance, and privacy. It is contextually complete given the tool's simplicity and the richness of annotations.

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

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

The single parameter 'window' is fully covered by the schema (100% coverage). The description adds practical guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This adds meaning beyond the enum values, justifying a 4 rather than 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?

Description clearly states the tool returns 'top tools, top packs, and total call volume' over a time window. It uses specific verbs ('returns') and resource ('Pipeworx trending data'), and distinguishes itself from siblings like ask_pipeworx and form_d tools by focusing on aggregate usage trends rather than individual queries or 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 lists three explicit use cases (discovering hot data sources, confirming canonical choice, checking alignment). While it doesn't explicitly state when not to use it or name alternatives, the use cases provide clear guidance on appropriate scenarios, and the context signals show many sibling tools for comparison.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds deep behavioral context: semantic anchor (Jaccard similarity threshold), partition filter (placeholder fraction), and fill check (realizable vs theoretical edge). 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 well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded purpose. Every sentence adds value, though a slight trim could improve conciseness without losing clarity.

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

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

Despite no output schema, the description fully explains the response structure and key aspects (gap_pp, suggested_trade, etc.). It covers input modes, edge cases (placeholder filtering), fill check, and even references a related tool. Complete for a tool of this complexity.

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

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

Schema has 100% coverage, but description adds significant value beyond: explains mode selection, provides concrete examples (e.g., 'fed-decision-may-2026'), and details behavior for each parameter. This goes well beyond the schema's brief descriptions.

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

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

The description clearly states it finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes: no args (trending_scan), event mode, and topic mode, making it distinct from sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

Explicit guidance on when to use each mode: 'Call with NO args for a `trending_scan`... pass `event` for the strongest per-event partition_check, or `topic` for a themed cross-event scan.' It also explains trade-offs (e.g., cross-event mode catches patterns single-event misses) and directs to polymarket_fill_risk for custom sizing.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true. The description confirms read-only scanning and adds behavioral details: caching at KV level, diagnostics revealing why segments are empty, edge calculations including slippage and 24h move warning. No contradiction.

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

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

The description is overly verbose and dense, containing implementation details like specific model equations and diagnostics structure. It front-loads purpose but then goes into excessive technical depth that could be simplified or moved to a separate documentation.

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

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

Given the tool's complexity (9 parameters, multiple model families, caching, diagnostics), the description covers all aspects including response segments, why segments can be empty, and edge knobs. No output schema, but the response structure is fully detailed.

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

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

Schema coverage is 100%. The description adds significant meaning beyond schema descriptions, such as explaining how min_kelly skips small opportunities, and how min_partition_leg_kelly applies to per-leg Kelly within partitions. Each parameter's effect is elaborated.

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 scans Polymarket markets for discrepancies with Pipeworx data, for discovering betting opportunities. It distinguishes from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on cross-referencing Pipeworx data.

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

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

The description provides extensive guidance on when to use (for discovering opportunities, with specific model families) and how to tune parameters like min_kelly and slippage_pp. It lacks explicit 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 indicate read-only, idempotent, non-destructive behavior. The description adds significant behavioral details: data source (daily snapshots), bounded history (60-day TTL), decay computation (daily closes, not intraday), and limitations (snapshot enablement date). No contradiction.

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

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

The description is detailed but front-loaded with purpose. Every sentence adds value, though the RESPONSE block could be slightly more structured. Overall, it's fairly concise for the complexity.

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

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

Given no output schema, the description thoroughly explains return fields (tracked, expired, snapshot_dates) with their structure. It covers parameter behavior, limitations, and data freshness. Complete for a telemetry 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 has 100% coverage for both parameters. The description adds context: 'lookback' for days, 'snapshot family' for window, and a lower bound clamp of 2 on days. It also specifies defaults again, reinforcing schema info.

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: edge persistence and decay telemetry. It answers a specific question ('how long has this edge existed and is it shrinking?') and distinguishes itself from sibling tools like polymarket_edges by focusing on temporal analysis rather than snapshots.

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

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

The description implies when to use the tool (when analyzing edge persistence vs. raw snapshot) but does not explicitly list exclusions or alternatives. The context is clear enough for an AI agent to differentiate from siblings.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false, confirming a safe, read-only operation. The description adds significant behavioral detail: walks the ladder, returns fill metrics and a verdict, and highlights risks like thin legs and forced directional risk. No contradictions with annotations.

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

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

The description is well-structured with clear sections for single-market and basket modes, requirements, and return fields. While slightly lengthy, each sentence contributes essential information. Front-loading of purpose and usage guidelines is effective.

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

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

Despite no output schema, the description exhaustively lists all return fields for both modes (e.g., top_of_book, vwap_fill_price, shootout_pp, verdict; for basket: theoretical_sum, capture_ratio, profit_usd, thin_legs, forced_directional_risk). It also explains the logic and risks, providing a complete understanding of tool 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?

With 100% schema coverage, the description still adds substantial value: explains the differing interpretations of size_usd for buys vs sells and for single-market vs basket, and the auto-detection of side in basket mode. This deepens understanding beyond the schema descriptions.

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

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

The description clearly states the purpose: performing a realizable-vs-theoretical edge check against live CLOB order-book depth. It distinguishes between single-market and basket modes, details return values, and explicitly positions itself relative to sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly advises to use this tool before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or polymarket_edges trade above ~$500. It warns about the danger of partial basket fills converting arbitrage into unhedged directional positions, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint: false. The description adds valuable behavioral details beyond these: it explains the two modes, the compatibility_warning scenarios (non-equivalent bet shapes, semantically unrelated events), temporal alignment checks, and counters for dropped comparisons. 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 verbose but each sentence adds essential information. It is front-loaded with the core purpose and modes, then details safety fields. While it could be more structured (e.g., bullet points), there is no redundant or unnecessary 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?

Given the tool has no output schema, the description compensates by detailing response fields (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters). It covers failure modes and constraints. The description is sufficient for an agent to understand the tool’s behavior fully.

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

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

Schema coverage is 100% with descriptions for each parameter. The description enhances understanding by explaining the interplay between topic and explicit parameters, noting that explicit tickers override topic-mapped sides. It also provides concrete examples of allowed topic values and expected formats for explicit tickers.

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

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

The description clearly states the tool computes cross-venue spreads between Kalshi and Polymarket for the same resolution question. It distinguishes itself from siblings like polymarket_arbitrage by specifying cross-venue vs intra-venue arbitrage, and details two modes (topic shortcuts and explicit tickers).

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

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

The description explains two modes (topic and explicit) and when each is appropriate. It includes safety fields that guide when the spread is meaningful or not (compatibility_warning, temporal_alignment). However, it does not explicitly state when not to use this tool (e.g., if only one venue’s data is needed), 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 indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context about scoping to user identifier and that omitting the key lists all keys. No contradictions. Some detail on behavior when key not found would be helpful, but overall strong.

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 delivers the core action and syntax, second provides context, use cases, and scoping. No wasted words, information is front-loaded and 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?

For a simple tool with one optional parameter, no output schema, and rich annotations, the description covers purpose, usage guidelines, behavioral context, and parameter semantics sufficiently. It is 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 has 100% coverage with a clear description for the single optional parameter. The description adds value by explaining the effect of omitting the key (list all), scoping, and pairing with remember/forget. Exceeds baseline 3 for schema coverage.

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

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

The description clearly states the tool retrieves a value by key or lists all keys when omitted, with specific verb 'retrieve' and resource 'value previously saved via remember'. It distinguishes from sibling tools 'remember' and 'forget' by naming them and explaining the pairing.

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 ('to look up context the agent stored earlier'), provides concrete examples of use cases, and mentions scoping. It could be improved by stating when not to use it, but the guidance is clear and 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?

Beyond annotations, describes key behavioral traits: return fields (source, citation_uri, payload), mark_read effect, and feed accessibility. 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?

Four focused sentences, front-loaded with purpose, no extra words. Each sentence adds substantial value.

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

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

Covers return format, filtering, idempotent behavior, and even an alternative channel, despite no output schema. Sufficient 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?

Enhances schema descriptions with examples (e.g., 'sec_8k' for type) and explains mark_read's impact on subsequent calls. Slight deduction for not elaborating on unread_only.

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 'Pull fired events from your subscription feed' with specific verb and resource, and distinguishes from related tools like subscribe and list_subscriptions.

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

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

Provides explicit filtering guidance (type, since, mark_read) and notes that polling works, also offers an alternative access method via URL.

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 behavior. The description adds crucial details: fan-out to multiple sources (SEC, GDELT, GNews, USPTO), fallback logic, and soft-failure for USPTO. No contradiction with annotations.

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

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

Description is moderately long but every sentence is informative and contributes to understanding. Front-loaded with usage examples. Could be slightly more concise but well-structured.

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

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

Despite no output schema, the description explains the return structure (changes[], total_changes, citation URIs) and covers edge cases like USPTO soft-fail and GDELT/GNews fallback. 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 describes all parameters with 100% coverage. Description adds semantic value beyond schema: explains 'since' shorthand formats and 'value' formats (ticker/CIK), and reiterates 'type' constraint.

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: providing a change feed for a company over a recent time window. It distinguishes itself from the sibling tool 'entity_profile', which is for static profiles.

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 gives explicit guidance on when to use this tool versus 'entity_profile', and provides query examples. It also explains the fallback behavior between GDELT and GNews, aiding appropriate 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 include idempotentHint=true, readOnlyHint=false, destructiveHint=false. Description adds scope (scoped by identifier), persistence details (authenticated users persistent, anonymous 24h). No contradiction, and adds useful behavioral context beyond annotations.

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

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

Every sentence adds value: purpose, when-to-use, scope, pairing. No redundant or unnecessary information. Well-structured 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 simplicity of a key-value store and no output schema, the description covers purpose, usage guidelines, persistence behavior, and related tools. Complete for an agent to use 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 descriptions for key and value already explaining their purpose. The tool description does not add further semantics beyond what schema provides, meeting 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?

Description clearly states the tool saves data for reuse, with specific verb 'save' and resource 'data'. It distinguishes from siblings 'recall' and 'forget' by mentioning pairing.

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

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

Explicitly advises when to use: 'when you discover something worth carrying forward.' Mentions alternatives: 'Pair with recall to retrieve later, forget to delete.' Provides clear context for usage.

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

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

Beyond the annotations (read-only, idempotent, open-world), the description discloses important behavioral traits: it resolves multiple identifier types, labels sources, explicitly states unresolved identifiers under 'unresolved', and degrades gracefully when external services are unavailable ('if GLEIF or OpenFIGI is unavailable, the EDGAR identifiers still return'). It also notes internal cascading through several endpoints.

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

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

The description is long but well-structured, with clear sections for supported types, enrichment details, and degradation behavior. Every sentence adds substantive information, but it could be tightened. It front-loads the purpose and usage directive, making it effective despite its length.

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

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

Given the tool's complexity (two entity types, multiple identifier sources, fallback behavior), the description is remarkably complete. It covers inputs, outputs, limitations, and internal behavior. No output schema exists, so the description's explanation of return characteristics (like 'unresolved' field) is essential and well handled.

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?

While the schema already describes both parameters (100% coverage), the description significantly enriches their meaning. It details accepted input formats for 'value' (ticker, CIK, ISIN, or company name for company; brand or generic name for drug) and explains the 'type' enum semantics. This goes well beyond the schema's basic 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: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input'. It uses specific verbs and resources, and differentiates itself by being the go-to identifier lookup tool. The inline examples ('What's the ticker for…') reinforce the 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 gives an explicit usage directive: 'Use FIRST whenever you have a name but need an ID.' This clearly indicates when to employ the tool. However, it does not explicitly name alternative sibling tools or state when NOT to use it, which prevents a top score.

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

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

Beyond annotations (readOnly, idempotent), description explains internal behavior: probes each entity with ai_visibility_check, ranks by score, returns score/confidence/signal density. No contradictions.

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

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

Three sentences, each essential. Front-loaded with purpose, followed by behavioral detail and usage example. No wasted words.

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

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

Given lack of output schema, description sufficiently describes return format (ranked list with score, confidence, signal density). Parameter constraints (2-8 entities) are in schema. Covers what and why.

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?

Adds value beyond schema by explaining first entity treated as subject, models supported (name-dropping Anthropic API key requirement), and context disambiguation. Schema coverage is 100% so baseline is 3, but description provides extra 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?

Clear specification of comparing AI visibility across multiple entities, with explicit mention of ranking and scoring. Distinguishes itself from sibling tools like ai_visibility_check by focusing on side-by-side comparison.

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

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

Provides clear usage scenario ('competitive AI-marketing audits') and example. Does not explicitly mention when not to use or compare to sibling tool compare_entities, but context is sufficient.

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

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

Annotations already indicate safe, read-only, idempotent behavior. The description adds valuable behavioral details: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, sources_failed lists timeouts. 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 front-loaded with the main purpose and is well-structured. It is somewhat lengthy due to detailed return field enumeration, but each sentence adds value given the tool's complexity and lack of output schema. Minor room for trimming.

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

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

Despite lacking an output schema, the description covers return format, failure modes, ecosystem limitations, and practical usage. It provides sufficient context for the agent to correctly select and invoke the tool.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description adds no new parameter meaning beyond what the schema provides; it repeats the scoped package acceptance and default version behavior. 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 it is a composite check for adding an npm package, naming specific sources (deps.dev, bundlephobia) and what it returns. It distinguishes from siblings by specifying NPM ecosystem only, which differentiates it from other tools in the list.

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

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

The description explicitly instructs when to use ('whenever an agent asks is X safe / popular / small...') and when not to use ('NPM ecosystem only; other ecosystems fall under deps.dev:version directly'). It provides clear context and alternatives.

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

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

Annotations already declare safe/idempotent traits. Description adds detailed behavioral info: BGE-base-en embeddings, cosine similarity, 500-char windows, 200K char cap with truncation flagging.

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

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

Concise, well-structured: main purpose first, then details and pairing. 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?

Despite lacking output schema, the description explains return format (passages with offsets and scores), embedding details, and cap behavior. Completely covers what an agent needs.

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

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

Schema covers 100% of parameters. Description adds valuable context: examples for query, mentions offsets and similarity scores for returned passages, and confirms 200K char limit.

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 'Semantic search INSIDE a fetched record' with specific examples like SEC 10-K. It distinguishes from siblings by focusing on internal search of already-retrieved 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 advises when to use—'when the record is too big to cram into the prompt'—and mentions pairing with ask_pipeworx_grounded. Lacks explicit 'when not to use' but 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 indicate it's a write operation (readOnlyHint=false) and idempotent (idempotentHint=true). The description adds significant context: returns subscription id, always-on feed, optional delivery, SMS cap, webhook signing details. However, it does not clarify idempotency behavior (whether duplicate subscriptions are prevented or return same id). Still, it provides rich behavioral detail 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 dense paragraph (~200 words). It front-loads the core purpose but could be more scannable with bullet points. Every sentence adds value; no fluff. The structure is adequate but could be improved for quick parsing.

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

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

Given the tool's complexity (multiple types, delivery options, no output schema), the description covers key aspects: types, params, delivery channels, limitations (SMS cap, phone verification, webhook auto-disable). It lacks explicit return value structure (beyond 'returns id') and error cases, but overall it is fairly complete for a subscription creation tool.

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

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

Schema coverage is 100% so all parameters have descriptions. The description adds extensive examples and details for each type (e.g., sec_8k items codes, polymarket_edge params) and delivery channels (e.g., webhook HMAC signing). This significantly 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 the action ('Create a proactive monitoring subscription') and the resource ('live-data event stream'). It distinguishes from sibling tools like list_subscriptions (list) and unsubscribe (remove) by focusing on creation. The verb+resource combo is specific and 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 specifies prerequisites (Pipeworx OAuth account), supported types with examples, and delivery channel constraints (10/day SMS cap). It implies when to use (to get alerts) but does not explicitly state when not to use or contrast with alternatives like recent_alerts. The context is clear but lacks exclusion criteria.

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

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

Annotations already indicate read-only, idempotent, non-destructive, and open-world behavior. The description adds behavioral context by disclosing that the tool returns example questions from a live catalog and includes tool/argument shapes. No contradictions or missing critical details.

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

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

The description is a single paragraph that front-loads the purpose and includes alternative query forms. It is efficient but includes a list of categories that slightly lengthens it. Every sentence adds value, making it appropriately concise.

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

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

With no output schema, the description fully explains the return value: category-bucketed example questions with tool/argument shapes from the live catalog. It also covers the optional topic parameter and the tool's role as an onboarding entry point. No gaps in context.

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

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

Schema coverage is 100%, baseline 3. The description adds meaning by providing concrete topic examples (finance, pharma, betting) and explaining that omitting the topic gives a wide spread. This enhances the schema 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's purpose: it is the onboarding entry point that returns category-bucketed example questions with tool/argument shapes. It distinguishes from siblings by positioning itself as the first tool to use when the agent doesn't know what Pipeworx can do, differentiating from ask_pipeworx and 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?

Explicit usage guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It also specifies calling with no arguments for full spread or passing a topic to focus. This clearly tells the agent when and how to use the 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?

Description discloses that the row is deactivated (not deleted) and historical events remain via recent_alerts, adding context beyond annotations which provide idempotent and destructive hints.

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

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

Two sentences front-load the main action and provide essential detail without waste. Every word 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?

For a simple one-parameter tool with no output schema, the description covers the effect (deactivation vs deletion), ownership constraint, and impact on historical data. 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 the id parameter already described. The description adds no new meaning beyond 'returned by subscribe', so 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?

The description clearly states the action 'Cancel a subscription by id' with specific verb and resource, and distinguishes from sibling tools like subscribe and list_subscriptions.

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

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

The description mentions ownership enforcement ('you can only cancel your own subscriptions'), but lacks explicit guidance on when to use this tool vs alternatives or when not to use it.

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

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

Annotations already indicate a non-destructive, read-only, open-world tool, and the description adds substantial operational context: the SEC EDGAR + XBRL fast path, automatic fallback for other claims, the exact verdict vocabulary, and the crucial distinction between could_not_verify and unsupported. It also explains the return payload includes verbatim evidence and pipeworx:// citations.

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

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

The description is long but information-dense, with every sentence adding value. It is front-loaded with user phrasing examples and ends with the impactful note about replacing sequential calls. It could be slightly tightened, but the length is justified by the complexity of the tool's behavior and outcomes.

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

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

Given there is no output schema, the description fully compensates by enumerating all possible verdicts, the format of the actual value with citation, and reasoning. It also explains failure modes (could_not_verify with verification_error) and what unsupported means. This is complete for an agent to use the tool safely and interpret results 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 schema already describes both parameters with 100% coverage. The description adds meaningful guidance by explaining that tolerance_pct overrides the tolerance implied by the claim wording and recommending 1–2 for hallucination detection. This goes beyond simply restating 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 opens with concrete natural-language invocations and defines the tool as claim verification against authoritative sources. It explicitly contrasts the company-financial structured path from the general grounded pipeline and notes it replaces 4–6 sequential calls, making it clearly distinct from sibling research 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 states 'Use whenever the agent needs to check whether something a user said is factually correct,' which is clear guidance. It also explains the fallback behavior and the meaning of could_not_verify. However, it does not explicitly mention when not to use the tool or direct users to alternative sibling tools.

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