Inaturalist

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

Annotations already mark the tool as readOnly, openWorld, idempotent, and non-destructive. The description adds important context: default model, optional Anthropic with BYO key and direct payment, and the return structure (per-model {score, confidence, signals, raw_response} + combined view). No contradictions with annotations.

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

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

The entire description is concise, front-loaded with the core action and scoring, then adds secondary details (default model, apiKey, returns) in a logical order. Every sentence serves a purpose with no wasted words.

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

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

Given the tool has 4 parameters with full schema coverage, no output schema, and moderate complexity, the description fully covers usage, model options, key handling, return format, and example use cases. It leaves no major gaps for an agent to infer.

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

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

Schema coverage is 100%, and the description adds value beyond the schema by explaining the default model (Workers AI Llama-3.3-70b, free), the condition for _apiKey, and the disambiguation purpose of 'context'. This enriches understanding without redundancy.

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

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

The description clearly states the action ('probe', 'score'), the resource ('LLMs'), and the scope ('business / brand / product / topic'), with specific scoring range (0-100). It also distinguishes the tool by listing use cases like AI-marketing audits and pre-launch checks, differentiating it from sibling tools such as scan_competitor_ai_presence.

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

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

The description provides clear use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to use the optional _apiKey. However, it does not explicitly state when not to use this tool or directly compare to siblings like compare_entities or 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?

The annotations already cover readOnlyHint, idempotentHint, openWorldHint, and destructiveHint, so the description doesn't need to restate those. It adds useful behavioral context beyond the annotations: the request is routed to one of many tools, arguments are filled automatically, and answers include stable citation URIs. It stops short of disclosing failure modes or limitations, so it is not a full 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 description is front-loaded with the most important steering information ('PREFER OVER WEB SEARCH') and flows from scope to examples to alternatives. It is somewhat long, and the ai_visibility_check sentence feels out of place, but nearly every sentence carries routing value, making it appropriately sized for a broad router tool.

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

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

For a tool with one required parameter and no output schema, the description provides enough to call it correctly: when to use it, what kinds of questions it handles, examples, and what the response looks like ('structured answer with stable pipeworx:// citation URIs'). It covers the missing output schema well enough and explains the tool's role among siblings.

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

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

Schema description coverage is 100%: the question parameter is already documented as a natural-language request, and all aliases (q, query, prompt, text, input) are explained in the schema. The description's examples reinforce this but do not add new parameter-level meaning, so the baseline of 3 applies.

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

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

The description names a specific action: 'Routes the question to the right one of 5,798 tools across 1517 verified sources, fills arguments, returns the structured answer with stable pipeworx:// citation URIs.' It also distinguishes this tool from siblings by telling the agent to prefer it over web search and by naming ask_pipeworx_grounded, deep_research, and bet_research as alternatives. This is far more than a restatement of the title.

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

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

It gives explicit when-to-use triggers such as 'Use whenever the user asks "what is", "look up", "find", "get the latest"...' and provides concrete examples. It also gives when-not-to-use guidance with alternatives: grounded answers use ask_pipeworx_grounded, analytical depth uses deep_research, and live-markets-only questions use bet_research. The guidance is dense but explicit rather than implied.

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

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

Beyond the annotations, the description reveals the beta status, the live candidate-testing behavior, the fact that no candidate is currently active, and that this is a fully working router rather than a fallback or stub. This is precisely the kind of behavioral context annotations cannot convey.

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

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

The description is front-loaded with the core identity and then gives current status, usage, and fallback behavior. There is minor redundancy between 'currently matches ask_pipeworx exactly' and 'use it exactly like ask_pipeworx,' but overall every sentence earns its place.

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

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

Given the annotations, schema, and role as a beta router, the description covers what the tool is, when to use it, its current live-candidate state, and its fallback behavior. An agent has everything needed to invoke it correctly and understand what to expect.

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

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

The schema already provides 100% coverage for all six parameters, documenting question and its five aliases. The description adds no parameter-specific detail, but the schema carries the full burden, so the baseline score of 3 is appropriate.

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

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

The description clearly identifies this as the beta variant of ask_pipeworx, a universal router with the same tools, arguments, and response shape. It explicitly differentiates it from the stable ask_pipeworx sibling while stating exactly what the tool does. There is no ambiguity about its role as the experimental routing edge.

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 states when to use it: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains the current operational state — no candidate active, so it matches stable exactly — and that results are compared against the stable router. This gives clear, actionable guidance for selecting it over siblings.

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

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

The description adds substantial behavioral context beyond the readOnly/openWorld/idempotent annotations: exact success and refusal return shapes, the enumerated refusal reasons, and the cost penalty of one extra LLM call. No annotations are contradicted.

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 definition opens with the core value proposition and packs routing, extraction behavior, return/refusal contracts, use cases, and cost tradeoff into three dense sentences. Every sentence contributes decision-relevant information and nothing is wasted.

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

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

Despite having no output schema, the description fully specifies both the success and refusal return contracts, making expected behavior clear on every path. Combined with the input schema and annotations, an agent has everything needed 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?

Schema description coverage is 100%, so the input schema fully documents the question parameter and its aliases. The description adds no parameter-level meaning, which is acceptable at the baseline-3 level because the schema carries that burden.

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?

States a distinct purpose: a hallucination-resistant answer mode that extracts the answer using ONLY what the tool result contains, and explicitly contrasts it with ask_pipeworx. The description makes the tool's specific role and differentiation from its sibling immediately clear.

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

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

Provides explicit when-to-use guidance: whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts. It also names concrete high-stakes domains and directs users to prefer ask_pipeworx for casual lookups, giving both inclusion and exclusion criteria.

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

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

The description extensively covers behavior beyond annotations, including fan-out examples, response shapes, resolver contract, parent_event extractor, news fallback mechanics, safety short-circuits for low-confidence or closed markets, tradeability warnings, and resolution-rule risk. Annotations declare readOnlyHint/openWorldHint/idempotentHint, which align with the description's emphasis on safe, non-destructive research.

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 excessively long (multiple paragraphs) and lacks clear structure. Critical information like usage guidelines appears only after detailed fan-out examples. While comprehensive, it violates conciseness: not every sentence earns its place, and key points could be front-loaded more effectively.

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

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

Despite having no output schema, the description compensates by detailing response shapes (result.market, result.analysis, result.evidence), resolver contract fields, parent_event extractor, and various edge cases (low-confidence, closed markets, wide spreads, cancellation rules). This provides sufficient context for an AI agent to understand tool behavior and parse responses correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant value by explaining input types (slug, URL, question text), the depth parameter's effect (quick vs thorough), and include_raw's impact on response size. It also provides examples and elaborates on the market field's flexibility.

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 the verb (research), resource (Polymarket bet), and outcome (evidence packet + comparison). This distinguishes it from sibling tools like polymarket_edges 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?

The description provides explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also explains market input formats. However, it could more explicitly state when to use alternative tools (e.g., polymarket_edges for pure edge iteration).

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds rich behavioral details: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and return of citation URIs. No contradictions found.

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

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

The description is front-loaded with examples and is relatively concise given the complexity. Every sentence adds information, though it could be slightly tighter. Rewards for clarity outweigh minor verbosity.

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 outlines the return format (paired data plus citation URIs) and covers key behaviors (sorting, data sources). It does not discuss error cases or rate limits, but those are minor omissions for a tool with clear annotations.

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

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

Schema coverage is 100%, so the schema already defines parameters. The description adds value by explaining the meaning of each 'type' value ('company' pulls financials, 'drug' pulls FAERS data) and clarifying that 'values' expects tickers/CIKs for companies and drug names, with item limits.

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

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

The description clearly states it performs side-by-side comparison of 2–5 companies or drugs. It provides multiple query examples ('X vs Y', 'which is bigger') and distinguishes itself from sequential single-pack lookups, making the purpose unmistakable.

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

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

Explicitly advises to prefer this tool over sequential lookups when comparing entities, and gives natural language triggers. However, it does not explicitly mention when not to use it (e.g., for a single entity), though the sibling 'entity_profile' likely handles that.

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 substantial behavioral context beyond those: account/gating requirements (free plan vs paid 'thorough'), parallel decomposition into 5,798 tools, explicit gaps[] rather than invented answers, contradictions[] behavior, fetchable citation guarantees, semantic excerpting of large records, and latency expectations (15-60s, up to ~90s). No contradiction with annotations.

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

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

Long, but every sentence carries functional information — no fluff or repetition. The most decision-critical information (account requirement, alternative for non-signed-in users, structured data vs open-web) is front-loaded. The length is justified by the tool's complexity and the number of behavioral caveats an agent needs. Deduct one point for density; a short summary line or structured bullets would make parsing faster.

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

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

For a complex tool with no output schema, the description covers the full contract: prerequisites, cost/pricing, input expectations, internal behavior, return format (findings packet with verbatim evidence, confidence, source, fetched_at, citation_uri), failure behavior (gaps[]), error/exception handling, latency, and which siblings to use instead. Nothing critical is missing for an agent 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?

Schema description coverage is 100%, so the schema already documents both parameters well. The description adds extra value by explaining how depth levels map to hop counts and which features are included at each tier (gap recovery, contradictions, paid requirement for thorough). The 'question' parameter is also given context ('Broad/multi-part is fine — decomposition is the point'). Slight deduction because the description doesn't enumerate what 'quick' vs 'standard' vs 'thorough' specifically means beyond hop counts, but the schema covers that.

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 ('research'), a clear resource ('Pipeworx's 1517 STRUCTURED data sources'), and explicitly contrasts itself with open-web search ('this is NOT open-web search'). It also differentiates from siblings like ask_pipeworx by naming them directly and providing selection criteria. The phrasing 'Grounded multi-source research... in ONE call' makes the core function unmistakable.

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

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

The description explicitly says 'If you are not signed in, use ask_pipeworx instead — it works on every tier' and 'For a single lookup use ask_pipeworx' — giving both when-to-use and when-not-to-use guidance with named alternatives. It also specifies ideal use cases ('Best for broad/multi-part questions over structured data') and gives concrete examples. This is exemplary usage guidance.

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

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

Description adds significant context beyond annotations: it specifies the tool returns top-N relevant tools with names, descriptions, and full input schemas with examples, ready to call directly. 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?

Six sentences covering purpose, usage, and behavior without redundancy. Front-loaded with key purpose. Could be slightly more concise but still effective.

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

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

Given no output schema and many siblings, the description fully explains what the tool returns and when to use it, addressing both discovery and direct usability of results.

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

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

Schema coverage is 100%, but description provides extra value by explaining query accepts natural language, lists aliases, and gives examples. This goes beyond simple parameter descriptions.

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

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

The description clearly states the verb 'Find tools' and resource 'tools', differentiated from sibling tools that search for data rather than tools themselves.

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 when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set', providing clear when-to-use guidance and context for exclusion.

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

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

The description discloses significant behavior beyond the annotations: fan-out across many sources, soft-fail for USPTO, GDELT→GNews fallback, empty sections meaning real 'no data', sources_used/sources_failed, and resolved:false with notes for private companies. It is fully consistent with readOnlyHint/idempotentHint.

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

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

The description is front-loaded with usage examples and the priority routing rule, then systematically covers sources, return fields, and failure modes. It is dense and long, but the complexity of the tool justifies most of the detail; only minor redundancy with the schema's parameter descriptions exists.

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 carries the full burden of explaining return values, and it does so thoroughly: cik, recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI, and sources_used/sources_failed. It also covers expected empty sections and private-company behavior, making the tool safely callable without external documentation.

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 description largely repeats what the schema already documents: accepted ticker/CIK/name values and the interchangeability of type 'company' and 'ticker'. The examples are user-friendly but do not add meaningfully new parameter semantics beyond the schema.

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

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

The description clearly states the tool's function: 'full cross-source profile of a US public company in ONE parallel call.' It enumerates the specific data sources and output sections, and explicitly distinguishes itself from chaining single-pack SEC/XBRL/news 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?

It gives an explicit routing rule: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also specifies acceptable input forms and describes the expected behavior for private companies, providing practical when-to-use and when-not-to-use guidance.

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

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

Annotations already provide destructiveHint=true; description adds context about deleting agent-saved memories but does not go 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 unnecessary words, purpose stated first.

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-parameter destructive tool with full schema coverage and adequate annotations, description provides all needed 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 has 100% coverage with description 'Memory key to delete'; description adds no additional meaning beyond schema.

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

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

Description clearly states verb 'Delete' and resource 'memory by key', distinguishing it from siblings 'remember' and 'recall'.

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

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

Explicitly states when to use ('context stale, task done, clear sensitive data') and suggests pairing with 'remember' and 'recall'.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds specific behavioral details: fetches the page, extracts title/description/key links, emits standard markdown. It doesn't contradict annotations and provides useful context beyond them.

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

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

The description is three sentences, front-loaded with purpose, followed by process and use cases. Every sentence adds value with no redundancy or excess.

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 two-parameter tool with no output schema and strong annotations, the description explains the output format (standard llms.txt markdown blob). It could mention error handling or accessibility constraints, but overall it is sufficient for an agent to use the tool correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description mentions default max_links (25) and max (50), which is also in schema. No additional semantic information beyond what the schema provides.

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 specific verbs and resources: 'Generate a production-ready llms.txt file for any URL'. It clearly distinguishes this tool from siblings by focusing on generating the llms.txt standard file, which is unique among the listed 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 provides explicit use cases: getting a client's site indexed, drafting for own project, auditing competitor visibility. While it doesn't explicitly state when not to use it, the use cases are clear and no close sibling exists for generating llms.txt.

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 safety and idempotency; description adds that it lists 'active' subscriptions by default and specifies returned fields, but lacks details on pagination or rate limits.

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

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

Two concise sentences with no redundant information; the main action is 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 list tool with one optional parameter and strong annotations, the description fully covers purpose, usage, and return fields.

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

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

Schema coverage is 100%, and description indirectly clarifies the parameter's behavior by stating 'active subscriptions,' helping the agent understand the default without explicit parameter description.

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

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

The description clearly states the verb 'list' and the resource 'subscriptions', and distinguishes from siblings like 'subscribe' and 'unsubscribe' by focusing on 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?

Explicitly tells the agent to use this to review existing subscriptions before adding more or to find an ID to cancel, providing clear when-to-use guidance.

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

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

Annotations are all false, so the description carries full burden. It discloses rate-limiting (5 per identifier per day), that it's free and doesn't count against tool-call quota, that filing without an account returns a claim_token, and that the team reads digests daily. This goes well beyond what annotations provide, though it doesn't explicitly state the side effect of creating a stored feedback record (which is implied by 'tell the team').

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 runs ~200 words, longer than typical, but nearly every sentence serves a purpose: purpose, exclusions, claim_token workflow, and rate limits. It is front-loaded with the core purpose and then handles edge cases. No fluff, though it could be tightened slightly by merging the rate-limit and free-quota sentences.

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

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

This tool has 4 optional params and no output schema, so the description must cover the touchpoints. It thoroughly explains the claim_token return value, how to use it later, rate limiting, and the scope of what the team can fix. It also provides message-length guidance (1-2 sentences, 2000 chars max). Complete for an agent to know exactly how to invoke it and what to expect.

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

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

Schema coverage is 100%, so baseline 3. The description adds meaningful extra guidance: it explains how to describe issues in terms of Pipeworx tools/packs (not pasting end-user prompts), and details the claim_token round-trip usage ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'). This goes beyond the schema's per-field descriptions, meriting a 4.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This clearly distinguishes it from sibling tools like ask_pipeworx (querying) and discover_tools (exploration). The purpose is unmistakable.

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

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

Provides explicit when-to-use guidance for each feedback type (bug, feature/data_gap, praise) and a firm exclusion: only for tools served by this Pipeworx connection, not other MCP servers. Also explains the claim_token workflow for checking resolution, leaving no ambiguity about when to use each parameter.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. Description adds further transparency: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' This communicates safety, data source, and caching behavior, exceeding the annotation baseline.

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

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

Description is concise (three sentences), well-structured, and front-loaded with the main function. Every sentence adds value with no redundant or extraneous content.

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

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

Tool has one optional parameter and no output schema, but description fully covers returned data (top tools, top packs, total call volume) and caching behavior. For its simplicity, the description is complete without gaps.

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

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

The single parameter 'window' has full schema coverage with enum and description. The description adds semantic value: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This provides meaningful interpretation beyond the raw schema.

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

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

Description clearly states it returns top tools, top packs, and total call volume over a recent window. The verb 'returns' and resource specification are precise, and the tool's purpose (trending/popularity) distinguishes it from siblings like discover_tools or top_species.

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 three explicit use cases (discovering hot data sources, confirming popular tool, aligning use case) and explains the significance of window options. While it lacks explicit 'when not to use' or alternative tool names, the use cases offer strong positive guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false. The description goes further by explaining internal logic: walks child markets, checks date-axis/threshold-axis ordering, computes partition_sum, applies Jaccard similarity filter (≥0.30), filters placeholder slugs, and performs fill check against live CLOB depth. No contradictions.

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

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

The description is well-organized with sections for each mode and sub-sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). It is front-loaded with the main purpose and modes. However, it is slightly verbose with implementation details that could be condensed, but still effective.

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

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

Given the tool's complexity (multiple modes, filters, and trade signals), the description covers all necessary aspects: input modes, output structure (opportunities[] with fields), fill-check logic, and limitations. It also references a related tool for custom sizing, making it complete.

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

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

Schema coverage is 100% with parameter descriptions. The tool's description adds context: recommends event for specific markets, topic for cross-event scanning, and notes that full Polymarket URLs are accepted. 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 defines the tool's purpose: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It specifies three distinct call modes (no args, event, topic) and distinguishes itself from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

The description provides explicit guidance on when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It also warns when not to trade (realizable_edge_pp ≤ 0) and references 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 are supplemented with extensive behavioral details: caching (1h at KV level), response structure with diagnostics, edge calculation formulas, slippage handling, and exclusion of certain bets. No contradictions with annotations.

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

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

The description is lengthy but front-loaded with purpose. Every sentence adds value for an agent, but some technical formula details could be simplified without loss of clarity.

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

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

Given 9 parameters, no output schema, and rich annotations, the description covers caching, return structure, edge sources, filtering knobs, and diagnostics, making it fully complete for an agent to use correctly.

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

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

Schema coverage is 100%, so baseline is 3. Description adds context beyond schema, such as explaining 'Tradeable-edge filter' for max_spread_pp and min_liquidity, and clarifying that min_kelly applies to single-leg opportunities while min_partition_leg_kelly applies to partition legs.

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 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price' and positions it for 'what should I bet on today'. This provides a specific verb+resource+goal that distinguishes it from sibling tools like polymarket_arbitrage.

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

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

Description explains the tool's role in discovery without paging, details tradeable-edge knobs for filtering, and notes Fed bets are excluded. However, it does not explicitly name alternative tools or state when not to use this one.

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

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

Annotations already declare readOnly, idempotent, non-destructive. The description adds significant behavioral details: explains the response structure (tracked[], expired[], snapshot_dates[]), how decay is computed, and limitations like 60-day TTL and daily snapshots. No contradiction with annotations.

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

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

The description is well-organized, starting with purpose, then arguments, then detailed response structure. It is appropriately sized for the tool's complexity, though some of the response details could be slightly more concise.

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

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

Given no output schema, the description fully explains the return format: three arrays with detailed fields for each (tracked edges with time-series, expired edges with lifespan, snapshot dates). It also covers limitations (60-day TTL, daily close data) and edge cases (gaps in snapshots). Comprehensive for a complex tool.

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

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

Schema coverage is 100% with both parameters already well-described (defaults, clamps, enums for window). The description merely restates this information (e.g., 'days (lookback, default 14, max 30)') without adding new meaning or usage guidance 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's purpose: tracking edge persistence and decay over time. It uses specific verbs ('answers how long has this edge existed and is it shrinking?') and distinguishes itself from sibling tools like polymarket_edges by focusing on historical telemetry rather than current edges.

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

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

The description provides a clear use case (assessing whether an edge is decaying) and contrasts with fresh vs. old edges. However, it does not explicitly state when not to use this tool or name alternative tools for different scenarios, such as using polymarket_edges for current edge data.

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

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

Annotations declare readOnlyHint, idempotentHint, etc. The description adds extensive behavioral details: how it walks the ladder, what fields it returns (top_of_book, vwap_fill_price, slippage_pp, shares_filled, etc.), and important warnings about partial fills. No contradictions.

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

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

The description is well-structured with clear sections for single-market and basket modes, and key points in caps. It is front-loaded with purpose. However, it is somewhat long and could be slightly more concise without losing clarity.

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

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

Given the complexity (two modes, many return fields, no output schema), the description is highly complete. It details all returned fields, explains the verdict, warns about thin legs and directional risk, and covers both use cases thoroughly.

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

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

Schema coverage is 100% (all parameters have descriptions). The description adds significant meaning beyond the schema, e.g., explaining size_usd interpretation in single-market vs basket mode, default values, and behavior of side auto-selection in basket mode. This goes well above the baseline of 3.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth'. It specifies the verb (check) and resource (edge), and distinguishes from siblings like polymarket_arbitrage and polymarket_edges by explaining when this tool should be used.

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 THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It warns about when not to skip it (e.g., partial basket fills convert arb into directional position), providing clear context and alternatives.

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

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

The description goes far beyond the readOnly/openWorld/idempotent annotations by disclosing the token-overlap matching method, compatibility_codes semantics, skipped leg categories, temporal_alignment nuances, and that Kalshi fees are not modeled so spreads are gross, not net. It even clarifies that temporal_alignment_unknown is not the same as confirmed alignment and that returned pairs are always 'pairing_unverified.' These are exactly the behavioral traits an agent needs.

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 almost every sentence earns its place given the complexity of the tool and the absence of an output schema. It is front-loaded with the core purpose, then modes, then response safety fields. The main deduction is for some redundancy, such as repeating temporal_alignment_unknown and stressing 'pre-mapped ≠ tradeable' at the end after it was already implied.

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 carries the full burden of explaining return semantics, and it does so thoroughly: leg prices, top_spreads_pp, compatibility codes, skipped counters, fees_note, and temporal alignment fields. However, all three parameters are optional and the description never states what happens when neither a topic nor explicit ticker/slug is provided, which is a meaningful gap for an agent deciding how to invoke the tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value beyond the schema by explaining how the three parameters interact: topic is a pre-mapped shortcut, and the explicit ticker/slug 'override' the topic-mapped side. It also makes clear that both modes run the 'identical token-overlap matcher,' which is not evident from 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 opens with a specific verb and resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes this tool from siblings like polymarket_arbitrage and polymarket_edges by emphasizing that it compares prices across two venues, not within a single venue. The two modes and response scope are also clearly stated up front.

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

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

The description gives clear selection guidance: use the `topic` mode for pre-mapped macro shortcuts and explicit `kalshi_event_ticker` + `polymarket_event_slug` for custom pairings. It also warns that 'pre-mapped ≠ tradeable' and that compatibility_warning should be read even when matched_pairs>0. However, it never explicitly names alternative sibling tools or states when NOT to use this tool in favor of a sibling like polymarket_arbitrage.

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

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

Annotations indicate readOnlyHint, idempotentHint, destructiveHint. Description adds scoping details (anonymous IP, BYO key hash, account ID) and pairing with remember/forget, which goes beyond annotations. No contradiction.

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

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

Three sentences, each with a purpose: first states core action, second gives usage context, third adds scoping and related tools. No unnecessary words.

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

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

Tool is simple (1 optional param, no output schema). Description covers use cases, scoping, and sibling relationships. No gaps.

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

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

Schema coverage is 100%; baseline 3. Description adds meaning by explaining behavior when key is omitted (list all keys), which is not fully captured in the schema's parameter 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?

Clearly states the verb 'retrieve' and resource 'value previously saved via remember', and distinguishes by explaining omitting key lists all keys. Distinguishes from siblings remember and forget.

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

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

Provides context for when to use: 'look up context the agent stored earlier... without re-deriving it from scratch.' Mentions scoping and pairing with remember/forget. Lacks explicit when-not, 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 declare readOnlyHint=true, implying no state modification, but the description says 'Set mark_read:true to flag returned events read so the next call only shows newer ones,' which clearly modifies state. This is a direct contradiction. The description also fails to disclose other behaviors like rate limits or auth requirements.

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

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

The description is relatively concise with about five sentences, front-loading the core purpose. It uses clear language and avoids unnecessary verbiage. Minor redundancy exists (e.g., 'Polls work fine' could be more precise), but overall it 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?

Given the tool has 5 parameters, no output schema, and annotations provide some context, the description covers return fields, parameter usage, and an alternative access method. It does not address error handling or pagination, but the information provided is sufficient for 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?

Schema coverage is 100%, and the description adds value beyond schema descriptions by providing examples (e.g., 'sec_8k' for type) and explaining the effect of 'mark_read' on subsequent calls. It does not repeat all schema details, but the added context is helpful.

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

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

The description starts with a clear verb+resource: 'Pull fired events from your subscription feed.' It specifies the return fields (source, citation_uri, raw event payload) and filtering options, making the purpose very specific and actionable. While it doesn't explicitly distinguish from siblings, the purpose is unambiguous.

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

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

The description provides guidance on filtering and the 'mark_read' parameter, and mentions an alternative HTTP endpoint for scripts. However, it does not explicitly advise when to use this tool versus sibling tools like 'list_subscriptions' or 'subscribe', nor does it state conditions where the tool should not be used.

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

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

Beyond annotations (readOnly, idempotent, not destructive), the description details fan-out to multiple sources, fallback behavior (GNews when GDELT rate-limited), and soft-failures (PatentsView API sunset). It also describes return structure.

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

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

The description is somewhat lengthy but every sentence adds unique value. It opens with common query patterns and then explains mechanics. Could be slightly more structured, but it is efficient and informative.

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

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

Given the complexity (three sources, fallback, single call), the description covers what the tool does, return shape (changes grouped by source), limitations (soft-fail on USPTO), and entity type constraint. No output schema, but return structure is described.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining shorthand for 'since' (e.g., '7d', '3m'), suggesting typical monitoring values, and clarifying that 'type' only supports 'company'.

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

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

The description clearly states the tool returns a change feed for a company, combining SEC filings, GDELT/GNews news, and patents. It provides specific query examples and distinguishes from sibling 'entity_profile'.

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

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

The description explicitly advises when to use this tool vs entity_profile, and gives guidance on the 'since' parameter (e.g., 'use 30d or 1m for typical monitoring'). No explicit when-not-to-use beyond the single sibling alternative.

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

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

Description adds value beyond annotations: key-value scoped by identifier, persistence differences for authenticated vs anonymous users (24h). No contradiction with annotations.

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

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

Four sentences, each serving a purpose: action, usage trigger, scoping/persistence, complementary tools. 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 no output schema, description explains storage behavior, scoping, and persistence. It adequately prepares the agent to use the tool correctly.

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

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

Schema coverage is 100%, so baseline 3. Description adds context by explaining key-value storage and scoping, which helps understanding 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?

The description clearly states 'Save data the agent will need to reuse later' with specific verb 'Save' and resource 'data'. It distinguishes from siblings like recall and forget by mentioning them explicitly.

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' and provides examples. Also advises pairing with recall/forget for complete memory lifecycle.

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

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

Annotations already declare read-only, idempotent, non-destructive, and open-world behavior, but the description adds substantial behavioral detail beyond that: internal multi-endpoint cascading, graceful degradation when GLEIF/OpenFIGI are unavailable, explicit `unresolved` reporting instead of omission, and returning `figi_candidates` rather than asserting an answer on ambiguous matches. 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 front-loaded with routing guidance and examples, then structured by supported type. It is long and dense, with some editorial asides, but nearly every sentence carries operational value for a tool with this much domain complexity. A more compact version could trim repeated examples, but the structure remains navigable.

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 carries the burden of explaining return semantics, and it does: identifiers are labeled by source, unresolved identifiers appear under `unresolved`, ambiguous FIGI matches return `figi_candidates`, and drug lookups return RxCUI plus ingredient and brand. Combined with the annotations and schema, an agent has enough to invoke and interpret the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description and parameter docs go well beyond the schema. They explain accepted input forms (ticker, CIK, ISIN, name), give examples, warn against including trailing security-class words for bond issuers, and clarify ISIN-to-LEI behavior for non-US entities. This materially reduces the chance of 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-phrase examples and a crisp definition: resolve a user-spoken NAME to canonical identifiers other tools require. It clearly distinguishes the tool as the name-to-ID resolver in a large sibling set, and enumerates supported types (company, drug) with specifics like CIK, LEI, FIGI, and RxCUI.

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 instruction 'Use FIRST whenever you have a name but need an ID' is an explicit, actionable routing rule. It also explains that internal cascading replaces multiple manual lookups. However, it never names specific sibling tools to avoid or states exclusions such as 'if you already have the ID, use another 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?

Beyond the safe annotations (readOnlyHint, idempotentHint), the description reveals that it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. This provides significant behavioral insight not present in annotations.

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

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

The description is two sentences, front-loading the purpose in the first sentence and adding mechanism and use case in the second. Every sentence is meaningful with no redundancy.

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

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

The description covers what the tool does, how it works internally, and what it returns. While it omits exact constraints (e.g., entity count 2-8) and error handling, these are covered by the schema and the description is sufficient for an agent to use the tool correctly.

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

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

Schema coverage is 100%, but the description adds value by explaining that the first entity is treated as the 'subject' for narrative purposes and that context disambiguates common names. This enriches understanding beyond the raw 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 it compares AI visibility across multiple entities side-by-side, explicitly referencing the sibling tool ai_visibility_check for individual probes. It distinguishes itself from single-entity checks and explains the competitive audit use case.

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 a concrete use case ('competitive AI-marketing audits') and implies when to use over ai_visibility_check (single vs multiple). However, it does not explicitly state when not to use or list alternatives beyond the implicit reference.

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

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

Annotations declare readOnlyHint, idempotentHint, destructiveHint. Description adds behavioral details: fans out to two services, partial failures degrade gracefully, Bundlephobia first measurement can take 5-30s, sources_failed lists timeouts. These go beyond annotations to set accurate expectations.

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

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

Description is longer but well-structured: starts with purpose, then usage guidelines, then behavioral notes. Every sentence adds value, though could be slightly more concise without losing clarity.

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

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

Despite no output schema, description fully specifies return fields (summary block, per-advisory detail, links, alternative versions), ecosystem limitations, and error handling. Covers all necessary context for an agent to understand inputs, outputs, and edge cases.

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

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

Schema coverage is 100% with descriptions for both parameters. Description adds that version defaults to latest when omitted and scoped packages like @types/node are accepted, supplementing schema without redundancy.

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

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

The description clearly states the tool's purpose: a composite check for npm packages combining deps.dev and bundlephobia data. It specifies resources (npm package) and action (scan), and distinguishes from siblings by being the only tool dedicated to dependency analysis.

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

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

Provides explicit when-to-use guidance: 'when an agent asks "is X safe / popular / small" or "what does adding lodash cost me". It also states when NOT to use: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', clearly differentiating from alternatives.

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

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

Annotations already declare readOnlyHint=true, etc. Description adds that results are 'photographed sightings with coordinates, dates, and observer info' and that place auto-resolves to place_id. No harmful behavior, but adds useful 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?

Single paragraph front-loads purpose and then details filters and return fields. While slightly dense, every sentence adds value and the description is efficient for the information conveyed.

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 output schema present and annotations covering safety, the description provides all essential usage details: filters, return fields, and cross-validation hint. No gaps remain for an agent to use this tool effectively.

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

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

Schema coverage is 100% (baseline 3). Description adds examples of taxon names (common and scientific), clarifies that place auto-resolves, and lists filterable criteria in a narrative form, providing extra value over 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?

Description explicitly states verb ('Search'), resource ('citizen-science wildlife observations on iNaturalist'), and scope ('ANY organism'). Provides examples of filterable criteria and contrasts with sibling tool GBIF, making purpose unmistakable.

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

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

Gives a clear usage pattern ('sightings/observations of <species> in <place> in <year>') and suggests pairing with GBIF. However, does not explicitly state when not to use or compare with sibling tool 'search_taxa'.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds return field details but no behavioral traits beyond what annotations provide.

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

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

Two sentences, front-loaded with action and return fields, no waste. Every word adds value.

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

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

Covers purpose, return format, and downstream usage. Output schema exists for detail, and parameters are fully described in the schema. No gaps identified.

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 does not add additional meaning beyond what is in the schema, so baseline score of 3 applies.

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

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

The description clearly states the tool searches iNaturalist taxa by name (common or scientific), lists specific return fields, and distinguishes it from other tools like search_observations by mentioning downstream use of taxon 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?

Provides explicit guidance on using the taxon ID for downstream filters or disambiguation, but does not mention when not to use this tool or direct alternatives among siblings.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds significant behavioral details: embedding model (BGE-base-en), cosine over 500-char windows, 200K char cap with truncation flag, and every passage carries offset for verification. 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 about 6-7 sentences, well-structured with the core purpose upfront. Each sentence adds unique information without redundancy. Could trim minor details but still 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?

With no output schema, the description adequately explains the output (passages with offsets, similarity scores). It covers internal mechanics, limitations (char cap), and pairing with a sibling tool. Slightly more could be said about error scenarios, but overall complete for the complexity.

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

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

Schema coverage is 100% with descriptions for all three parameters. Description enhances meaning by explaining the purpose of each parameter (e.g., 'Natural-language query'), default values, and constraints (max chars for text). Adds value beyond schema.

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

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

The description clearly states the tool performs semantic search inside a fetched record, specifying input (text and query) and output (passages with offsets and scores). It distinguishes from siblings by naming ask_pipeworx_grounded and explaining when to use this tool over 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?

Explicitly says 'Use when the record is too big to cram into the prompt' and explains benefits (saves context, returns only relevant passages). It pairs with a sibling tool, providing integration guidance. No explicit 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 discloses important behavioral traits beyond annotations: persistence requirement (anonymous/BYO cannot persist), delivery constraints (SMS 10/day cap, webhook auto-disabled after 10 failures), and response including subscription id. It does not contradict annotations (readOnlyHint=false, idempotentHint=true).

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

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

The description is comprehensive but slightly long. It is well-structured with line breaks and grouping by subscription type, and front-loaded with the main action. Every sentence adds value, but some redundancy (e.g., repeated phone verification note) could be trimmed.

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

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

Given the complexity (5 subscription types, 3 delivery channels, constraints, and authentication requirements), the description is thorough. It explains the return value and covers all critical aspects for correct agent invocation, making it complete for a tool without an output schema.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant value by providing type-specific examples (items:['5.02'], topic:'fed', series_id:'UNRATE') and detailed delivery configurations (webhook signing, phone verification). This extra context improves parameter understanding beyond the schema.

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

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

The description uses a specific verb ('Create') and resource ('proactive monitoring subscription'), and clearly states the return value ('Returns the new subscription id'). It distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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

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

The description provides clear context on when to use this tool (to set up monitoring subscriptions) and prerequisites ('Requires a Pipeworx OAuth account'). It details supported types and delivery channels, guiding the agent on appropriate usage, though it does not explicitly state when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. The description adds that it returns category-bucketed example questions with tool and argument shapes, which is useful behavioral 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 thorough but slightly long; however every sentence serves a purpose. It is front-loaded with common questions and structured logically from overview to usage details.

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

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

The description fully covers the tool's purpose, when to use it, what it returns, and how to call it. Given no output schema, the description explains the return format sufficiently.

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

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

Schema coverage is 100%, providing a baseline of 3. The description adds value by explaining that omitting the topic gives 'full spread' and passing a focus topic narrows results, which is more semantic than the schema's brief description.

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

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

The description clearly states it is the onboarding entry point for an agent to learn what Pipeworx can do. It uses specific verb phrases like 'What can I ask Pipeworx?' and lists example topics, distinguishing it from siblings such as ask_pipeworx and discover_tools.

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

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

Explicitly says to use this FIRST when you do not know what Pipeworx can do, or to learn how to call meta-tools. Also provides guidance on invoking with no arguments for full spread or with a specific topic.

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

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

Annotations already mark it as read-only and idempotent. Description adds that place auto-resolves to ID, which is useful behavioral context beyond annotations.

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

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

Two concise sentences without fluff, front-loaded with key information.

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

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

Despite simplicity, description covers purpose, behavior, and usage. Output schema exists, so no need to detail return values.

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

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

Schema has 100% coverage with basic descriptions. Description adds that place auto-resolves to place_id and per_page is 1-50 with default 20, enhancing understanding.

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

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

Description clearly states the tool retrieves most-frequently-observed species in a place over a date range, auto-resolves place names, and returns ranked data. Distinct from siblings like search_observations.

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 for 'what wildlife lives here?' questions, implying when to use. Could improve by mentioning when not to use or naming 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?

Describes deactivation (not deletion) and preservation of historical events, adding behavioral context beyond annotations. Also clarifies ownership enforcement.

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, 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 single-parameter tool with no output schema, description covers ownership, effect (deactivation), and relation to historical data. Complete.

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

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

Schema coverage is 100%, so baseline is 3. Description adds that 'id' is the subscription id from subscribe, but schema already describes it.

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 verb 'cancel' and resource 'subscription by id'. Distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Explicitly mentions ownership enforcement ('only cancel your own subscriptions'), guiding when to use. Does not explicitly mention 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?

While annotations already mark the tool as read-only, idempotent, and open-world, the description adds critical behavioral details: specific verdict types, the meaning of 'could_not_verify' with its error object, and the distinction between 'unsupported' and 'refuted'. It also warns that 'could_not_verify' must not be presented as evidence, which is a crucial misuse-avoidance trait.

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

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

The description is longer than typical but every sentence adds value: trigger phrases, usage guidance, dual-path behavior, return semantics, and error handling. It is well-structured with clear transitions, though slightly verbose; the density of important information justifies the length.

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

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

With no output schema, the description fully covers return values (verdict types), error cases, and the reasons for outcomes. It also explains the fast vs. grounded paths and how the tool replaces multiple sequential steps, making it complete for an agent to invoke correctly without external 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?

The schema already provides full descriptions for both parameters (100% coverage), but the description enriches them by explaining how tolerance_pct interacts with claim wording, the default cap of 5, and its use for hallucination detection. This added context goes beyond the schema's basic descriptions, though the schema already carries significant weight.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources, with explicit trigger phrases. It distinguishes itself from siblings by covering both a structured SEC EDGAR path and a grounded pipeline, and notes it replaces 4-6 sequential calls, making its unique role obvious.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and differentiates between company-financial claims and other factual claims. It also implies when not to use it by contrasting with the sequential alternative, providing clear context for tool selection.

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