Idigbio

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint. Description adds: default model selection, need for _apiKey for Anthropic probes, score range 0-100, and return structure (per-model + combined). 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?

Two sentences, front-loaded with main action and output. No wasted words, covers purpose, behavior, and use cases efficiently.

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 4 parameters fully described, missing output schema compensated by description of return structure. Annotations provide safety profile. Sibling tools do not overlap significantly. Description is sufficient for effective invocation.

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

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

All parameters have schema descriptions (100% coverage). Description enriches semantics: explains scoring, default model, that _apiKey bypasses standard billing, and context helps disambiguate. 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?

Description states specific verb 'probe' and resource 'LLMs for visibility of an entity', with scoring scale. Clearly distinguishes from sibling tools like ask_pipeworx or bet_research by focusing on brand/product visibility across multiple LLMs.

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: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' Implicitly guides when to use by contrasting free default model and BYO key option. Lacks explicit when-not or direct comparison to 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 signal a safe, read-only, idempotent, non-destructive tool. The description adds meaningful behavior beyond that: it is a router that fills arguments, returns structured answers, and provides stable citation URIs, and it indirectly discloses that it may not guarantee an answer rate by directing 100%-answer-rate needs to ask_pipeworx_grounded. Minor missing details like failure modes or rate limits keep it just short of 5.

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 text is long but front-loaded with the strongest guidance ('PREFER OVER WEB SEARCH'), organized into use cases, examples, and sibling routing. The trailing section becomes garbled ('snapshots? base only... bet_research? maybe'), which prevents a 5.

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

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

With no output schema, the description properly explains the return value (structured answer with citation URIs). It covers supported domains, trigger language, example queries, and when to route to specific siblings, making it complete enough for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100% and the schema already explains that the parameter is a natural-language question with five aliases. The description's examples illustrate but do not add new parameter semantics; the baseline of 3 is appropriate.

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

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

The description states a clear, specific action: ask a factual question, route it across thousands of verified-source tools, fill arguments, and return a structured answer with pipeworx:// citations. It goes beyond a restatement and explicitly distinguishes itself from web search and sibling tools such as ask_pipeworx_grounded, ai_visibility_check, and deep_research.

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

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

It gives concrete when-to-use guidance ('PREFER OVER WEB SEARCH', 'START HERE for most questions'), lists trigger phrases and example questions, and names alternatives with their specific conditions (grounded for 100% answer rate/CoT, ai_visibility_check for token attribution, deep_research for generative tasks/tables/parallel fan-out, bet_research for enterprise SLA/premium sources). This is unusually rich routing guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds transparency by disclosing that no candidate is active right now and that results are compared against the stable router to decide merges, which is useful beta-context beyond the annotations.

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

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

The description is a single focused paragraph front-loaded with the beta relationship and the 'identical router' framing. No repetition of schema details beyond the alias mention, and the caveat about no active candidate is efficiently embedded.

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

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

For a tool with no output schema and a simple single-required-parameter interface, the description covers the key context: what it is, how it differs from the stable sibling, when it's currently identical, and what happens to results. It doesn't explain return shape, but the description explicitly states the response shape is identical to ask_pipeworx, which effectively covers that.

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 all six parameters. The description adds the alias usage note ('accepts query, q, prompt, text, input as aliases') but that's mostly repeating schema info, so it just meets the baseline without adding much new 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 that this is a beta version of ask_pipeworx with identical routing, arguments, and response shape, and explicitly names ask_pipeworx as the sibling it is equivalent to. It distinguishes itself by being the experimental candidate edge while clarifying that no candidate is currently active.

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 says to use it exactly like ask_pipeworx when you want the newest routing, though it doesn't explicitly discuss when not to use it or alternatives beyond noting the stable router. The guidance is clear enough for an agent to select between this and ask_pipeworx, but a more explicit when-not-to-use statement would strengthen it.

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description adds substantial behavioral context beyond them: the extraction constraint ('EXTRACTS the answer using ONLY what the tool result contains'), the exact success return shape with evidence as a verbatim quote, and the full refusal contract enumerating five refusal_reason values (not_in_source, no_tool_match, tool_error, data_truncated, llm_error). Since there is no output schema, this disclosure is essential and comprehensive. No contradiction with annotations exists.

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

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

The description is dense but every sentence earns its place: core value proposition, routing mechanism, success/refusal return contract, use-case guidance, and cost tradeoff. The key differentiator ('Hallucination-resistant') is front-loaded, and the refusal-reason enumeration is compact despite covering five distinct failure modes. No filler or redundancy.

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

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

For a single-free-text-parameter tool with no output schema, the description covers everything an agent needs: what the tool does, what it returns on success, what it returns on each failure class, when to prefer it, and its cost relative to the alternative. The annotations cover the safety profile, and the schema covers parameters, so no critical gap remains.

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

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

Schema description coverage is 100% — all six parameters (question and its five aliases) are documented in the schema, so the baseline of 3 applies. The description does not add parameter-level detail, but it does enrich the parameter's purpose by explaining what the tool does with the question (routing, filling arguments, fetching, extracting). This is adequate but not more than the baseline warrants.

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

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

The description opens with a specific mode and purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly distinguishes itself from siblings (ask_pipeworx, ask_pipeworx_beta) by its grounded-extraction mechanism and explicit refusal behavior, and names its sibling relation directly ('Same routing as ask_pipeworx'). An agent can tell exactly what this tool does and how it differs from its nearest alternatives.

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

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

The description gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' with concrete high-stakes examples. It also states when NOT to use it and names the alternative: 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups.' This is exemplary routing guidance with no inference required.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds extensive behavioral details: fan-out logic, classifiers, resolver contract (match confidence, alternatives, suggestions), parent event extractor, news fallback fields, safety short-circuits for low-confidence matches and closed markets, wide-spread tradeability warnings, and cancellation rule parsing. This fully discloses the tool's behavior 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 very long (over 600 words) and lacks formatting like bullet points or sections. It is front-loaded with a clear first sentence but contains redundant and overly detailed explanations. Brevity would improve usability for an agent scanning for 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 complexity (3 parameters, 100% schema coverage, no output schema, informative annotations), the description is thorough. It covers edge cases (low-confidence matches, closed markets, wide spreads), resolution rules, parent events, and news fallbacks. All critical behaviors for correct usage are documented.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds value by explaining the market parameter input formats (slug, URL, question), depth parameter options (quick vs thorough), and include_raw parameter impact on response size. This contextual information helps an agent choose appropriate parameter values.

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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types and output components. While very clear, it does not explicitly distinguish from sibling tools like polymarket_edges or polymarket_arbitrage, which could cause confusion for an agent.

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 for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This provides clear usage context. However, it does not mention when NOT to use this tool or list alternatives, leaving room for improvement.

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

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

Annotations already declare readOnly and idempotent, so the description adds valuable context: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs. It does not mention rate limits or data freshness delays, but overall adds meaningful behavioral traits.

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 despite its length, front-loaded with natural language examples and then structured details. Every sentence adds unique information: triggers, data sources, type-specific behavior, sorting, and efficiency gains. 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?

Given the tool's simplicity (2 parameters, no output schema), the description covers all essential aspects: what data is returned (paired data + citation URIs), how results are sorted, and the entities it supports. It is sufficiently complete for an AI agent to understand 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%, but the description greatly enriches parameter semantics: it explains what each type returns (company: latest 10-K metrics; drug: FAERS counts, FDA approvals, trials) and gives explicit examples for values (tickers/CIKs for company, drug names). This goes well beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: side-by-side comparison of 2-5 companies or drugs. It uses specific verbs and resources (compare entities, pulls financial data, adverse-event counts). It distinguishes itself from siblings by explicitly recommending over sequential single-pack lookups and noting it replaces many lookups.

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

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

The description provides explicit when-to-use guidance with natural language triggers (e.g., 'compare X and Y', 'which is bigger'). It strongly recommends this tool over sequential lookups for comparisons, implying when not to use (when not comparing multiple entities). This is clear and actionable.

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

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

Annotations already declare safe, non-destructive behavior (readOnlyHint, idempotentHint, destructiveHint=false). The description adds the context 'Keyless', suggesting no API key required, and specifies that scoping is optional. 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?

Two sentences efficiently convey purpose, scope, and key feature (optional filters). No wasted words; front-loaded with the core action.

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 count tool with good annotations, the description covers the main functionality. It mentions 'top values + counts', matching the top_count parameter. However, it does not describe the return format (e.g., JSON structure), which would improve completeness.

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 parameters described. The description adds no new parameter details beyond restating the grouping field and optional filters, so baseline 3 is appropriate.

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

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

The description clearly states the verb 'Get', the resource 'taxonomic/geographic specimen counts grouped by a field', and the scope 'across iDigBio'. It distinguishes itself from sibling tools like 'search_specimens' by focusing on counts rather than specimen records.

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 optional filters but does not explicitly guide when to use this tool versus alternatives. It implies usage for aggregated counts, but lacks explicit when-to-use or when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description goes well beyond these by disclosing account/paid-tier requirements, parallel decomposition, `gaps[]` for unanswered facets, a never-invented guarantee, fetchable citation URIs, semantic excerpting, contradiction scanning, and latency expectations. There is no contradiction with annotations.

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

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

The description is long but densely informative and front-loaded with the critical account caveat, then the value proposition, then return semantics, then latency. A few details repeat what the schema's `depth` description already states, but overall every sentence adds meaningful operational context.

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

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

Despite no output schema, the description fully covers what the agent will receive: findings packet, evidence, confidence, source, fetched_at, citation URIs, gaps, contradictions, and excerpting behavior. Auth requirements, latency, and alternatives are all addressed, making the tool safe and practical to invoke.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds practical nuance beyond the schema: question accepts natural-language broad/multi-part queries, depth behaviors are tied to paid tiers, and the trade-offs between quick/standard/thorough are reinforced with concrete operational 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 uses a specific verb and resource: "Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources" in ONE call. It also explicitly distinguishes itself from open-web search and from ask_pipeworx, making its scope unambiguous.

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

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

Usage guidance is explicit: "If you are not signed in, use ask_pipeworx instead," "Best for broad/multi-part questions," and "For a single lookup use ask_pipeworx instead." This clearly tells an agent when to select this tool versus its sibling alternatives.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds context about what the tool returns (top-N relevant tools with schemas) and that results are 'ready to call directly.' No contradictions; description adds moderate 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?

The description is information-dense without redundancy. It starts with the core action, lists domains, explains output, and ends with usage guidance. Every sentence serves a purpose and is well-structured.

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

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

Despite no output schema, the description details what the tool returns (names, descriptions, schemas). It addresses the 6 parameters (mostly aliases) and provides examples. The tool's behavior is fully described for its discovery role.

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

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

Schema coverage is 100% with descriptions for all parameters. The description reinforces that query accepts natural language and gives examples. It also clarifies that multiple aliases are accepted, adding meaning beyond the schema.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists many example domains and explains that it returns tool names, descriptions, and full input schemas. This distinguishes it from siblings which are specialized tools.

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

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

The description explicitly advises: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear when-to-use guidance, implying not to use when you already know the specific 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?

With annotations already covering the read-only/idempotent/open-world safety profile, the description adds substantial behavioral context far beyond those flags: parallel fan-out, soft-fail on the sunset USPTO API, expected-empty fda_products for small-molecule-only companies, GDELT→GNews fallback, and the crucial caveat that 'an empty section is a real no-data, not a bug.' These traits materially change how an agent should interpret results and are not visible anywhere in the structured fields.

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, but it front-loads trigger examples and the core purpose before the source enumeration, and nearly every clause carries behavioral or edge-case information. It loses a point for restating parameter shapes already covered by the schema and for the seven near-duplicate trigger paraphrases ('brief me on Tesla' vs 'what does Apple do') that could be trimmed without information loss.

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?

Because there is no output schema, the description carries the full return contract — and it does so thoroughly, enumerating every response section (cik, recent_filings with pipeworx URIs, LATEST 10-K fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI) and explaining empty-vs-failed semantics. Input formats, name resolution, private-company handling, soft-fail chains, and expected-empty cases are all covered, leaving no critical gap for a tool of this complexity.

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

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

Schema description coverage is 100%, and the schema already documents that both enum values behave identically and that value accepts a ticker, CIK, or company name with SEC EDGAR name-resolution. The description mostly restates these facts using the same examples (AAPL, 0000320193, Moderna), so the high-coverage baseline of 3 applies; the only incremental content (resolved_from/resolved_to) describes return behavior, not parameter semantics.

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

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

The description states a specific verb and resource: 'full cross-source profile of a US public company in ONE parallel call,' and enumerates the precise sources it fans out across (SEC EDGAR, XBRL, USPTO, USAspending, FDA Purple Book, DOL LCA, news, GLEIF). The trigger examples ('Tell me about X', 'research Acme', 'company profile for Microsoft') plus the explicit 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' clearly distinguish it from sibling single-source 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?

'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' is an explicit when-to-use rule that names the concrete alternative. It also sets expectations for edge cases — 'a private company (no CIK/ticker) returns resolved:false with an explicit notes line, not a bare failure' — so an agent does not misroute or misreport partial coverage.

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 destructiveHint=true and idempotentHint=true, so the description's mention of 'delete' aligns. The description adds context about clearing sensitive data but does not reveal additional behavioral details beyond the annotations.

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

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

The description is concise with two sentences, no wasted words. It is front-loaded with the core action and provides usage guidance efficiently.

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

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

Given the tool's simplicity (one parameter, no output schema), the description is complete: it explains the action, when to use, and how it relates to sibling tools. 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 a clear description for the 'key' parameter ('Memory key to delete'). The description does not add extra meaning beyond what the schema provides, so a baseline of 3 is appropriate.

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

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

The description clearly states the action ('Delete') and the resource ('previously stored memory by key'). It also distinguishes itself from siblings by mentioning pairing with '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?

The description explicitly states when to use the tool: when context is stale, task is done, or to clear sensitive data. It also references sibling tools ('Pair with remember and recall'), providing clear 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?

The description details the process (fetch page, extract title/description/key links, output markdown) and deployment suggestion, significantly enriching beyond the annotations that declare read-only, idempotent, and non-destructive.

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

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

Three sentences, each serving a distinct purpose: main function, process details, use cases. Front-loaded and 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?

For a simple tool with full schema coverage and annotations, the description adequately explains output format and deployment, with no gaps in context.

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

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

Schema coverage is 100%, and the description largely restates schema info (url, max_links default/max). No additional semantic value beyond what the schema provides, meeting baseline expectation.

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 generates an llms.txt file for any URL, specifying verb and resource. Among sibling tools, none perform this function, so it is clearly distinguished.

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?

Use cases are provided (indexing client sites, drafting for own project, auditing competitors), giving clear when-to-use context. However, no explicit exclusions or alternative tool references.

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. Description adds context that it returns a 'full normalized record' and provides an example, but does not significantly extend beyond annotations.

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

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

Two sentences, no wasted words. First sentence states core purpose. Second provides example and key attribute. Efficient and front-loaded.

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

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

For a simple retrieval tool with one parameter and no output schema, the description covers purpose, gives an example, and mentions keyless access. It omits return format but annotations provide safety and idempotency info. Reasonably 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 covers the uuid parameter with 100% description coverage. Description adds an example of a uuid and the note 'Keyless', but this does not add substantial meaning beyond the schema for parameter usage.

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

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

Description clearly states 'Get the full normalized record for a single iDigBio specimen by its uuid', providing a specific verb and resource. It distinguishes from sibling tool 'search_specimens' which returns multiple specimens.

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 implies usage for a single specimen by uuid but does not explicitly guide when to use this tool versus alternatives like 'search_specimens'. No exclusions or when-not-to-use guidance provided.

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

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

Annotations already declare readOnlyHint, destructiveHint, idempotentHint. Description adds the return structure and default scope (active subscriptions), which aligns with annotations.

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

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

Two sentences: first states purpose and outputs, second gives usage guidance. No wasted words, front-loaded efficiently.

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

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

For a simple list tool with one optional parameter and no output schema, the description fully covers purpose, return fields, and usage context.

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

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

Schema coverage is 100% and describes the 'include_inactive' parameter. Description implicitly indicates default (active only) but adds no new parameter details 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?

Clearly states it lists the caller's active subscriptions and enumerates return fields (id, type, etc.), differentiating from siblings like subscribe/unsubscribe.

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

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

Explicitly advises use for reviewing subscriptions before adding more or finding an id to cancel, providing clear context for invocation.

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 annotations only show all false hints, contributing little, so the description carries the transparency burden. It discloses the claim_token flow for follow-up, daily digest reading, the 5-per-day rate limit, and that it's free with no quota impact. These are important operational behaviors an agent needs to know before invoking.

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

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

The description is long but well-structured, with each sentence adding a distinct piece of information: purpose, triggers, exclusion, token mechanics, rate limit, and cost. It's appropriately front-loaded with the core action. While every sentence earns its place, the length is slightly higher than the minimum needed, so a 4 is appropriate.

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

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

With no output schema and minimal annotation information, the description carries the full burden—and it does so thoroughly. It covers what, when, when-not, how (including the token flow), and operational constraints like rate limits and cost. An agent has all the information needed to decide whether and how to use this tool.

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

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

The input schema provides 100% coverage of parameter meanings, so the baseline is 3. The description adds valuable nuance: telling users to describe issues in terms of Pipeworx tools/packs rather than pasting end-user prompts, and demonstrating the claim_token syntax for retrieving earlier feedback results. This goes beyond the schema's field 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 opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist'—a specific verb and target, immediately clarifying the tool's purpose. It clearly distinguishes itself from sibling tools like ask_pipeworx, discover_tools, and other research-oriented tools by being the dedicated reporting channel for issues with Pipeworx 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?

Explicitly states when to use: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides a precise exclusion: feedback about tools from other MCP servers should be filed there, not here. This is clear when/when-not guidance with named alternatives.

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

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

Discloses data source (CF analytics-engine), privacy (no PII), and caching behavior (5min-1h depending on window). Annotations already cover hint, but description adds valuable behavioral context beyond annotations.

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

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

Front-loaded with main purpose, then bulleted uses, then technical details. Every sentence adds value, no waste.

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

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

Given the simple tool (1 param, no output schema, rich annotations), the description covers purpose, usage, transparency, and parameter semantics completely.

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

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

Schema coverage is 100% with a single parameter (window) that has enum and description. Description adds nuance: short vs long windows surface different trends, but schema already documents it well.

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

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

The description clearly states it returns top tools, packs, and call volume over a recent window, using specific verbs and resource. It distinguishes from siblings like 'discover_tools' and 'ask_pipeworx' by focusing on what other agents are calling.

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 with bullet points (discovering hot data, confirming canonical choice, seeing alignment). Does not explicitly state when not to use, but the context is clear.

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

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

The description adds extensive behavioral details beyond annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint). It explains monotonicity checks, partition-sum checks, semantic anchor with Jaccard similarity, partition filter with placeholder slugs, fill check against live CLOB depth, and conditions for null signals. 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 long but well-structured, starting with the main purpose then detailing modes, semantics, and response format. Every sentence adds value, though it could be slightly more concise without losing information. It effectively front-loads the key action.

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

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

Despite lacking an output schema, the description fully explains the response structure: opportunities[] with fields (gap_pp, suggested_trade, reasoning, monotonicity violation context) and event-mode partition_check. It also details fill_check outputs. For a complex tool, this is exceptionally 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%, but the description adds significant meaning: for 'event' it explains walking child markets and checking date-axis/threshold-axis ordering; for 'topic' it explains cross-event scanning and structural patterns. It also clarifies that URLs are accepted for event slugs.

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: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It uses specific verbs (find, call, pass) and distinguishes between modes (no args, event, topic), making it distinct from sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

Explicit guidance on when to use each mode: 'Call with NO args for a trending_scan; pass event for the strongest per-event partition_check; topic for cross-event scan.' It also recommends event mode for specific markets, and advises against trading when realizable_edge_pp ≤ 0. It points to polymarket_fill_risk for custom sizing.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds substantial context: caching at KV level for 1h, diagnostics to explain empty segments, fed_candidates caveat, and detailed edge computation methodology (e.g., 24h-move warning). This goes well 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 long but well-structured with clear sections (segments, response structure, diagnostics). Every sentence adds detail, but it could be more concise for an AI agent. The front-loading is good with the opening sentence stating core purpose.

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

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

Given the tool's complexity (9 parameters, no output schema, nested objects), the description is exceptionally complete. It explains each segment's methodology, response top-level, diagnostics, caching, and caveats like fed candidates. The rationale for missing fields (e.g., partition leg kelly) is also covered.

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 have schema descriptions (100% coverage). The tool description adds value by grouping knobs like 'TRADEABLE-EDGE KNOBS' and explaining their interplay (e.g., min_partition_leg_kelly for partition arbs). This contextualizes parameters beyond standalone schema descriptions.

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

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

Clearly states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It distinguishes its purpose with 'Built for what should I bet on today' and avoids paging. The three model segments are described, making it very specific and distinct from sibling tools.

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

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

The description implies use for discovering betting opportunities but does not explicitly state when not to use it or provide alternatives. While siblings exist (e.g., polymarket_arbitrage, polymarket_edge_tracker), no guidance on choosing between them is given.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds rich behavioral details: explains response structure (tracked[], expired[], snapshot_dates[]), sign convention for edge_pp_net, and limitations (daily closes, not intraday, bounded by TTL). 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 thorough but somewhat verbose, including detailed response field explanations. It is front-loaded with the purpose, but some details (like sign convention) could be omitted if output schema existed. Still, it remains readable and organized.

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

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

Given no output schema, the description fully covers return values (tracked, expired, snapshot_dates) and handles edge cases like missing data. It provides all necessary behavioral and structural context for correct tool invocation.

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

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

Schema coverage is 100% with both parameters described. The description adds practical context: default values (days=14, window='1wk') and clamp info (days max 30). While not extensive, it enhances understanding beyond the schema alone.

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

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

The description clearly states the tool's purpose: to answer 'how long has this edge existed and is it shrinking?' It specifies the verb (track edge persistence and decay) and the resource (daily polymarket_edges snapshots). The tool is distinguished from siblings like polymarket_edges by being a derivative analysis tool.

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

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

The description provides context for when to use (checking edge persistence) and limits (60-day TTL, daily closes). It does not explicitly list when not to use or compare to alternatives, but the purpose is clear enough to guide 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?

Annotations indicate read-only, open-world, idempotent, non-destructive. The description adds detailed behavioral context: walks the order book ladder, returns verdicts (clean|degraded|cannot_fill), and warns about forced directional risk. 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 structured with bold headers for modes, but it is somewhat lengthy. However, every sentence adds value; minor reduction could improve conciseness without losing clarity.

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

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

No output schema is provided, but the description thoroughly lists return fields for both modes, including edge cases like thin_legs and forced_directional_risk. It explains the risk of partial basket fills, making the output expectation clear.

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 four parameters have 100% schema coverage, but the description adds significant meaning: explains size_usd interpretation for buys vs sells and basket mode (settlement notional), side defaults and auto-detection in basket mode, and market/event distinction. The description provides context 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 as a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes two modes (single-market and basket). It differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by indicating this tool is a prerequisite check.

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

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

Explicitly advises when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains the rationale (theoretical overround not capturable on thin books, partial fills converting arb to directional risk).

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?

Even though annotations already declare readOnlyHint and idempotentHint, the description goes far beyond them: it discloses the token-overlap matching mechanism, the absence of a shared resolution source, the gross-vs-net fee treatment, the non-equivalence/null semantics of temporal fields, and explicit warnings about unclassified legs never being paired. No behavioral trait is hidden.

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

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

The description is long and dense, but almost every sentence carries a needed warning or clarification for a complex cross-venue matching tool. It is well-structured with bolded mode labels and clear sections. There is minor redundancy around temporal alignment ('NOT the same as confirmed-aligned' is emphasized multiple times), which is defensible given the nuance but still slightly repetitive.

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

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

With no output schema and rich runtime behavior, the description carries a heavy burden and succeeds: it explains the return shape, the safety fields, all compatibility codes, the skipping rules for unclassified legs, the meaning of null temporal alignment, fees, and skipped comparison counters. An agent has enough context to invoke and interpret the tool correctly in both modes.

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

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

Schema coverage is 100%, so the baseline is 3; however, the description adds meaningful semantics: it explains that topics are '10 pre-mapped macro shortcuts' that auto-fetch matching events, that explicit tickers override the mapped side, and that both modes run the identical matcher. This goes beyond the schema's simple type/description fields.

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

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

The description opens with a precise definition: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This names the resource (two venues), the action (computing a spread), and the key qualifying condition (same resolving question), making the tool's purpose unambiguous and clearly distinct from the sibling arbitrage tools.

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

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

The description explicitly defines TWO MODES and explains when to use each: the `topic` shortcuts for pre-mapped macro events and explicit `kalshi_event_ticker` + `polymarket_event_slug` for custom pairings. It also warns that pre-mapped topics are not necessarily tradeable and that most return compatibility warnings today. It does not explicitly contrast this tool with sibling tools like polymarket_arbitrage, so it falls just short of a perfect usage-guideline score.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. Description adds context about listing all keys by omitting argument, scoping, and pairing with remember/forget, exceeding annotation coverage.

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 main action, every sentence adds value. No redundancy or waste.

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

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

Fully covers purpose, usage, scoping, and pairing. No output schema needed, annotations handle safety. Complete for a simple 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 coverage is 100% with a clear description for the key parameter. Description adds usage details and examples, providing additional meaning beyond the schema.

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

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

The description clearly states the verb (retrieve/list) and resource (saved values/keys). It distinguishes from sibling tools 'remember' and 'forget' by explicitly pairing with them.

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

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

Explicitly states when to use ('to look up context the agent stored earlier') and when not to ('without re-deriving it from scratch'). Provides examples and notes scoping per identifier.

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

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

Annotations (readOnlyHint, idempotentHint, openWorldHint, destructiveHint false) already indicate safe, read-only behavior. The description adds critical context: mark_read affects future calls, polling works fine, and events carry specific fields. No contradictions.

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

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

Four sentences, front-loaded with purpose, no redundancy. Every sentence adds new information (purpose, fields, filters, mark_read behavior, alternative access). Highly efficient.

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

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

For a read-only, non-destructive tool with no output schema, the description adequately explains return fields, filtering, state management, and alternative access. No gaps identified given the tool's simplicity.

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

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

Schema coverage is 100%, but the description adds value beyond schema by providing example type ('sec_8k'), clarifying mark_read's effect on subsequent calls, and emphasizing ISO timestamp format for since. Slight room for more parameter elaboration (e.g., limit range mentioned in schema but not description).

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

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

The description starts with 'Pull fired events from your subscription feed,' clearly stating the action and resource. It specifies returned fields (source, citation_uri, raw payload) and distinguishes from sibling tools like list_subscriptions (subscription management vs. event retrieval).

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

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

Explicit guidance on filtering by type and since, setting mark_read to manage read state, and noting that the same feed is available via HTTP for scripts/dashboards. This provides clear when-to-use and alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds useful behavioral details: fans out in one parallel call, fallback from GDELT to GNews, USPTO soft-fail until May 2025, and return structure with grouped changes and citations.

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

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

Description is well-structured, starting with example queries, then sources, parameter hints, and sibling comparison. It is slightly verbose but every sentence contributes necessary detail, earning its place.

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

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

Given no output schema, the description explains the return format (changes[], total_changes, citation URIs) and covers multiple data sources with fallback behavior. It is fairly complete for a complex aggregation tool, though it omits mention of pagination or date range limits.

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

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

Schema coverage is 100%, so baseline 3. The description adds value by explaining the 'since' parameter accepts ISO dates and relative shorthand with examples (e.g., '7d', '3m'), and clarifies 'value' can be ticker or CIK. It also recommends typical values for monitoring.

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

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

The description clearly states the tool provides a change feed for a company over a recent time window, listing specific data sources (SEC EDGAR, GDELT→GNews, USPTO). It distinguishes from the sibling tool 'entity_profile' by noting entity_profile is for static profiles without a time window.

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 example queries like 'what's new with X' and explicitly recommends using 'entity_profile' for static profiles, giving clear context for when to use this tool. However, it does not exhaustively list when not to use it versus other tools like 'deep_research'.

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

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

Beyond annotations (idempotentHint, etc.), description adds valuable behavioral context: scoped by identifier, 24-hour retention for anonymous sessions, persistent for authenticated users. 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?

Three sentences with front-loaded purpose, followed by usage and behavioral details. Every sentence adds value; no waste.

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

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

For a simple key-value write tool with 2 parameters and no output schema, the description covers purpose, usage, storage model, and persistence. Paired sibling tools are mentioned, making the context 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 already provides examples. The description reinforces but does not add meaningful new information beyond what the schema offers. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later.' It provides specific examples (resolved ticker, target address, etc.) and distinguishes from sibling tools by naming recall and forget.

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

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

Explicitly says when to use: 'when you discover something worth carrying forward.' Also gives guidance on pairing with recall and forget, and describes persistence differences (authenticated vs anonymous sessions), providing clear context for selection.

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

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

Annotations already mark the tool read-only/idempotent, and the description adds substantial context: source-labelled identifiers, an explicit `unresolved` field, graceful degradation when GLEIF/OpenFIGI are unavailable, internal cascading lookups, and drug output fields. 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 examples and the 'Use FIRST' rule, and nearly every clause adds useful information. However, the company support parenthetical is long and heavily nested, which makes it harder to parse than necessary.

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

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

There is no output schema, so the description carries the burden of explaining return values; it enumerates identifiers by source, the `unresolved` field, graceful degradation behavior, and accepted input forms. An agent has enough information to select and invoke this tool correctly.

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

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

The input schema already describes both parameters at 100% coverage, but the description adds critical conventions: accepted ticker/CIK/ISIN/name formats, drug brand/generic inputs, and the warning to pass the issuer exactly as printed rather than the full noun phrase. This meaningfully reduces misuse.

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

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

The description opens with concrete user phrasings and clearly states the verb+resource: resolve a name to canonical identifiers. It also distinguishes the tool from downstream siblings by noting these identifiers are what 'other tools require as input' and instructs 'Use FIRST whenever you have a name but need an ID.'

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

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

It gives an explicit trigger condition ('Use FIRST whenever you have a name but need an ID') and illustrates with example queries. It covers edge cases like non-equity bonds and ISINs, but it does not name specific alternatives or 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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, but the description adds transparency by explaining internal mechanism (calls ai_visibility_check), ranking logic, and output fields (score, confidence, signal density). No contradictions.

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

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

Three sentences: first states purpose, second explains mechanism, third gives example use case. Every sentence is essential and front-loaded. No fluff.

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

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

The description covers purpose, behavior, parameters, and output (ranked list with score/confidence/signal density). Despite no output schema, it fully describes return structure. For a read-only comparison tool with 4 parameters, this is complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds minimal extra semantics: it notes the first entity is treated as 'subject' and context disambiguates names, but this is already implied by the parameter descriptions. No major value added 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 it compares AI visibility across multiple entities, ranks them, and surfaces which is most/least recognized. It uses specific verbs like 'probes', 'ranks', 'surfaces' and distinguishes itself from sibling tools like ai_visibility_check (single entity) and compare_entities (generic).

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

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

The description provides a concrete use case (competitive AI-marketing audits) and implicitly distinguishes from ai_visibility_check by focusing on multiple entities. However, it lacks explicit when-not-to-use guidance or comparison to other sibling tools like compare_entities.

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

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

The description adds significant behavioral context beyond the annotations: it explains fan-out to two external services, mentions potential slow first measurement for bundlephobia (5-30s) and graceful degradation via 'sources_failed'. This is especially valuable as the agent needs to set expectations for latency and partial results.

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, front-loading the core purpose and then detailing components. It is relatively concise for the amount of information (purpose, components, usage, ecosystem, edge cases). A slight improvement could be using bullet points for the return fields, but it remains effective.

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

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

Despite no output schema, the description enumerates all return fields (summary block fields, per-advisory, links, alternative versions) and covers edge cases (partial failures, timeout behavior). It also clarifies ecosystem limitations and boundaries, making the tool self-contained for the agent.

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

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

Schema coverage is 100% with detailed descriptions for both parameters. The description adds minor extra context (e.g., 'Scoped packages are accepted') but does not substantially enhance the parameter understanding beyond the input schema. Baseline of 3 is appropriate given high schema coverage.

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

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

The description clearly states it is a composite check for adding an npm package, specifying it fans out across deps.dev and bundlephobia. It directly addresses the user's question 'should I add this npm package', which distinguishes it from sister tools like 'scan_competitor_ai_presence' or 'validate_claim'.

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

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

Explicit usage guidance is provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also limits scope to 'NPM ecosystem only in v1' and mentions alternatives for other ecosystems, helping the agent decide when not to use this tool.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive hints. The description adds context: it is keyless (no auth), searches a large dataset (~150M), and requires at least one filter. No contradictions.

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

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

Two sentences with high information density: first sentence covers purpose and scope, second covers filters and constraint. No wasted words, well 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?

For a search tool with no output schema, the description covers key behaviors: data source, size, required filters, and keyless access. Lacks details on pagination beyond limit, but examples in schema help. Minor gap prevents a 5.

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 each parameter. The description groups parameters into taxonomy and locality categories, adding slight semantic value, but mostly reiterates filtering capability. 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 searches ~150M natural-history museum specimen records from US collections via iDigBio, using a specific verb ('Search') and resource. It distinguishes from sibling tools like 'get_specimen' by focusing on multiple records and taxonomic/locality filtering.

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 requires at least one filter, guiding appropriate usage. It implies use for filtered batch queries but does not explicitly state when not to use or name alternatives, though siblings provide clear contrast.

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 significant behavioral details: internal algorithm (BGE-base-en embeddings + cosine), window size (500-char overlapping), and a character cap (200K chars) with truncation behavior. No contradiction exists.

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

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

The description is four sentences, each serving a distinct purpose: core action, usage context, pairing suggestion, and technical detail. No wasted words; the structure is logical and front-loaded with the most important 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?

Despite lacking an output schema, the description adequately covers return values (top-N passages with offsets and scores). It explains internal algorithm, limits, and pairs well with sibling tools. For a 3-parameter tool, it provides all necessary context for an agent to use 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?

Schema description coverage is 100%, so the baseline is 3. The description adds value by providing examples for the query parameter ('e.g. supply-chain risk, fiscal year 2024 revenue') and explaining the text parameter's truncation behavior. This exceeds the baseline but doesn't add entirely new 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: 'Semantic search INSIDE a fetched record.' It uses strong verbs and provides concrete examples (SEC 10-K, article, long tool result), effectively differentiating it from siblings like '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?

The description explicitly states when to use the tool: 'Use when the record is too big to cram into the prompt.' It highlights the benefit of saving context and mentions pairing with another tool. However, it lacks explicit 'when not to use' guidance, which would strengthen the score.

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

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

Adds rich behavioral details beyond annotations: OAuth requirement, subscription ID return, type-specific filters, delivery channels, SMS cap, webhook signing and auto-disable. Annotations state idempotentHint=true, destructiveHint=false, which align. 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?

Single paragraph that is dense but well-organized: purpose, requirement, types, delivery options. Every sentence adds unique information. No filler or repetition. Front-loaded with key action and return value.

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

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

For a 3-param tool with no output schema, description covers: return type (subscription id), all type-specific params with examples, delivery constraints (verification, rate limits, webhook signing secret), and failure behavior (auto-disable). No gaps for agent to guess.

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% (3 params fully described in schema). Description adds significant value: explains type enum values with practical examples (e.g., 'items:["5.02"] = officer change'), details params objects for each type, and elaborates delivery options with verification requirements. Goes well beyond the schema.

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

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

Description starts with a clear verb+resource: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This distinguishes it from siblings like list_subscriptions (listing) and unsubscribe (removal).

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 prerequisite: 'Requires a Pipeworx OAuth account'. Covers when to use each subscription type with concrete examples. Specifies default feed delivery and optional email/SMS with constraints (verification, cap). No ambiguity about 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, destructiveHint. Description adds concrete behavioral details: returns category-bucketed questions each with exact tool+argument shape, and lists categories. No contradictions.

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

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

Description is relatively long but packs essential information. It front-loads the question phrase and lists categories efficiently. Some redundancy could be trimmed, 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 no output schema, the description fully explains the return format (category-bucketed example questions with tool+argument shapes). It is complete for an onboarding tool, covering purpose, usage, and output.

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

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

Schema coverage is 100% but description adds value by explaining the topic parameter's possible values and behavior when omitted. It provides real-world usage context beyond the schema.

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

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

Description clearly states the tool returns category-bucketed example questions for Pipeworx, serving as an onboarding entry point. It lists specific categories and provides a clear verb ('returns') and resource ('example questions').

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains how to call with or without the topic argument. Does not explicitly list when not to use, but context strongly implies 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 beyond annotations: row is deactivated not deleted, preserving historical events. Consistent with idempotentHint=true and destructiveHint=false.

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, no redundant content, front-loaded with purpose.

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

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

For a simple 1-param tool with no output schema, covers purpose, side effects, and constraints fully.

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

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

Schema coverage 100% with existing description. Description adds no extra meaning beyond 'by id'.

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 cancels a subscription by id, with specific verb 'cancel' and resource 'subscription'. Differentiates from siblings like 'subscribe' and 'list_subscriptions'.

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

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

Explicitly mentions ownership enforcement ('you can only cancel your own subscriptions'), guiding when to use. Lacks explicit when-not-to-use or alternatives, but constraint 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/openWorld/idempotent/non-destructive, and the description adds substantial context beyond that: it enumerates all possible verdicts, explicitly warns that could_not_verify means the check did not happen and must not be treated as evidence, and distinguishes unsupported from could_not_verify. This is exactly the kind of behavioral depth an agent needs, and it doesn't contradict any annotation.

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 trigger phrases and purpose, then systematically covers routing, outputs, and a critical caller warning. Every sentence adds distinct information, and the length is justified by the tool's complexity. However, it is quite long, and the final sentence about replacing 4–6 calls is persuasive rather than essential, so it doesn't reach a 5.

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

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

Given the tool's simple schema and lack of output schema, the description carries the full burden—and succeeds. It explains when to use, how routing works, what verdict values to expect, the exact meaning of could_not_verify and unsupported, and that responses include a citation. It also notes the limitation to public US companies for the financial path. The only tiny gap is not defining 'inconclusive', but that doesn't hinder an agent's basic usage.

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

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

The schema already covers both `claim` and `tolerance_pct` at 100% coverage, setting a baseline of 3. The description adds valuable semantics by giving concrete claim examples and explaining that tolerance_pct overrides the claim's implied tolerance, capping at 5 unless explicitly set. This extra operational guidance lifts it above the baseline.

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

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

The description opens with specific trigger phrases ('Is it true that…', 'fact check', 'verify the claim that…') and states a clear verb+resource: natural-language claim verification against authoritative sources. It distinguishes itself from sibling tools by describing a verdict-producing pipeline and a structured SEC EDGAR path for financial claims, making it unambiguous when this tool is the right choice.

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

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

It explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct' and further clarifies the automatic routing between SEC financial claims and grounded-pipeline claims. It also notes that it replaces 4–6 sequential calls. However, it doesn't formally name alternatives or exclusion scenarios, so it stops short of a 5.

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