Ashby

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context: scoring 0-100, dependency on API key for anthropic model, free default. No contradiction.

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

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

Three sentences, front-loaded with the main action. Every sentence adds value: what it does, default model, optional key, return structure, and use cases. No redundancy.

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

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

No output schema, but the description adequately explains the return format (per-model + combined view). All parameters are covered, use cases are given, and optional API key is explained. Complete for the tool's complexity.

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

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

Schema description coverage is 100%, but the tool description adds valuable context beyond the schema: default model is Workers AI Llama-3.3-70b (free), underscore in `_apiKey` indicates it's passed through, and context parameter helps disambiguate common names.

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 a business/brand/product/topic and scores visibility (0-100). It specifies the default model, optional Anthropic key via `_apiKey`, and the return structure (per-model {score, confidence, signals, raw_response} + combined view). This is specific and distinguishes it from sibling tools.

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

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

The description mentions use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It explains when to use the optional `_apiKey` and models parameter. No explicit 'when not to use' or alternatives, but context is clear.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds detail on return contents (contact info, resume, interview history, status), complementing rather than 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: the first succinctly states the purpose, the second lists return contents. No unnecessary words, front-loaded with key information.

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

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

Given the tool's low complexity, 2 required parameters, existing output schema, and annotations, the description sufficiently conveys purpose and return data. It omits error handling or auth details, but these are covered by the schema and annotations.

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

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

Schema coverage is 100% and both parameters are well-described in the schema. The description does not add additional meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description explicitly states 'Get full candidate profile by ID' and lists specific return contents (contact info, resume, interview history, status). It clearly identifies the verb, resource, and scope.

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

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

The description implies usage when a specific candidate ID is known, but does not explicitly mention when to avoid this tool or provide alternatives (e.g., use ashby_list_candidates for listing).

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, indicating a safe, repeatable read operation. The description adds specifics on returned data (description, requirements, etc.), providing 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?

The description is a single, concise sentence that front-loads the action ('Get full job posting by ID') and lists key return fields. It is efficient but could be slightly more detailed.

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 low complexity (2 params, no enums) and presence of an output schema, the description adequately covers the tool's purpose and return fields. It is sufficient for an agent to understand functionality.

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 jobId and _apiKey. The description does not add additional parameter information beyond what the schema already provides, meeting the baseline.

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

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

The description clearly states the tool gets a full job posting by ID, listing specific return fields like description and applicant count. This distinguishes it from sibling tool 'ashby_list_jobs' which lists jobs without full details.

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

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

The description implies usage when you have a job ID, but it does not explicitly state when to use this tool over alternatives like 'ashby_list_jobs' or other tools. No exclusion criteria or context provided.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds minimal extra transparency beyond listing returned fields. No mention of pagination behavior or authentication requirements beyond what schema provides.

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 concise sentence (15 words) that front-loads the action and outputs. No redundant information.

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

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

Given the tool has an output schema, the description need not fully document return values. It covers the main output fields. However, it could mention that results are 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 description coverage is 100%, so each parameter is already documented. The tool description adds no additional meaning to parameters beyond what the schema provides. 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's function: 'Search job applications across positions' and specifies the returned fields (candidate name, applied job, application stage, submission date). This distinguishes it from sibling tools like ashby_list_candidates and ashby_list_jobs.

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

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

The description implies usage for searching all applications but does not provide explicit guidance on when to use this tool versus alternatives (e.g., ashby_list_candidates for candidates). No when-not-to-use advice.

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 and destructiveHint false, so the description's claim 'Search candidates' aligns. However, the description adds no additional behavioral context such as pagination behavior, rate limits, or permission requirements beyond what the schema provides.

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

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

Two efficient sentences with no wasted words. Information is front-loaded: purpose first, then output summary, then sibling reference. Very concise.

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

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

Given the output schema exists and annotations cover safety, the description is sufficient for a simple read-only search tool. It could improve by briefly noting pagination behavior, but it is complete enough 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% for all three parameters (cursor, _apiKey, per_page). The description does not add extra meaning beyond 'Search candidates' and mentions output fields but not parameter usage details. 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 uses a specific verb 'Search candidates' and identifies the resource 'your ATS'. It clearly distinguishes from the sibling ashby_get_candidate by noting that this tool returns names, emails, and application metadata, while the sibling provides full profile details.

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

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

The description advises to use ashby_get_candidate for full profile details, which implies this tool is for broad listing/searching. It does not explicitly state when not to use or provide alternatives, but the sibling differentiation is clear and helpful for an agent.

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, establishing safety. The description adds return details (job title, department, posting details) and filtering options, which supplements the annotations without contradiction.

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

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

Three short, focused sentences: main action first, then filtering, then return scope. No wasted words, easy to scan.

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

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

Given the simple tool (2 parameters, rich annotations, output schema present), the description fully covers necessary context. Return fields are succinctly stated; 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 parameter descriptions already present. Description reinforces status values but adds no new semantic meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states 'Search open positions' with a specific verb and resource, and mentions filtering by status. It effectively distinguishes from sibling tools like 'ashby_get_job' (single job) and 'ashby_list_candidates' (different 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 implies usage for listing jobs with optional status filtering but lacks explicit guidance on when to use versus alternatives like 'ashby_get_job'. No direct when-not-to-use or prerequisite information.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds meaningful behavioral context beyond annotations: it routes to one of 5,347 tools, fills arguments automatically, and returns stable pipeworx:// citation URIs. It also discloses it works on every tier and is one fast call.

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 critical guidance ('PRE FE R OVER WEB SEARCH') but is quite long, running more than 200 words. While much of the detail is valuable (examples, tier info, alternatives), some repetition exists (multiple trigger phrases and example formats cover similar ground). The structure is logical but could be tightened.

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 6 parameters (all aliases of one semantic field), 100% schema coverage, and no output schema, the description is comprehensive. It covers domain scope (SEC, FDA, FRED/BLS, etc.), provides numerous examples, explains the routing mechanism, mentions tier availability, and addresses performance characteristics (one fast call). The behavioral profile and usage boundaries are well covered even without an output schema.

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

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

Schema description coverage is 100%, so the schema already documents the question parameter and its aliases thoroughly. The description reinforces what kinds of questions to ask (factual, real-world entities) and gives examples, which adds some guidance beyond raw parameter documentation, but the schema already carries the full burden for parameter understanding.

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

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

The description clearly states what the tool does with specific verbs and resources: routes factual questions to a database of 5,347 tools across 1,393 verified sources, fills arguments, and returns structured answers with stable citation URIs. It explicitly distinguishes itself from siblings by naming ask_pipeworx_grounded and deep_research as alternatives for step-up scenarios.

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: 'PRE FE R OVER WEB SEARCH', lists trigger phrases ('what is', 'look up', 'find'), gives concrete examples, and names it as the default entry point. It also explicitly states when NOT to use it ('Step up only when needed') and names alternatives (ask_pipeworx_grounded, deep_research), which is excellent differentiation.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable context: that it's an experimental edge, that no candidate is currently active (as of a dated retire), and that results are compared against stable routing. This explains behavior beyond what annotations convey, though it doesn't detail response format or error 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?

Description is compact and front-loaded with the essential purpose. Each sentence earns its place — purpose, beta context, current-state clarification, and usage directive. Slightly wordy around the dated retirement detail but no redundancy.

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

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

For a router-style tool with read-only, idempotent annotations and 100% parameter schema coverage, the description is complete. It covers what the tool is, its current operational state, when to use it, and how it relates to siblings. No output schema exists, so return-shape explanation isn't required by the rubric.

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

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

Schema description coverage is 100%, so the schema documents all six parameters, with the question field fully explained including six named aliases. The description adds no additional parameter semantics beyond what the schema already provides, so baseline 3 is appropriate given full 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?

Description clearly states this is a beta/router variant of ask_pipeworx with the same 5,347 tools and arguments, and differentiates it from siblings (ask_pipeworx, ask_pipeworx_grounded). The verb 'ask' plus the router context is clear, though it leans on sibling comparison rather than standalone specificity.

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

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

Description explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing,' names the stable alternative, and explains the comparison/merge context. It also clarifies the current no-candidate state, telling the agent it currently behaves identically to ask_pipeworx — strong when/when-not guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds significant value beyond annotations: explains the routing mechanism, the refusal contract with specific refusal_reason values, and the exact return shape including evidence as verbatim quote. Notably transparent about cost (one extra LLM call). Minor gap: doesn't detail behavior on partial-but-usable data, but the data_truncated refusal reason covers much of it.

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

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

Substantial but densely informative. Every sentence earns its place: purpose, mechanism, return contract, when-to-use, cost tradeoff. Slightly long but the refusal-code enumeration and routing detail justify the length. Front-loaded with the most important qualifier ('Hallucination-resistant'). Not padded.

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

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

For a grounded answer tool with no output schema, the description fully documents the return contract including all refusal_reason enum values, success shape, and behavior constraints. The routing/tool-count detail adds operational transparency. Given the complexity (routing across 5,347 tools, extraction, refusal logic), this is near-complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100% with detailed alias documentation already present. The description adds the natural-language framing (the question being the only input) and clarifies that aliases are accepted, reinforcing what the schema states. It reinforces the semantics without redundancy. Baseline 3 elevated because the description clarifies the single-question input model, which is the needed compensation given the aliases.

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?

Very specific: 'Hallucination-resistant answer mode for high-stakes reads' with clear verb (extract/fetch) and resource (Pipeworx tools). Explicitly distinguishes from sibling ask_pipeworx by the grounding/extraction behavior, and names the sibling alternative directly.

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?

Excellent guidance: explicitly states when to use (quoted/cited/acted-on answers, financial/legal/medical/public statements) and when NOT to (casual lookups — prefer ask_pipeworx due to extra LLM call cost). Directly compares with the sibling tool.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds extensive behavioral context: resolver contract (match confidence, alternatives), parent event extractor, news fallback fields, safety short-circuits on low confidence, closed market handling, wide-spread warnings, and cancellation rule parsing. 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 verbose with multiple paragraphs and technical detail. While all content is relevant, it could be more concise. Front-loading is good (first sentence states purpose). Structure uses section labels, but overall length may reduce quick readability.

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

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

Given the tool's complexity (multiple classifiers, fan-out packs, edge cases), the description covers all necessary aspects: input resolution, evidence sources, response shapes, resolver contract, parent events, news fields, safety mechanisms, and resolution rules. No output schema exists, but response shapes are described.

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

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

Schema coverage is 100%, yet the description adds significant meaning: explains 'depth' quick vs thorough, 'market' parameter with three accepted formats and examples, and 'include_raw' with size implications and use cases. Adds value beyond schema.

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

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

The description starts with a clear action verb ('Research') and specific resource ('Polymarket bet'), states inputs (slug, URL, question text), and output (evidence packet + comparison). It distinguishes from siblings by specializing in Polymarket betting 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?

Explicitly suggests use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. Includes classifier examples and fan-out scenarios. Does not explicitly state when not to use or point to alternative tools, 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 declare readOnlyHint, idempotentHint, and openWorldHint. Description adds valuable context: data sources (SEC EDGAR/XBRL, FAERS, FDA), correct handling of off-calendar fiscal years for companies, and that results are sorted by primary metric. No contradiction with annotations.

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

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

Description is dense but efficient: front-loads trigger phrases, then explains behavior per entity type, then output format. Every sentence serves a purpose with no redundancy. Well-structured 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?

Despite no output schema, the description mentions return of paired data with citation URIs, which is adequate. Covers key behaviors like data sources, sorting, and entity limits. Minor gap: does not specify response format (e.g., table or JSON), but overall complete for a comparison tool with rich annotations.

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

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

Schema coverage is 100% with descriptive parameter comments. Description adds practical usage details: examples of tickers vs CIKs for companies and drug names, plus reinforces the 2–5 range. This adds moderate value beyond the schema.

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

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

Description provides explicit trigger phrases and clearly states the tool performs side-by-side comparison of 2–5 companies or drugs, with specific data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs). It distinguishes from sibling tools like entity_profile by emphasizing multi-entity comparison in one call.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and quantifies efficiency ('replaces 8–15 sequential lookups'). Provides clear when-to-use guidance with no ambiguity.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds substantial context beyond this: the parallel decomposition into facets, the gaps[] mechanism guaranteeing no invention, contradictions[] scan, semantic excerpting, timing ranges (15-90s), hop field, and citation stable URIs. It could note whether the tool consumes rate-limited credits, but for a research action this is thorough behavioral disclosure.

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

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

The description is very information-dense but runs long (roughly 250+ words) with long run-on sentences mixing parentheticals, em-dashes, and semicolons. Key facts are front-loaded (account requirement, not open-web, one-call parallelism) but the density makes it hard to scan. Punctuation-heavy structure with chains of colons and multiple asides ('— this is NOT open-web search') reduces readability despite the valuable 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?

For a 2-param tool with 100% schema coverage, no output schema, and rich output semantics (findings packet with verbatim evidence, confidence, source, citations, gaps, contradictions, hop fields), the description goes well beyond what structured fields provide. It compensates for the missing output schema by describing return shapes, addresses the openWorld/closedWorld tension (structured only, not open-web), and covers timing, pricing, and iteration behavior. The setup is complex enough that this level of detail is warranted.

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 meaning to both params: it explains what depth levels mean operationally (quick=3, standard=5 with gap recovery + contradictions, thorough=8 paid with full iterative hop) and clarifies the 'question' param accepts broad/multi-part natural language ('Decomposes your question into focused facets'). The schema already documented these well, so the description's marginal add is modest but real.

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 is exceptionally specific: 'Grounded multi-source research across Pipeworx's 1393 STRUCTURED data sources in ONE call' with clear verb (research), resource (structured data sources), and explicit NOT-open-web-scope. It clearly distinguishes from siblings by describing its parallel decomposition architecture, citing ask_pipeworx as the alternative, and enumerating what it covers.

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?

Extremely explicit when-to-use: 'Best for broad/multi-part questions over structured data.' It names alternatives directly ('For a single lookup use ask_pipeworx'; 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'). Also covers prerequisites (account required, paid tier for thorough), depth-mode selection, and second-hop iteration behavior. 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?

Annotations indicate readOnly, idempotent, non-destructive. Description adds that it returns top-N tools with full schemas and examples, ready to call directly.

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?

Front-loaded with purpose, then lists domains and return format. Slightly long but clear 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?

Comprehensive for a discovery tool with 6 params (1 required). Explains return format sufficiently without output schema.

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

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

Schema coverage is 100% and description reinforces the query parameter's purpose with examples, though it doesn't add much beyond the schema.

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

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

The description clearly states it finds tools by describing data/task, listing many domains. It distinguishes from siblings as a meta-tool for discovery.

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

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

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set' and 'Use when you need to browse, search, look up, or discover what tools exist'.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context: fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), returns specific fields, and mentions the USPTO PatentsView API sunset and soft-fail. 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 front-loaded with examples and the core purpose. It includes useful return field details but is slightly verbose. Every sentence adds value, though it could be trimmed slightly for conciseness.

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

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

Despite no output schema, the description enumerates return fields (cik, company_name, recent_filings, fundamentals, patents, news, LEI) and their structure. It covers data sources and constraints (e.g., recent_filings up to 5). For a complex tool, this is fairly 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%, and parameters have clear descriptions. The description reinforces that value is either ticker or CIK and that names are unsupported. It adds no new semantic detail beyond the schema, so baseline 3 is appropriate.

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

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

The description starts with multiple user intent examples (e.g., 'Tell me about X', 'brief me on Tesla'), then explicitly states 'full cross-source profile of a US public company in ONE parallel call.' It clearly identifies the verb (profile/research) and resource (company). Sibling tools like search_within or resolve_entity are distinct, so this tool is well-differentiated.

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

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

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

Annotations already provide destructiveHint=true and idempotentHint=true; description adds context about clearing sensitive data but no further behavioral 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?

Two concise sentences, front-loaded with key action, no filler.

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

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

Single-parameter tool with clear purpose and usage guidelines; sibling references complete the 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 provides full coverage (100%) with description 'Memory key to delete'; tool description does not add additional semantic 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?

Clearly states 'Delete a previously stored memory by key.' with specific verb and resource, and distinguishes from siblings by mentioning 'remember' and 'recall'.

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

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

Explicit use cases: 'when context is stale, the task is done, or you want to clear sensitive data...' and suggests pairing with remember/recall.

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 behavior. The description adds process details: fetches page, extracts title/description/links, outputs a single text blob. 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 well-structured sentences, no unnecessary words. First sentence states purpose, second explains process, third lists use cases. Highly efficient.

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

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

Given two parameters, no output schema, and comprehensive annotations, the description provides adequate context: output format, target audience, and use cases. Missing potential error scenarios (e.g., invalid URL) but acceptable for a simple read-only tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add significant new meaning beyond the schema—it only mentions 'extracts title/description/key links' without detailing parameters.

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

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

Clearly states the tool generates an llms.txt file for AI crawler indexing, with a specific verb and resource. It distinguishes itself from sibling tools like scan_competitor_ai_presence by its unique 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?

Explicitly lists three use cases (client site indexing, own project drafting, competitor auditing). Does not mention when not to use or alternatives, but the use cases are clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. Description adds return fields and context about include_inactive, providing value beyond annotations.

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

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

Two concise sentences: first states purpose, second gives usage guidance. No fluff, 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?

Simple tool with one optional parameter, no output schema, and clear annotations. Description covers return fields, usage context, and parameter implication sufficiently.

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 description for include_inactive. The description does not add new parameter details but implies the parameter by mentioning 'active'. Baseline of 3 is appropriate.

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

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

Clearly states 'List the caller's active subscriptions' – specific verb and resource. Distinguishes from sibling tools like 'subscribe' and 'unsubscribe' by focusing on listing.

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 guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Clearly tells when to use it, though does not mention 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?

Discloses rate limiting (5 per identifier per day), free usage, and that it doesn't count against tool-call quota. Annotations only indicate non-read-only and non-destructive; the description adds valuable behavioral context beyond what annotations provide.

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

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

The description is informative and well-structured, starting with the action and then elaborating on usage. It is slightly verbose but every sentence adds value; could be tightened slightly 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?

Covers all necessary information for using this tool: purpose, usage scenarios, parameter guidance, rate limits, and cost implications. No output schema, but the description provides sufficient context for the agent to invoke it 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?

Input schema has 100% description coverage per parameter. The description adds extra context on how to frame the message (in terms of tools/packs) but does not significantly extend beyond the schema definitions. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: to send feedback about bugs, missing features, data gaps, or praise. It uses specific verbs ('tell', 'describe') and distinguishes between different feedback types, making it distinct from sibling tools which are primarily read or analysis 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?

Provides explicit guidance on when to use each feedback type (bug, feature/data_gap, praise) and what not to do (don't paste end-user prompt). Also mentions rate limits and quota exemption, helping the agent decide when to invoke this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive nature. The description adds valuable context: self-aggregating signal, no PII, and caching behavior (5min-1h). 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 concise (3 sentences), uses bullet points for use cases, and front-loads the core 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?

The tool is simple (one optional param, no output schema). The description explains the return structure, caching, privacy, and window semantics. It is fully adequate for an agent to understand usage and expectations.

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 enum description. The description adds meaning by explaining the trade-off: shorter windows for hot trends, longer for steady-state demand. This helps the agent choose the right window.

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

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

The description clearly states that the tool returns top tools, top packs, and total call volume over selected windows. The verb 'returns' and the specific resources ('top tools, top packs, total call volume') make the purpose unambiguous. It distinguishes itself from sibling tools like discover_tools by focusing on trending social proof.

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 three explicit use cases (discovering hot sources, confirming popular tools, checking alignment) and explains window choices (short vs. longer windows). It lacks explicit when-not-to-use guidance, but the context is clear enough for an AI agent to decide.

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

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

The description provides rich behavioral context beyond annotations: monotonicity checks, partition sum logic, semantic anchor (Jaccard similarity ≥0.30), partition filter (placeholder slugs), fill check against CLOB depth, and warnings like 'do not trade it' when realizable_edge_pp ≤ 0. 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 fairly long but every sentence adds value. It is front-loaded with the core purpose and mode distinctions. Minor improvement could be breaking into sections, but it remains clear and not verbose.

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 response structure: opportunities[] with gap_pp, suggested_trade, reasoning, etc., and partition_check fields. It also covers edge cases like fill check and custom sizing. Complete for a complex tool.

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

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

Schema coverage is 100% for both parameters. The description adds deep semantic meaning: explains what event string format is accepted (slug or full URL), what topic represents (seed question), and how each mode uses the parameter. This goes beyond the schema's short 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 explicitly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It clearly distinguishes three modes (no args for trending scan, event for single-event, topic for cross-event) and differentiates from siblings like polymarket_edges and polymarket_fill_risk.

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

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

The description gives clear guidance on when to use each mode: 'Call with NO args for a trending_scan... pass `event` for per-event partition_check, or `topic` for cross-event scan.' It recommends 'event (recommended for a specific market)' and explains what each mode does. It lacks explicit 'when not to use' but is still very helpful.

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

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

The description goes far beyond the readOnlyHint, openWorldHint, idempotentHint, and destructiveHint annotations. It details caching (1h at KV level), diagnostics output, the three model families, and how Fed bets are handled. No contradictions with annotations.

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

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

The description is relatively long but well-organized into sections. It is front-loaded with the core purpose. Every sentence adds information, though some detail (e.g., exact α values) could be moved to documentation. Still, it is efficient for the complexity.

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

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

Given the complexity (9 parameters, 3 segments, multiple model families, caching, diagnostics, and no output schema), the description is exceptionally complete. It explains response structure (by_segment, fed_candidates, diagnostics) and how to handle empty segments, leaving no major gaps.

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

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

All 9 parameters are described in the schema (100% coverage), and the description adds significant value beyond the schema. For example, it explains slippage_pp context (Polymarket fees, bid/ask), max_spread_pp and min_liquidity as 'tradeable-edge filters', and min_partition_leg_kelly clarifies why min_kelly doesn't filter partitions.

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 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price', providing a specific verb and resource. It distinguishes itself from siblings like polymarket_arbitrage by focusing on edge discovery and explicitly mentioning the purpose 'Built for "what should I bet on today"'.

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 clear context for when to use the tool ('what should I bet on today') and explains tuning knobs like min_liquidity and max_spread_pp. However, it does not explicitly exclude cases when alternatives should be used (e.g., polymarket_arbitrage for pure arbitrage).

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 significantly expands on annotations (readOnlyHint, idempotentHint) by detailing data sources (daily snapshots), limitations (60-day TTL, snapshot gaps), computation details (decay from daily closes), and response structure. 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 information-dense and front-loaded with the core purpose. Every sentence adds value, but it is somewhat lengthy. A slightly more concise rewrite could improve readability without losing 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 2 parameters with 100% schema coverage and no output schema, the description thoroughly explains the response fields (tracked[], expired[], snapshot_dates[]), includes limitations, and covers edge cases (gaps, TTL). It is fully complete for an agent to invoke correctly.

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

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

Both parameters have schema descriptions, but the description adds meaningful context: default values (days=14, window='1wk'), clamping (2-30 for days), and explains the 'window' as a snapshot family. It also provides the response structure, which is valuable beyond schema.

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

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

The description clearly states the tool provides 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and answers a specific question about edge longevity. It distinguishes itself from sibling tools like polymarket_edges by focusing on historical time-series and decay metrics.

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 clear context on when to use (e.g., assessing if an edge is fresh or old) and the rationale behind it. However, it does not explicitly state when not to use or provide alternatives like polymarket_edges for current edges.

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, and non-destructive behavior. The description adds substantial behavioral details: walks the order book ladder, returns specific fields like top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, and verdict; for basket mode includes per-leg fill detail, thin_legs, forced_directional_risk. This goes far beyond the annotations in explaining 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 dense but well-structured, front-loading the core function and then clearly separating single-market and basket modes with headings. Every sentence serves a purpose, explaining mode-specific arguments, return values, and usage rationale. It is concise given the complexity of the tool.

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 with two modes and multiple return fields, the description covers all necessary aspects: mode-specific parameters, return values for each mode, edge cases (thin legs, partial fills), and actionable guidance. No output schema is provided, but the description fully compensates by enumerating all return fields.

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

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

Input schema already describes all 4 parameters with 100% coverage, which sets a baseline of 3. The description adds value by contextualizing parameters within single-market vs basket modes, explaining the default for side in basket mode, and clarifying size_usd semantics for each mode (spend vs target proceeds vs settlement notional). This enriches understanding beyond the schema's descriptions.

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

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

Description clearly states it performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' This specific verb+resource distinguishes it from sibling tools like polymarket_arbitrage (signal generator) and polymarket_edges (edge detection), which are about generating signals rather than verifying fill feasibility.

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

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

Explicitly instructs 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the rationale: theoretical overround on thin books is not capturable and partial basket fills convert arb 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 (readOnlyHint, openWorldHint, idempotentHint) are complemented by extensive details: the tool explains safety fields (compatibility_warning, temporal_alignment, skipped_cross_type/subtype) and conditions where spreads are meaningless. No contradiction with annotations.

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

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

The description is dense and front-loaded with the core purpose, then modes, response, and safety fields. While every sentence adds value, it is somewhat long and could be slightly more concise.

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

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

With 3 parameters and no output schema, the description thoroughly covers the tool's behavior, input modes, response structure, edge cases (compatibility warnings, temporal alignment), and provides specific examples. No gaps remain.

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

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

Schema coverage is 100% with parameter descriptions. The description adds value by explaining the two modes (topic vs. explicit) and that kalshi_event_ticker/polymarket_event_slug override mapped values, going beyond the schema.

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

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

The description clearly states it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question, distinguishing itself from sibling tools like polymarket_arbitrage which focus on single-venue opportunities. The two modes (topic and explicit) are clearly defined.

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

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

The description explains when to use the tool (to find spreads), when not (when compatibility_warning fires due to non-equivalent bet shapes or unrelated events), and that pre-mapped topics often return warnings. It could mention alternative tools more explicitly but provides sufficient 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 readOnly, idempotent, non-destructive. Description adds scoping: 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID).' 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, no wasted words. Front-loaded with purpose, then usage and scoping. Excellent structure.

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

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

Single optional parameter, no output schema, annotations present. Description fully covers usage, scoping, and pairing with siblings. 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%. Description explains optional key parameter: 'omit the key argument to list all keys', adding value beyond schema.

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

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

Description clearly states 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' This specifies the exact action and resource, and distinguishes from sibling tools (remember, forget).

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

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

Describes use case: 'look up context the agent stored earlier' and pairs with remember/forget. No explicit when-not or alternatives, but context is clear.

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

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

Annotations already declare readOnly and idempotent. Description adds that mark_read:true advances the cursor for subsequent calls, and explains return payload fields (source, citation_uri). This is valuable behavioral context.

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

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

5 sentences, no redundancy. Front-loaded with purpose, then explains parameters and usage. Every sentence earns its place.

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

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

No output schema, but description explains return fields. Covers filtering, mark_read, polling, and alternative endpoint. Complete for a read-only alert retrieval 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, but description adds example for type ('sec_8k') and clarifies mark_read behavior ('flag returned events read so the next call only shows newer ones'). This adds meaning beyond schema.

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

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

Description clearly states 'Pull fired events from your subscription feed' with specific verb and resource. It differentiates from sibling tools like list_subscriptions by focusing on fired events/alerts.

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 filtering options (type, since) and mentions polling suitability. Includes alternative access via URL for scripts/dashboards. Could explicitly state when not to use, but context is strong enough.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: fan-out behavior, fallback mechanism from GDELT to GNews on rate limits/5xx, USPTO soft-failure due to PatentsView API sunset, and the returned structure (changes grouped by source, total_changes count, pipeworx:// URIs). 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 a single dense paragraph that efficiently conveys all needed information. It is front-loaded with example queries. Could be slightly more structured (e.g., bullet points for sources) but remains concise and informative.

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 adequately explains the return format and all key behavioral aspects: multi-source fan-out, fallback logic, known limitations (USPTO soft-fail), and parameter usage. Covers all essential context for an agent to use the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning: relative shorthand for 'since' (e.g., '7d', '1y'), explicit recommendation of '30d' or '1m' for monitoring, and examples of valid 'value' inputs (ticker or CIK). This exceeds the baseline.

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

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

The description clearly states the tool's purpose as a change feed for a company within a time window, listing specific data sources (SEC EDGAR, GDELT→GNews, USPTO) and explicitly distinguishes itself from the sibling tool 'entity_profile' by contrasting dynamic vs 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?

The description provides explicit usage guidance, including example queries ('What's new with X', 'latest on Y'), when to use this tool vs 'entity_profile', and details on the 'since' parameter format with recommended defaults ('30d' or '1m').

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

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

Description adds value beyond annotations: scoped by identifier, persistence details, and idempotent nature. No contradiction with annotations (readOnlyHint false, idempotentHint true).

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

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

Three sentences, front-loaded with purpose, no wasted words. Every sentence adds value.

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

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

Given no output schema, description covers behavior, persistence, pairing, and usage scenarios. Complete for a simple key-value store 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 adequate descriptions. Description enhances with practical examples of keys (e.g., 'subject_property', 'target_ticker'), adding meaning beyond schema. Baseline 3, plus 1 for 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?

The description clearly states the tool saves data for reuse across conversations/sessions, using a specific verb-resource pair. It distinguishes from siblings like recall (retrieve) and forget (delete).

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

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

Explicitly tells when to use: 'when you discover something worth carrying forward'. It describes pairing with recall and forget, and provides context on scoping and persistence (auth vs anonymous).

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds valuable context: each call cascades through several lookup endpoints internally, replaces 2-3 manual lookups, and explains the return format for each type (including citation URIs). No contradiction with annotations.

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

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

The description is a single paragraph but efficiently packs examples, use case, supported types, and return details. It is front-loaded with example queries. Could benefit from bullet points for readability, but remains concise and informative.

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 adequately explains return values for each type (ticker, CIK, RxCUI, citation URIs). It covers the supported types and input formats. However, it omits error handling or edge cases (e.g., ambiguous names), but overall suffices for a straightforward resolution 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%, but the description adds meaning beyond the schema: it provides concrete examples for each accepted value (e.g., 'AAPL' for ticker, '0000320193' for CIK, 'ozempic' for drug) and clarifies the output behavior per type, aiding the agent in constructing valid inputs.

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

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

The description starts with concrete example queries (ticker, CIK, RxCUI) and clearly states the tool's purpose: resolving a user-spoken name to a canonical/official identifier. It distinguishes itself from sibling tools by noting it replaces 2-3 manual lookups, making its role unique.

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 'Use FIRST whenever you have a name but need an ID.' Supported types are detailed with input examples. However, it does not explicitly state when not to use it (e.g., if an ID is already known) or mention alternative tools for cases where the entity type is unsupported.

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

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

Discloses internal use of ai_visibility_check, ranking by score, and output format (ranked list with score, confidence, signal density). Annotations already declare readOnlyHint, openWorldHint, idempotentHint; description adds meaningful behavioral context without contradiction.

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

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

Two concise sentences: first states action, second adds context and output details. No superfluous words, 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?

Describes output (ranked list with score, confidence, signal density) in absence of output schema. Covers required parameter (entities) and optional details. Complete for a comparison 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%, and description does not add substantial meaning beyond parameter descriptions. Mentions default model and array size, but these are covered in 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 uses specific verb 'Compare AI visibility' and resource 'multiple entities', clearly distinguishes from sibling ai_visibility_check which checks a single entity. Provides example use case to clarify 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?

States usefulness for competitive AI-marketing audits with concrete example. Implicitly suggests when to use (multiple entities) vs ai_visibility_check (single entity) but does not explicitly exclude 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 the tool as read-only, open-world, idempotent, and non-destructive. The description adds valuable behavioral details such as fan-out to two services, potential 5-30s timeout for new versions, and return of a summary block with specific fields. This exceeds what annotations alone 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 well-structured with the core purpose upfront ('Composite check in ONE call'), followed by details on return value, ecosystem limitations, and error behavior. Every sentence adds value, and the length is appropriate for the tool's complexity.

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

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

Since no output schema is provided, the description fully enumerates the return fields (summary block fields, advisory details, links, alternative versions) and explains partial failure behavior. No critical information is missing for an agent to use the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds implicit context by explaining how parameters are used (e.g., 'Defaults to the latest published version when omitted') and constrains the 'package' parameter to the npm ecosystem. This provides meaningful extra information beyond the schema.

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

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

The description clearly states the tool's purpose: a composite check for npm packages that gathers license, advisories, version history, and bundle size info. It differentiates itself from sibling tools like 'deep_research' and 'scan_competitor_ai_presence' by focusing on a specific npm package evaluation.

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 specifies when to use this tool (e.g., 'is X safe / popular / small') and provides alternatives for other ecosystems (PyPI, Maven, etc.). It also mentions graceful degradation for partial failures, giving clear usage context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral details: uses BGE-base-en embeddings + cosine over 500-char overlapping windows, caps input at 200K chars with truncation and flagging. 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 appropriately sized and front-loaded with the core purpose. Every sentence provides useful information without redundancy. Could be slightly more concise, but overall well-structured.

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

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

Given the complexity and no output schema, the description adequately explains return values (top-N passages with character offsets and similarity scores), truncation behavior, and technical specifics (embedding model, window size). Sufficient for an 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 all three parameters described. The description adds meaning beyond the schema by explaining the nature of 'query' with examples, specifying that 'text' is the document to search inside with a max length, and clarifying 'limit' as max passages with a default and range.

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

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

The description clearly states it performs semantic search inside a fetched record, with specific examples like SEC 10-K body or article. It distinguishes from siblings by noting it is for searching within a specific text, and pairs with ask_pipeworx_grounded.

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

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

Explicitly says to use when the record is too big for the prompt, saving context and returning only relevant passages. It also provides pairing guidance with ask_pipeworx_grounded and outlines when to avoid using alternative tools.

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

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

Annotations declare idempotentHint=true, but description adds that it creates a new subscription. It also discloses important behavior: phone must be verified before sms delivery, 10/day sms cap, webhook auto-disabled after 10 consecutive failures, and the one-time nature of webhook secret. No contradiction with annotations.

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

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

The description is front-loaded with the purpose and returns value. It is moderately long but each sentence adds valuable information. Could be slightly improved with bullet points for readability, but overall it is well-structured and not redundant.

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

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

No output schema exists, but description mentions the return value (new subscription id). It covers all parameters and their constraints, explains delivery channels in depth, and addresses preconditions (phone verification, account type). For a complex tool with nested parameters, the description is fairly complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds substantial meaning beyond the schema: it explains the enum values for 'type' with concrete examples (e.g., 'sec_8k: items:["5.02"] = officer change'), details the 'params' object structure for each type, and clarifies constraints on 'delivery' fields (e.g., sms must match verified phone, webhook secret only returned once).

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 'creates a proactive monitoring subscription to a live-data event stream' and 'Returns the new subscription id'. This is a specific verb+resource, and it distinguishes from sibling tools like 'list_subscriptions', 'unsubscribe', and 'recent_alerts'.

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

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

The description explains when to use this tool (to set up monitoring) and includes alternative delivery methods: 'pull via recent_alerts or GET registry.pipeworx.io/alerts.json' for the feed. It also mentions that anonymous users cannot persist subscriptions, requiring a Pipeworx OAuth account. However, it does not explicitly state when not to use this tool.

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

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

Adds context beyond annotations: explains output format (category buckets with exact tool+argument shape), behavior with no args vs topic, and connection to live catalog. 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?

Description is thorough but slightly verbose. Well-structured with common queries, output description, usage, and when-to-use. Every sentence is valuable but could be tightened.

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 and single optional parameter, the description fully covers functionality, usage, and outcomes. Comprehensive for an onboarding tool.

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

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

Schema coverage is 100% and description adds example values ('finance', 'pharma', etc.) and clarifies omission behavior, significantly enriching the parameter meaning.

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 is an onboarding entry point that returns category-bucketed example questions with tool calls, and distinguishes it from meta-tools like ask_pipeworx. Uses specific verbs and resource identification.

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

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

Explicitly says 'Use this FIRST' and describes how to call with/without topic. Lacks explicit exclusions but provides clear context for appropriate 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?

Adds context beyond annotations: ownership enforcement, deactivation instead of deletion, and impact on historical events. Annotations already indicate idempotent and non-destructive; description aligns and enriches.

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

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

Two sentences, front-loaded with the core action, each sentence adds essential information without redundancy.

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

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

Covers purpose, side effects, ownership, and relation to other tools ('recent_alerts'). Although there is no output schema, the tool is simple; the description is sufficient for correct use.

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

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

Schema has 100% coverage with a clear description of the 'id' parameter. The tool description does not add further parameter details, but it provides ownership context that relates to the parameter. Baseline of 3 is appropriate.

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

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

Clearly states the action 'cancel a subscription' by id, distinguishing from siblings like 'subscribe' and 'list_subscriptions'. Mentions that it deactivates rather than deletes, which is a key behavioral 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?

Explicitly states ownership enforcement ('you can only cancel your own subscriptions'). Implies when to use, but does not provide explicit alternatives or exclusions. The reference to 'recent_alerts' indirectly guides post-cancelation behavior.

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

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

Annotations indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral details: it returns a verdict (confirmed/refuted/etc.), actual value with citation, and reasoning. It also mentions that the tool replaces 4-6 sequential steps. No contradiction with annotations.

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

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

The description is well-structured, starting with example triggers, then stating purpose, then detailing behavior for different claim types, and finally listing return values. It is packed with useful information without being overly verbose.

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

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

Despite no output schema, the description fully explains return values (verdict, actual value, citation, reasoning) and covers both claim types. It also mentions that it replaces multiple sequential steps, making it complete for the tool's complexity.

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

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

Schema coverage is 100% for the two parameters (claim and tolerance_pct). The description adds examples and context for each parameter, such as natural-language examples for claim and default behavior for tolerance_pct.

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: natural-language claim verification against authoritative sources. It provides explicit usage examples like 'Is it true that…', 'fact check', and distinguishes itself from sibling tools by focusing on factual claim verification.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It differentiates between company-financial claims (fast path via SEC EDGAR) and other claims (grounded pipeline). However, it does not explicitly state 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.