Smithsonian

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

Annotations indicate readOnlyHint, idempotentHint, and non-destructive behavior. The description adds behavioral context: it returns per-model score, confidence, signals, raw_response, and a combined view. It also discloses cost implications for Anthropic ('you pay directly'). While not exhaustive (e.g., no mention of rate limits or timeouts), it adds valuable behavioral insight beyond annotations.

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

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

The description is two sentences plus a use-case sentence, all front-loaded with the core action. Every sentence contributes value without redundancy. No fluff or unnecessary details.

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

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

Given no output schema, the description explains the return structure (per-model object with score, confidence, signals, raw_response, plus combined view) and lists use cases. It covers purpose, parameters, and returns. Minor gaps: no mention of error handling or what happens with invalid API keys, but overall complete for the tool's complexity.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning by clarifying the default model ('Workers AI Llama-3.3-70b (free)') and the relationship between models and _apiKey. This goes beyond the schema descriptions, which already are detailed. The added context about free vs paid is helpful for parameter selection.

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: probing LLMs for knowledge about a business/brand/product/topic and scoring visibility. It specifies the verb (probe, score), resource (LLMs), and output format. This is a specific, distinguishable function among siblings.

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

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

The description provides explicit when-to-use guidance: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains the free default model and the optional Anthropic probe with BYO key. However, it does not mention when not to use this tool or compare with similar siblings like scan_competitor_ai_presence.

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, and idempotentHint. The description adds that it internally selects the best tool, returns structured answers with pipeworx:// citation URIs, and works in one fast call. This explains the routing behavior beyond the annotation safety profile.

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 instruction ('PREFER OVER WEB SEARCH') and efficiently packs domain lists, examples, and sibling comparisons. It is slightly verbose in listing domains but each sentence serves a purpose (scope, use cases, alternatives). 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?

No output schema is provided, so the description adequately explains return format (structured answer with citation URIs). It covers scope, tier compatibility, and use cases. It lacks error handling details but is sufficiently complete for a general-purpose query tool with strong annotations.

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

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

Schema coverage is 100% because all 6 parameters (aliases for 'question') have descriptions. The tool description does not add meaning beyond the schema—it only mentions example questions. The baseline of 3 is appropriate as the schema already fully documents each parameter.

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

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

The description clearly states the tool routes factual questions to 4,772 tools across 1,242 sources and returns structured answers with citations. It lists specific domains (SEC filings, FDA data, etc.), making the purpose highly specific and distinct from siblings like ask_pipeworx_grounded and deep_research.

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

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

Explicitly instructs to prefer this over web search for factual questions, gives example query phrasings, and provides when to use alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad queries). Includes specific user intent signals (e.g., 'what is', 'look up') and tier compatibility.

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

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

Annotations already mark the tool as readOnly, openWorld, and idempotent. The description goes beyond by explaining the internal routing, extraction process, refusal reasons, and the extra LLM call cost. This fully discloses behavior without contradicting annotations.

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

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

The description is comprehensive and well-structured, front-loading the core purpose. However, it is slightly verbose with the detailed explanation of the routing and return format. It could be trimmed slightly without losing meaning.

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 the return structure (answer, evidence, confidence, etc.) and all possible refusal reasons. It also covers the tool's behavior, limitations, and cost trade-off, leaving no important 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%, but the description adds value by noting that 'question' accepts aliases like q, prompt, text, input. This clarifies input flexibility beyond the schema's structural definitions.

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

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

The description clearly defines the tool as a hallucination-resistant answer mode for high-stakes reads. It specifies the verb 'ask' with a grounded constraint, and explicitly distinguishes it from the sibling tool 'ask_pipeworx' by highlighting the additional extraction step and refusal logic.

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

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

The description explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also advises when not to use: 'prefer ask_pipeworx for casual lookups.' This provides clear guidance on choosing between siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds extensive behavioral context: fan-out parallelism, resolver handling (match confidence, alternatives, suggestions), parent event extraction, news fallback mechanisms, safety short-circuits (low-confidence, closed markets, wide spread), and cancellation rule parsing. It explains what happens internally and how to interpret responses. 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 lengthy but well-structured with capitalized section headers and clear examples. It is front-loaded with the core purpose. However, some sentences are verbose and could be streamlined (e.g., the cancellation rule paragraph). Every sentence adds value, but the overall length may overwhelm some agents. Still, it's organized for reading.

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

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

Since there is no output schema, the description must fully explain return values. It does: result.market (bid/ask/spread/liquidity), result.analysis (model probability, edge, kelly fraction with 24h-move warning), result.evidence keyed by source, result.market_match_confidence (with alternatives and suggestions), result.parent_event, news fields with fallback info, and edge cases (low-confidence, closed, wide spread, cancellation rules). This is comprehensive.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond the schema. For 'market', it clarifies accepted formats (slug, URL, question text). For 'depth', it explains quick vs thorough. For 'include_raw', it details the trade-off (summarized vs full payload) and when to use each. This goes well beyond the schema's enum and description.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the input types (slug, URL, question text) and outputs (evidence packet + market-vs-model comparison). It lists specific use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'), differentiating it from sibling tools like ask_pipeworx or deep_research. This is a specific verb+resource with clear scope.

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

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

The description provides explicit guidance on when to use the tool ('Use for ...'). It explains the fan-out behavior per classifier, the resolver contract, parent event extraction, and safety mechanisms (low-confidence short-circuit, closed markets, wide spread). It also warns when to inspect market_match_confidence before trusting analysis. This covers when and when-not, and how to interpret results.

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, non-destructive behavior. The description adds valuable context: it specifies data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), explains handling of off-calendar fiscal years, notes results are sorted by primary metric, and mentions return format includes paired data and citation URIs. No contradictions with annotations.

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

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

The description is compact but packed with information. It front-loads with user-facing query examples, then explains the two entity types, and finally describes output characteristics. Every sentence serves a purpose—no redundancy or fluff. It is well-organized and easy to parse.

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

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

Given 2 parameters, 100% schema coverage, and no output schema, the description fully compensates by explaining what data is returned (paired metrics, citation URIs), how results are sorted, and what data sources are used for each type. This gives the agent all necessary context to use the tool effectively without needing additional references.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond the schema: it explains that 'type' determines which data is pulled (10-K financials vs FAERS/trials), provides examples for 'values' (tickers/CIKs vs drug names), and clarifies sorting behavior ('largest' reads off top). This transforms the schema into actionable guidance.

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

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

The description uses specific verbs ('compare', 'side-by-side comparison'), identifies the resource ('companies or drugs'), and gives multiple example queries. It clearly distinguishes from sibling tools like entity_profile by stating 'ALWAYS PREFER over sequential single-pack lookups' and quantifying that it replaces 8-15 sequential calls.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear guidance on when to use this tool over alternatives. It also explains the scope (2-5 entities, one call) and gives a rationale (replaces 8-15 sequential lookups), which helps the agent decide confidently.

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

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

Adds significant behavioral context beyond annotations: account requirement, paid plan for 'thorough', parallel decomposition, returns findings packet with gaps[], expected duration (15-60s). 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?

Well-structured with critical info front-loaded (account requirement, alternative). Every sentence is informative, though slightly verbose. Could be tightened 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?

Highly complete given complexity: explains input, output format (findings packet with specific fields), behavior, and limitations. No output schema, but description covers return structure adequately.

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 value by explaining enum values for depth (quick=3, standard=5, thorough=8) and that question can be broad/multi-part, exceeding schema detail.

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: 'Grounded multi-source research across Pipeworx's 1242 STRUCTURED data sources... in ONE call'. It explicitly distinguishes itself from open-web search and sibling tools like ask_pipeworx and bet_research.

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

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

Provides explicit when-to-use (broad/multi-part questions over structured data) and when-not-to-use (breaking current news, single lookups). Names alternatives: ask_pipeworx for single lookups or breaking news, and mentions account tiers.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by stating that results include full input schemas with curated examples and are 'ready to call directly, no second schema lookup needed,' which improves transparency beyond annotations.

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

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

The description is appropriately concise and front-loaded with the core purpose. It uses short sentences and lists domains efficiently. A few minor redundancies (aliases mentioned twice) but overall clear and 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's complexity (6 parameters, 1 required, no output schema), the description adequately covers purpose, usage context, and what each result contains. The lack of output schema is compensated by describing the return format. Completeness is good.

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 parameters are well-documented in the schema. The description mentions query (as natural language) and limit (max number), but does not add significant new meaning beyond what's already in the schema. Baseline 3 is appropriate.

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

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

The description explicitly states the tool's purpose: 'Find tools by describing the data or task.' It clearly identifies the verb (find/discover), resource (tools), and distinguishes itself from sibling tools that perform specific tasks like search, entity resolution, or betting research.

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

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

Provides clear usage guidance: 'Call this FIRST when you have many tools available and want to see the option set.' Lists specific domains (SEC filings, FDA drugs, etc.) to guide when to use. Lacks explicit when-not or alternatives, but context is sufficient.

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

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

Annotations declare readOnlyHint, idempotentHint, and destructiveHint (false). The description adds details: single parallel call, fans across multiple sources, returns specific fields, and patents may soft-fail. 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 fairly long but well-structured with front-loaded examples and a clear recommendation. Every sentence adds information, though minor redundancy exists (e.g., repeating parameter info).

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

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

Given no output schema, the description thoroughly explains return fields (cik, company_name, filings, fundamentals, patents, news, LEI), sources, and failure modes. It is complete for an agent to understand expectations.

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

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

Schema coverage is 100%, but the description adds value by clarifying that value accepts ticker or zero-padded CIK and that names are not supported. It also explains the type parameter's current limitation. This goes 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 provides a full cross-source profile for US public companies, with example queries like 'Tell me about X' and 'company profile for Microsoft'. It explicitly distinguishes from chaining single-pack lookups and sibling tools like resolve_entity.

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

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

The description includes explicit when-to-use guidance (user asks for holistic view) and when-not-to-use (names not supported; use resolve_entity first). It also notes the patents soft-fail, providing clear context for appropriate invocation.

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

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

Annotations already indicate destructiveHint=true. The description adds context about clearing sensitive data but does not substantially expand on 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?

The description is two sentences long, front-loaded with the action, and contains no unnecessary words. Every sentence adds value.

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

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

Given the tool's simplicity (one parameter, no output schema), the description adequately covers purpose and usage, making it complete for the agent to select and invoke correctly.

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

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

Schema coverage is 100%, and the description only restates the schema's parameter description ('key' to delete). No additional semantic details are given, so baseline score of 3 is appropriate.

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

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

The description clearly states 'Delete a previously stored memory by key,' specifying both the action and the resource. It distinguishes from sibling tools like 'remember' and 'recall'.

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

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

The description provides explicit guidance on when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data.' It also mentions pairing with related tools but 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=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral details: fetches page, extracts title/description/key links, emits standard markdown. No contradictions. Could mention auth or rate limits but not necessary given safe 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 plus a bullet list, all front-loaded with the tool's purpose and action. Every sentence adds value; 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?

For a simple tool with 2 parameters, 100% schema coverage, and clear annotations, the description covers enough: input, process, output format, and use cases. Lacks details on error handling or response format, but not critical given the tool's simplicity.

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

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

Schema coverage is 100%; both parameters (url, max_links) are already well-described in the schema. The description does not add meaning beyond the schema (e.g., no format hints for url, no explanation of max_links defaults). Baseline 3 applies.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the exact resource and action. It distinguishes itself from siblings like ai_visibility_check and scan_competitor_ai_presence by focusing on llms.txt generation.

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 client's site indexed, drafting for own project, auditing competitor). It does not explicitly state when not to use or list alternatives, but the context is clear and the sibling list helps differentiate.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description adds value by listing returned fields. No behavioral surprises beyond what annotations indicate.

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, each providing distinct value. No redundancy or fluff. Purpose 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?

Description adequately covers the tool's purpose, returned fields, and usage context. No output schema, but return fields are listed. Could be slightly more explicit about scope (caller's own subscriptions), but overall complete for a simple list 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 the single optional parameter 'include_inactive' described in schema. The description does not add extra meaning beyond the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool lists the caller's active subscriptions and enumerates the returned fields. It distinguishes from sibling tools like subscribe and unsubscribe by specifying the action and resource.

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 guides when to use: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Provides clear context, though does not explicitly state when not to use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the description does not need to repeat these. The description adds context that the tool returns 'full details', which is useful. 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 a single, well-structured sentence that conveys the tool's purpose without 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?

Given the tool's simplicity (2 parameters, no output schema), the description is sufficient. It does not explain the return format, but annotations imply a safe, idempotent read operation.

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

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

The input schema has 100% coverage. The description adds meaning by explaining that the 'id' parameter should be a Smithsonian content id from search results, which complements the schema's example value.

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

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

The description clearly states the tool fetches full details for a Smithsonian Open Access item by its id, with a specific note that the id comes from the search 'id' field. This distinguishes it from sibling tools like 'search' and 'search_within'.

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

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

The description implies usage after a search by referencing the 'id' field from search, but it does not explicitly state when to use this tool versus alternatives, nor does it mention any exclusions or prerequisites.

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

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

Discloses rate limit (5 per identifier per day), cost (free, no quota impact), and team's usage of feedback (daily digests, affects roadmap). Annotations are minimal (no relevant hints), so description fully covers behavioral traits.

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

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

Four tight sentences: purpose, usage guidelines, behavioral notes. Front-loaded with core action. No unnecessary words; every sentence adds critical information.

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

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

For a simple feedback tool, the description covers everything needed: what to include, what to avoid, rate limits, quota impact, and team's response. No gaps remain even without output schema.

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

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

All three parameters have schema descriptions (100% coverage). The description adds real value by explaining the type enum in detail, specifying message length limit (2000 chars), and describing the optional context structure.

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

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

Description starts with a clear verb ('Tell') and specific resource ('Pipeworx team'). It lists concrete use cases (bug, feature, data_gap, praise) and distinguishes from sibling tools by referencing tools/packs.

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 (bug, feature/data_gap, praise) and what not to do (don't paste end-user prompt). No ambiguity about context of use.

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

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

Annotations already indicate safe read-only behavior. The description adds caching specifics, data source (CF analytics), and lack of PII, providing context beyond annotations.

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

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

The description is efficient: three sentences with bullet-style use cases, front-loaded with output, and 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?

For a simple read-only tool with one optional parameter and no output schema, the description covers output, purpose, use cases, data source, caching, and privacy adequately.

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. The description adds semantic guidance on trade-offs between short and long windows, going beyond the enum.

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 top tools, packs, and total call volume over a window. Three concrete use cases are provided, distinguishing it from siblings like discover_tools.

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

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

The description lists three useful scenarios but does not explicitly state when not to use it or compare to alternatives among the many sibling tools.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds rich behavioral context: monotonicity checks, partition-sum logic, Jaccard similarity threshold (≥0.30), placeholder filtering, and fill-check against 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?

Description is lengthy but well-structured with sections like SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK. Every sentence adds necessary detail for a complex tool. Could be slightly condensed, but organization compensates.

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

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

Despite having no output schema, the description fully explains the response structures (opportunities[], partition_check, fill_check details). Covers edge cases (low similarity, placeholder fraction, fill-check results) and references sibling tool for custom sizing. Complete for the tool's complexity.

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

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

Schema coverage is 100% with descriptions for event and topic. The description adds significant meaning: event accepts full URLs, topic triggers cross-event search, and no args triggers trending scan. This goes beyond the schema, but baseline for high coverage is 3; credit for extra context.

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

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

The description explicitly states it finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) and names specific sibling tools like polymarket_edges, making its purpose clear and differentiated.

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

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

Provides explicit guidance: when to use no args (trending_scan), event mode (recommended for specific market with slug), and topic mode (cross-event scanning with seed question). Includes fill-check warning against trading if realizable_edge_pp ≤ 0, and directs custom sizing to sibling polymarket_fill_risk.

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

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

The description thoroughly discloses behavioral traits: model families, segments, diagnostics, caching (1h at KV level), edge calculation details, tradeable-edge knobs, and Fed handling. This goes well beyond annotations (readOnlyHint=true, etc.) and aligns with 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 very long and densely detailed, with structured sections but no bullet points. While every sentence adds value for a complex tool, it sacrifices conciseness; an agent may find it verbose.

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

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

Given the tool's complexity (9 parameters, no output schema, 3 segments), the description comprehensively covers return structure (edge_pp_net, kelly_fraction, diagnostics), caching, filters, and edge cases like Fed data and placeholder slugs.

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

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

All 9 parameters have schema descriptions (100% coverage), so baseline is 3. The main description adds context on how parameters like min_liquidity and max_spread_pp function as 'tradeable-edge knobs' and explains their interplay, providing marginal added meaning.

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

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

The description clearly states 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price', providing a specific verb and resource. It distinguishes from siblings by focusing on Pipeworx disagreement and is explicitly built for 'what should I bet on today'.

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

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

The description gives clear context for when to use the tool ('what should I bet on today' and 'discover opportunities without paging hundreds of markets'), but does not explicitly state when not to use it or mention 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 already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context beyond these: details on output structure (tracked, expired, snapshot_dates), limitations (60-day TTL, snapshot gaps), and behavioral notes (decay computed from daily closes, not intraday). 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 thorough but well-structured using sections (ARGS, RESPONSE, LIMITS). Every sentence provides necessary detail for a complex tool. Slightly long but justified by the information density.

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 completely explains the return value structure (tracked, expired, snapshot_dates with field details), covers edge cases (snapshot gaps, TTL, data currency), and is sufficient for an agent to understand what the tool returns and its limitations.

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

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

Schema coverage is 100% with descriptions for both parameters. The description reiterates defaults and constraints (days default 14, max 30; window default '1wk') but adds no new meaning beyond what the schema provides. Baseline of 3 is appropriate.

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

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

The description succinctly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It uses specific verbs ('Answers') and clearly distinguishes from sibling tools like 'polymarket_edges' by focusing on historical tracking.

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

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

The description explains the tool's use case ('how long has this edge existed and is it shrinking?') and provides a concrete example contrasting a fresh vs. 3-week-old edge. It implies when to use this over sibling tools but does not explicitly list alternatives or exclusions.

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

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

Annotations declare readOnlyHint and idempotentHint, and the description reinforces this by describing it as a check/analysis rather than a mutation. It adds behavioral details about partial fills, thin legs, and directional risk, which go beyond the 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?

The description is well-structured with clear sections for single-market, basket, and usage warning, but it is somewhat lengthy. Every sentence adds value, but a slight reduction in verbosity could improve conciseness while retaining 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, four parameters, no output schema), the description covers all necessary context: input parameters, return fields for both modes, behavior under thin books, and risk of partial fills. It is fully sufficient for an AI to decide when to use this tool and how to configure it.

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

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

Schema description coverage is 100%, and the description adds significant meaning: explains side defaults in both modes, interprets size_usd differently for single-market (spend/target) vs basket (settlement notional per leg), and clarifies market/event parameter usage. This is far beyond the schema's minimal 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 performs a realizable-vs-theoretical edge check against live order-book depth, with explicit distinction between single-market and basket modes. It lists specific return fields and use cases, making it highly distinguishable from siblings like polymarket_arbitrage and polymarket_edges.

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

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

It explicitly instructs to use this tool before acting on polymarket_arbitrage sell/buy-every-leg signals or polymarket_edges trades above ~$500, and explains the risks of not using it (uncapturable theoretical overround, directional risk from partial fills). This provides clear when-to-use and why.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds substantial behavioral detail: two modes, response structure (legs, spread, safety fields), temporal alignment considerations, and how skipped comparisons work. This goes well 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 fairly long but front-loaded with the main purpose. It uses section-like formatting (TWO MODES, RESPONSE, SAFETY FIELDS) for clarity. A bit verbose but every sentence adds value; could be slightly tighter.

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

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

No output schema is provided, so the description must explain return values. It does so thoroughly: covers spread calculations, compatibility_warning with two cases, temporal_alignment, skipped counters, and the caveat about pre-mapped topics. Complete for the tool's complexity.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds context: the 'topic' parameter lists the 10 macro shortcuts and explains that explicit parameters override the topic mapping. This adds practical 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?

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes the two modes ('topic' shortcuts vs explicit pairings) and differentiates from siblings like 'polymarket_arbitrage' (which may focus on a single venue).

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: comparing spreads on two venues for the same event. It also warns when not to trust the output via 'compatibility_warning' and explains that pre-mapped topics are often not tradeable. Alternatives are implied but not explicitly named.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds scoping details (anonymous IP, BYO key hash, account ID) and pairing info, providing extra 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?

Description is concise, informative, and front-loaded with purpose. 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?

For a simple tool with no output schema, description covers behavior (value retrieval or list), scoping, and pairing with other tools. Complete and clear.

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

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

Schema covers 100% of parameters. Description adds behavior: omitting key lists all keys, clarifying optionality. 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 retrieves a saved value or lists all keys, with specific verb+resource. It distinguishes from siblings (remember, forget) by name.

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 when to use: to look up previously stored context without re-deriving. Mentions scoping and pairing with remember/forget, providing good context. Lacks explicit when-not-to-use, but still 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?

Discloses mark_read side-effect, return payload structure, and alternative feed URL. However, annotations declare readOnlyHint=true while description describes a state-modifying operation (mark_read), creating a 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?

Concise with front-loaded purpose. Includes necessary details without excessive verbosity. Could be slightly tighter by removing the URL example if not needed.

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?

Explains return field details (source, citation_uri, raw payload) despite no output schema. Covers polling suitability and mark_read behavior. Could mention other potential fields like type or timestamp.

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

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

Adds examples for type filter ('sec_8k'), specifies ISO timestamp for since, and explains effect of mark_read. Schema already covers descriptions 100%, but description adds practical usage context.

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

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

Clearly states it pulls fired events from subscription feed, returns most recent alerts with specific fields (source, citation_uri, raw payload). Distinguishes from siblings like list_subscriptions by focusing on alerts with filtering and mark_read ability.

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

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

Describes when to use (get recent alerts, polling works fine) and provides alternative access via URL for scripts. However, does not explicitly compare with sibling tools or state when not to use this tool.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds significant behavioral detail: it fans out to multiple data sources, mentions the USPTO API sunset causing soft-fail, and describes fallback logic. 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 a single, well-structured paragraph that front-loads the purpose with query examples, then explains sources, parameters, and sibling differentiation. Every sentence adds value without fluff.

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

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

Given the tool's complexity (multi-source aggregation, parameter options) and lack of output schema, the description adequately explains return structure ('changes[] grouped by source + total_changes count + pipeworx:// citation URIs'). All necessary aspects are covered.

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

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

Schema coverage is 100%, and the description adds value by explaining that 'since' accepts ISO dates or relative shorthand (e.g., '7d', '30d', '3m', '1y') and that 'value' can be a ticker or CIK. This goes beyond the schema descriptions.

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

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

The description explicitly states the tool provides a change feed for a company across multiple sources (SEC, GDELT/GNews, USPTO) within a time window. It includes query examples like 'what's new with X' and clearly distinguishes from the sibling tool 'entity_profile' by stating when to use each.

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

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

The description provides explicit usage guidance with example queries and specifies when to use alternatives ('Use entity_profile instead when you want the static profile'). It also explains fallback behavior (GDELT preferred, GNews when rate-limited).

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

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

Discloses scoping by identifier, persistence duration differences between authenticated (persistent) and anonymous (24 hours), going beyond annotations that only indicate idempotent and non-destructive behavior.

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

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

Three sentences, front-loaded with purpose, each sentence adding value: purpose, usage, and additional tips. 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?

For a simple two-parameter tool with no output schema, the description covers purpose, usage, behavior, and parameter examples completely.

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

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

Schema already has 100% coverage with descriptions; the description adds examples for keys (e.g., 'subject_property') and values ('findings, addresses'), providing extra meaningful context.

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

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

The description clearly states the verb 'save' and the resource 'data' for reuse, distinguishing from sibling tools '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?

Provides specific examples ('resolved ticker, target address, user preference, research subject') and explicitly pairs with 'recall' and 'forget' for retrieval/deletion, giving clear usage context.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds that each call cascades through lookup endpoints internally and returns citation URIs, 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 with front-loaded examples, clear segmentation of supported types. Every sentence adds value; no redundancy.

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

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

No output schema, but description covers return values for both types. Explains internal cascading behavior. Parameters fully described. Adequate for the tool's complexity.

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

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

Schema has 100% coverage, but description adds substantial meaning: examples of values for company (ticker, CIK, name) and drug (brand/generic), and explicitly states what each type returns (ticker, CIK, company name; RxCUI, ingredient, brand).

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 it resolves names to identifiers, provides query examples, and distinguishes from siblings by positioning it as the first step when needing an ID. Lists supported types (company, drug) with specific outputs.

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?

Directly instructs 'Use FIRST whenever you have a name but need an ID.' Also details acceptable input formats for each type, helping agent decide when to invoke.

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 readOnly, openWorld, idempotent, and non-destructive hints. The description adds that it probes each entity with ai_visibility_check, ranks by score, and surfaces most/least recognized. It also describes the return format (ranked list with score, confidence, signal density per entity), providing valuable context beyond annotations.

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

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

The description is four sentences and front-loaded with the main action. Every sentence adds value: purpose, process, use case, output. No fluff.

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

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

The tool has 4 parameters and no output schema. The description explains the input parameters, internal process (calling ai_visibility_check), and output format (ranked list). It provides a complete picture for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning to parameters: 'models' explained as probe selection, '_apiKey' as optional for Anthropic, 'context' for disambiguation, and 'entities' as 2-8 items with first as subject. This adds significant value beyond the schema descriptions.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side. It uses specific verbs (compare, scan) and identifies the resource (AI presence). It distinguishes from sibling tools like ai_visibility_check by emphasizing multi-entity comparison.

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

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

The description explicitly states the use case: competitive AI-marketing audits, with an example question. It implies when to use (multi-entity comparison) but does not explicitly state when not to use or list alternatives, though the sibling tool ai_visibility_check is implied for single entities.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds behavioral details beyond annotations: partial failures degrade gracefully, bundlephobia timing (5-30s on first measurement), and that sources_failed will list timeouts. This exceeds what annotations 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 dense but well-structured, front-loading the core purpose. Each sentence adds necessary information: purpose, sources, use cases, ecosystem scope, behavior details, return format, and limitations. It avoids redundancy and is efficiently written for the complexity of the tool.

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

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

With no output schema, the description fully enumerates the return fields (summary block, per-advisory detail, links, alternative versions) and handles edge cases like partial failures and bundlephobia timing. This is comprehensive enough for an agent to understand the tool's full behavior and output.

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

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

Schema coverage is 100%, so the schema already documents parameters well. The description adds extra value: it confirms scoped packages are accepted for 'package' and explains that 'version' defaults to the latest published version. This provides practical guidance not in 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 composite purpose: checking npm packages across deps.dev and bundlephobia. It distinguishes from siblings by specifying 'NPM ecosystem only in v1' and referencing other tools for other ecosystems, making it easy to select correctly.

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

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

The description explicitly says 'Use whenever an agent asks "is X safe / popular / small"' and provides fallback guidance for non-npm packages. It also mentions bundlephobia timing caveats, giving the agent context for when to expect delays. However, it doesn't explicitly state when not to use it, leaving a minor gap.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that it returns images and metadata, which is useful but not critical. No contradictions.

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

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

Two sentences efficiently convey purpose and return values. No extraneous 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?

The description lists return fields but omits pagination details (e.g., total results, next page) and sorting or relevance behavior. Given no output schema, these gaps slightly reduce completeness.

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

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

The schema covers all parameters with full descriptions (100%). The description does not add any further meaning about parameters beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states it searches the Smithsonian Open Access collection by keyword, and specifies the return fields (ids, titles, creators, dates, image links). This distinguishes it from siblings like 'object' or 'search_within'.

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

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

The description implies usage for keyword search of the Smithsonian collection, and hints that if you have an id, you should pass it to the 'object' tool. However, no explicit when-not or alternatives are provided, leaving some ambiguity.

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

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

Beyond annotations (readOnly, idempotent, etc.), the description discloses embedding model (BGE-base-en), windowing (500-char overlapping), char cap (200K with truncation flag), and output details (offsets, similarity scores). No contradictions with annotations.

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

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

The description is concise (about 100 words) with front-loaded key action. Every sentence adds value—no fluff, no repetition of schema or annotations.

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

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

For a 3-parameter tool with full schema coverage and good annotations, the description covers purpose, usage, behavior, limits, and pairing advice comprehensively, leaving no significant 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 description coverage is 100%, and the description adds no new per-parameter details beyond the schema's existing descriptions. The description provides overall context but does not enhance parameter meanings further.

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, distinguishing it from general search tools like 'search' in sibling list. It specifies input (text and query) and output (passages with offsets and scores).

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

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

Explicitly advises use when records are too large for the prompt and mentions pairing with ask_pipeworx_grounded. However, it does not directly contrast with other sibling tools like 'search' or 'deep_research', leaving some ambiguity about when not to use.

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

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

Discloses important behaviors beyond annotations: requires OAuth account, returns subscription ID, delivery limitations (SMS cap, phone verification, webhook secret one-time, auto-disable after 10 failures). No contradiction with annotations; idempotentHint is consistent with creation.

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?

Well-structured with clear sections and bullet points. Front-loaded with the main action. Could be slightly more concise, but every sentence adds important detail.

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 return value (subscription id). Covers all prerequisites, limitations, and type-specific parameters. Complete for a subscription creation tool.

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

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

Schema coverage is 100% and already includes descriptions. The description adds value by providing concrete examples and additional constraints (e.g., sponsor or condition required for clinical_trial, SMS pattern) that are not in the schema descriptions.

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

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

The description clearly states it creates a proactive monitoring subscription, lists supported types and delivery channels, and mentions return of subscription ID. It distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on subscription 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?

Explicitly states requirement for Pipeworx OAuth account and that anonymous/BYO cannot persist. Lists types and delivery options, but does not explicitly exclude or compare to alternative ways to get alerts (e.g., polling). However, the context is clear enough for an agent to decide when to use this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds beyond that: it states the tool returns example questions with tool+argument shapes drawn from a live catalog, and explains behavior with and without the topic parameter. 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 somewhat long but well-structured: it starts with aliases/questions, then describes the output (category-bucketed examples with tool+argument shapes), and ends with usage guidance. Every sentence adds value; no redundancy. Could be slightly tighter but remains clear 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?

With only one optional parameter, no output schema, and rich annotations, the description covers all essential aspects: what the tool does, what it returns, how to use it with and without topic, and when to invoke it. No gaps are apparent for an onboarding tool.

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

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

The input schema has 100% coverage (description for topic). The description further adds meaning by listing possible topic values (finance, pharma, etc.) and explaining the effect of omitting it. This enriches the bare schema description.

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

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

The title and description clearly state the tool's purpose as an onboarding entry point. The description enumerates example questions (e.g., 'What can I ask Pipeworx?') and explains it returns category-bucketed examples with exact tool calls. It distinguishes the tool from siblings like ask_pipeworx and discover_tools by positioning it as the first tool to use when unfamiliar with the system.

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

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

The description explicitly advises to 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains when to use the optional topic parameter for focus. While it doesn't list explicit alternatives for when not to use it, the context of sibling tools and the 'FIRST' directive provide clear guidance.

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

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

Annotations already indicate idempotentHint=true, destructiveHint=false. The description adds context: deactivation (not deletion) and preservation of historical events via recent_alerts, which goes beyond annotations. No contradictions.

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

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

Two sentences, front-loaded with the action, ownership, and behavior. No wasted words; every sentence adds value.

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

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

The tool is simple with one parameter and no output schema. The description covers the effect, ownership, and side effect (historical events remain). This is complete for an unsubscribe operation.

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

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

Schema coverage is 100% with the 'id' parameter described as 'Subscription id (uuid) returned by subscribe.' The description adds no further parameter details, so baseline score of 3 is appropriate.

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

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

The description clearly states it cancels a subscription by id, specifies ownership enforcement and deactivation behavior, distinguishing it from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

The description explains when to use the tool (to cancel a subscription) and imposes an ownership constraint. It implicitly differentiates from subscribe/list_subscriptions but does not explicitly mention when not to use it.

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

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

Annotations provide safety and idempotency traits. The description adds value by explaining the verification process, return structure (verdict, structured form, citation, delta), and the SEC EDGAR + XBRL source. It could mention limitations like only US companies or financial topics, but implicitly does.

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?

Very efficient: front-loaded with examples, clear purpose, concise explanation of scope and output. Every sentence adds value with no redundancy.

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

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

For a single-param tool with no output schema, the description covers purpose, scope, and return values well. Missing error handling or data freshness notes, but overall 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 a single parameter 'claim' well-described. The description reinforces with examples, but adds little beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: verify natural-language claims against authoritative sources, specifically company-financial claims. It provides examples and distinguishes itself by replacing sequential calls.

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 whenever the agent needs to check whether something a user said is factually correct.' It sets clear scope for company-financial claims but does not explicitly list alternatives or when not to use it.

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