Sbir

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds that the default model is free, Anthropic requires a BYO key with direct payment, and returns per-model fields including score, confidence, signals, and raw_response. 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 four sentences, each providing essential information: action, default behavior, return structure, and use cases. No wasted words; well front-loaded.

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

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

Given no output schema, the description adequately explains the return format (per-model and combined view). All parameters are documented except that output schema is missing, but the description compensates. Could mention if results are cached, but not critical.

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

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

Schema description coverage is 100%, but the description adds value by clarifying the default model (Workers AI Llama-3.3-70b free) and that passing _apiKey enables Anthropic probing with direct payment. It also explains that context helps disambiguate common names.

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

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

The description explicitly states it probes LLMs for knowledge about an entity and scores visibility (0-100) per model. It clearly distinguishes from sibling tools like ask_pipeworx or deep_research by focusing on AI visibility scoring.

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 concrete use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It explains default vs. optional models and API key requirements. However, it does not explicitly state when not to use the tool or mention alternatives.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, clearly indicating a safe read-only operation. The description adds context that it returns structured answers with stable pipeworx:// citation URIs and that it works on every tier in one fast call. No contradictions.

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

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

The description is long but well-structured, with each sentence serving a purpose. The front-loading is effective: it starts with the key directive to prefer over web search. A slight deduction for length, but the content earns its place.

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

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

Given the tool's complexity (routes to 5,564 tools), few required parameters, and no output schema, the description is remarkably complete. It explains the tool's scope, behavior, alternatives, and provides numerous examples, 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%, so the baseline is 3. The description adds value by explaining that the tool accepts natural language questions and provides many example questions, though it doesn't detail every parameter beyond the schema (which is sufficient).

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

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

The description clearly states that ask_pipeworx routes questions to a vast set of verified sources for authoritative structured data with citations, covering many domains. It explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research 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 when-to-use guidance, stating it should be preferred over web search for factual questions. It also lists alternatives and when to use them: ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad multi-part questions, and indicates where it falls short (breaking news, 'what's the world saying') with a note about live news routing.

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 strong safety signals (readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=true). The description adds useful context about the routing experiment lifecycle and current state (no candidate active), but does not disclose any other behavioral traits or edge cases. Score is appropriate as annotations already cover 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 appropriately concise for a beta tool that mirrors a stable sibling. It front-loads the name, purpose, and key difference, then adds operational context. The last sentence about fallback is slightly redundant given the earlier clarity, but overall effective.

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

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

Given the tool inherits most context from ask_pipeworx and has no output schema, the description covers the experimental purpose, current behavior, and usage guidance. Minor gap: no mention of rate limits or stability expectations for a beta tool, but the openWorldHint and readOnlyHint annotations compensate.

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

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

With 100% schema description coverage, the schema already documents the 6 parameters effectively. The description adds clarity by confirming the tool as a universal router accepting natural language questions, and by noting that the response shape is identical to ask_pipeworx, which adds value beyond schema for the agent to infer expected behavior.

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 this is a beta version of ask_pipeworx, an identical universal router with 5,564 tools. It explicitly distinguishes from the sibling tool 'ask_pipeworx' (stable router) by explaining the routing improvement candidate testing purpose.

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

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

The description explicitly states when to use it ('when you want the newest routing'), clarifies current behavior (no active candidate, matches stable exactly), and implies no alternatives needed for experimental routing. It also explains the fallback behavior and comparison-to-stable 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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds significant behavioral context: it uses the same routing as ask_pipeworx, performs an extra LLM call, returns a structured response with evidence and refusal reasons, and only uses the tool result. No contradictions with annotations. The description fully discloses the tool's behavior and limitations.

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

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

The description is well-structured, starting with the core concept ('Hallucination-resistant answer mode'), then explaining the mechanism, return format, use cases, and trade-offs. It is dense but every sentence adds value. Slightly longer than minimal but still efficient. Not a tautology or waste.

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

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

Despite having no output schema, the description provides a detailed return format including success and refusal cases. The 6 parameters are fully covered by the schema. The description explains the tool's routing, cost, and use cases comprehensively. Given the complexity (high-stakes queries, refusal reasons, sibling differentiation), the description is complete enough for an agent to use correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add any meaning beyond what the schema already provides for the parameters. The schema itself describes the 'question' parameter and its aliases. The description repeats 'Your question in natural language' but adds no new semantics. With full schema coverage, no extra value is needed.

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: 'Hallucination-resistant answer mode for high-stakes reads.' It distinguishes itself from the sibling 'ask_pipeworx' by specifying that it extracts the answer using only the tool result, and it returns explicit refusals when data doesn't directly answer. The verb 'ask' combined with 'grounded' and the detailed explanation makes the specific verb+resource+mode clear.

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

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

The description explicitly states when to use this tool: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts (financial verdicts, legal claims, medical lookups, public statements).' It also provides an alternative: 'prefer ask_pipeworx for casual lookups' and notes the cost trade-off ('Costs one extra LLM call vs ask_pipeworx'). This is exemplary guidance.

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

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

The description extensively discloses behavioral traits beyond annotations: it explains resolver contract, parent_event extraction, news fallback, safety short-circuits, closed market handling, wide spread indicators, and resolution rule risk. Annotations (readOnlyHint, openWorldHint, etc.) align with description, 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 comprehensive but verbose, spanning multiple paragraphs. It uses headings effectively and front-loads the main purpose, but could be more concise. Every sentence adds value, but overall length reduces 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 tool's complexity and no output schema, the description thoroughly explains expected responses, edge cases, and resolution mechanisms. It covers all necessary contextual details for an agent to correctly invoke and interpret results.

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

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

Schema coverage is 100% and the description provides examples but does not add significant new meaning beyond the schema's descriptions. The parameter details are reinforced but not expanded, so baseline 3 is appropriate.

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

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

The description starts with a clear verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It covers multiple input types and explicitly states the tool's purpose, distinguishing it from siblings by its comprehensive functionality.

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 direct usage scenarios: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides examples and covers edge cases, but does not explicitly compare to sibling tools, which would enhance differentiation.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. Description adds specifics: SEC EDGAR data for companies (including fiscal year handling), FAERS/FDA data for drugs, and sorted results. Provides more context than annotations alone.

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 front-loaded with natural language examples and packed with useful details. While dense, every sentence adds value. Could be slightly more concise, but well-structured.

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

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

Given no output schema, description covers input format, behavior (including edge cases like fiscal years), and expected output (paired data + citation URIs). Comprehensive for the tool's complexity and rich annotations.

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

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

Schema has 100% coverage with descriptions. Tool description adds further meaning: explains what data each enum value pulls and how to populate the values array (tickers/CIKs for company, names for drug). Enhances usability beyond schema.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 entities (companies or drugs) and provides specific query examples. It distinguishes from sibling tools like entity_profile by emphasizing parallel lookups over sequential.

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

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

Explicitly says to prefer this tool over sequential single-pack lookups when comparing entities. Provides trigger phrases. Lacks explicit exclusions but gives strong contextual guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds substantial behavioral context beyond these: it clarifies that the tool does not perform open-web search, returns structured findings with verbatim evidence, confidence, sources, fetched_at, and stable citations; that large records are semantically excerpted; that standard and thorough depths include contradictions detection; and that latency ranges are 15-90s. No contradictions with annotations exist.

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

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

The description is long but well-structured, with front-loaded prerequisites and alternatives. Every sentence adds useful information; however, some details (e.g., exact counts of data sources and tools) are precise but could be omitted for brevity. The overall organization and clarity justify a high score, but there is slight room for trimming.

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

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

Despite lacking an output schema, the description fully explains the return format: a findings packet with verbatim evidence, confidence, source, fetched_at, stable citations, gaps array, hop field, contradictions (for standard/thorough), and citation_uri condition. It also covers expected latency, depth behavior, and the account prerequisite. This is a complete and self-contained description for a complex research tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining the depth parameter's behavior in detail (e.g., standard adds gap-recovery hop + contradictions, thorough adds iterative lead chasing) and clarifying that the question parameter accepts broad/multi-part queries because decomposition is the tool's purpose. These additions raise the score above baseline.

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

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

The description clearly states the verb ('research') and resource ('Pipeworx's 1462 STRUCTURED data sources'). It explicitly distinguishes from siblings by noting that deep_research is for broad/multi-part questions over structured data, while ask_pipeworx is for single lookups, and that it is not open-web search. The purpose is specific and well-differentiated.

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

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

The description provides explicit guidance on when to use: 'Best for broad/multi-part questions over structured data'. It also states when not to use: for single lookups use ask_pipeworx, and for breaking news prefer ask_pipeworx. It further notes the account requirement for deep_research and that 'thorough' depth needs a paid plan, advising to use ask_pipeworx if not signed in. This is comprehensive usage advice.

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds that it returns top-N relevant tools with names, descriptions, full input schemas, and curated examples, ready to call directly. Provides concrete behavioral details 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 efficient: purpose stated first, then usage context, then return value details. No redundant sentences. 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?

For a discovery tool with no output schema, description fully explains what the agent can expect: names, descriptions, schemas with examples, and that results are directly callable. Complete for agent decision-making.

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 aliases documented. Description adds that 'query' is a natural language description and gives examples. This adds meaning beyond the schema's basic property descriptions.

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

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

Description clearly states 'Find tools by describing the data or task' with specific verb and resource. Distinguishes from siblings by being a meta-discovery tool, not a specific data retrieval tool.

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

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

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

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds that it fans out across multiple sources in one parallel call, returns specific fields, and notes that patents may soft-fail due to API sunset. This provides useful behavioral context beyond annotations.

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

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

Description is front-loaded with example queries, then explains purpose and return fields. Every sentence adds value, though slightly verbose in listing return fields. Generally well-structured.

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

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

Given complexity of multi-source data and no output schema, description thoroughly explains what the tool returns (cik, filings, fundamentals, patents, news, LEI) and limitations (patent soft-fail, name unsupported). Sufficient for an agent to understand tool behavior.

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

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

Schema descriptions already cover both parameters with 100% coverage. The description reinforces that names are not supported and directs to resolve_entity, adding usage context that helps the agent choose correct input format.

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

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

Description clearly states the tool provides a full cross-source profile of a US public company, with specific examples like 'brief me on Tesla'. It distinguishes from sibling tools like resolve_entity and compare_entities by explicitly saying to prefer over chaining single-pack lookups.

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

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

Explicitly says when to use: when user asks for a holistic view, ALWAYS PREFER over chaining. Also states when not to use: if only a name is provided, use resolve_entity first. This is clear and actionable 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 destructiveHint=true; description reinforces with 'delete' and 'clear sensitive data', adding context beyond structured fields without contradiction.

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

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

Three concise sentences front-loaded with action and resource, no unnecessary words.

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

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

Given single parameter, no output schema, and rich annotations, the description covers usage scenarios and pairing advice, making it fully adequate.

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

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

Schema coverage is 100% with description for 'key'; description adds minimal extra meaning beyond 'by key', so 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 uses a specific verb 'Delete' and resource 'memory by key', clearly distinguishing it 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?

Explicitly states when to use the tool (stale context, task done, clear sensitive data) and advises pairing with related 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 already declare readOnlyHint, idempotentHint, and destructiveHint, so the description's job is lighter. The description adds that it 'Fetches the page, extracts title/description/key links', which provides basic behavioral context. However, it does not detail error handling, rate limits, or edge cases like invalid URLs, leaving gaps.

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 extremely concise: two sentences that front-load the core functionality and then list use cases. Every word earns its place with no redundancy or filler.

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

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

Given the tool's simplicity (2 params, no output schema), the description covers the essential context: input format, output format, and typical use cases. It does not mention error handling or limitations, but for a straightforward read-only tool this is acceptable.

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 bar for adding meaning is higher. The description repeats the schema's default/max for 'max_links' and provides an example for 'url' but adds little semantic depth 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 action ('Generate a production-ready llms.txt file'), the target resource ('any URL'), and the outcome ('emits the standard llms.txt markdown format'). It also provides specific use cases, making the tool's purpose unambiguous and differentiating it from siblings.

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

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

The description lists explicit use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), giving clear context for when to use. However, it does not explicitly mention when not to use or compare to alternatives like 'ai_visibility_check' or 'scan_competitor_ai_presence', which would improve guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds that it returns specific fields and defaults to active subscriptions, which is 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?

Three short sentences: first defines purpose and outputs, second provides usage context, third is optional. No wasted words, information is front-loaded.

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

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

For a simple list tool with no required parameters, no output schema, and comprehensive annotations, the description covers what it does, what it returns, and when to use it. Completeness is high.

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

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

Only one optional parameter (include_inactive) is fully described in the input schema (100% coverage). The description does not repeat or add new meaning to the parameter, 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 lists the caller's active subscriptions and specifies the returned fields (id, type, params, etc.). It distinguishes from sibling tools like subscribe/unsubscribe.

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

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

Explicitly recommends using this tool to review current monitoring before adding more subscriptions or to find an id to cancel, providing clear when-to-use guidance.

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

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

Annotations are all false, so the description carries full responsibility for behavioral disclosure. It reveals the claim_token workflow, daily digest reading, rate limit of 5/day, free/no-quota impact, and instructs users not to paste end-user prompts. This goes well beyond basic safety hints and provides rich operational context.

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

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

The description is dense and information-rich, with a logical flow: purpose, usage, exclusions, token workflow, and limits. It's a single long paragraph, which could be slightly harder to scan than bulleted points, but every sentence adds value and there is no filler.

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

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

Despite having no output schema, the description explains what happens when filing without an account (claim_token), how to check resolution status, and what the team does with feedback. Nested object context is covered by the schema, and the description gives concrete framing guidance. Complete for a feedback tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds valuable parameter semantics by demonstrating the claim_token round-trip pattern ('pipeworx_feedback({claim_token:"pwfb_…"})') and explaining that context should describe issues in terms of Pipeworx tools/packs. It doesn't quite reach 5 because the schema already provides solid descriptions for each field.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses a specific verb+resource pattern and includes the types of feedback (bug, feature/data_gap, praise), making it easily distinguishable from sibling tools like ask_pipeworx or 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 gives explicit when-to-use guidance: use for bugs, missing features, data gaps, or praise. It also explicitly states when NOT to use it: for tools from a different MCP server, and tells users to file with that server instead. This is exemplary alternative/contextual guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by noting the data is self-aggregating, derived from CF analytics-engine, no PII, and cached 5min-1h. This goes 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 efficient with about 6 sentences and uses bullet points for use cases. It is front-loaded with the main purpose. Minor redundancy (e.g., 'hot for current events' could be condensed), but overall well-structured.

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

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

For a simple tool with one optional parameter and no output schema, the description covers purpose, behavior, caching policy, privacy, and use cases. No gaps remain.

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

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

Schema coverage is 100% with one enum parameter and description. The description adds context that shorter windows surface what's hot while longer windows show steady-state demand, which aids selection 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 returns top tools, top packs, and total call volume over a window. The verb 'what other AI agents are calling' combined with 'Pipeworx trending' makes the purpose specific and distinguishable 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 provides three explicit use cases: discovering hot data sources, confirming canonical tools, and seeing alignment. It does not explicitly exclude when not to use, but the use cases cover common scenarios, giving the agent 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 declare readOnlyHint, openWorldHint, idempotentHint, and no destructiveness. The description significantly adds behavioral context: explains monotonicity violations, partition checks, semantic anchor (Jaccard similarity threshold), partition filter (placeholder fraction), fill check (pricing against CLOB depth), and when not to trade (realizable_edge_pp ≤ 0). No contradictions with annotations.

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

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

The description is detailed and well-structured with clear sections for each mode, semantic anchor, partition filter, response, and fill check. Every sentence adds value, though it is longer than necessary for simpler tools. For the complexity (two modes, multiple checks), it is appropriately sized and front-loaded with the purpose.

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

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

Despite no output schema, the description fully explains the return structure: 'opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context)' and partition_check details for event mode. It covers inputs, behavior, fill check, and tradeability conditions. No gaps remain.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra meaning: for 'event', it provides example slugs and explains it walks child markets; for 'topic', it gives example seed questions and describes cross-event scanning. This adds value beyond the schema's concise 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 starts with a clear verb-object pair: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It specifies the resource (Polymarket arbitrage) and method, distinguishing it from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicitly states when to use each mode: 'Call with NO args for a trending_scan', 'pass event for per-event partition_check', and 'topic for cross-event scan'. Recommends event mode for specific markets and explains cross-event catches patterns single-event misses. Lacks explicit when-not-to-use versus other arbitrage tools, but guidance is clear.

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

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

Annotations declare read-only, open-world, idempotent, non-destructive. Description adds substantial behavioral context: three model families, caching (1h at KV level), diagnostics for empty segments, Kelly fractions, slippage handling, and tradeable-edge knobs. 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 a single dense paragraph over 500 words. While front-loaded with purpose, the wall of text harms readability. Bullet points or sections would improve. Not concise.

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

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

With 9 parameters, no output schema, and complex output structure (segments, diagnostics), the description fully compensates. Explains each segment, output fields (edge_pp_net, kelly_fraction, etc.), Fed bets handling, and filter knobs. Very 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?

All parameters have schema descriptions (100% coverage). Description adds value beyond schema: explains slippage_pp rationale, min_partition_leg_kelly behavior, and tradeable-edge filter usage. Baseline 3, elevated 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?

Specific verb 'scan' and resource 'Polymarket markets', clear output 'opportunities where Pipeworx data disagrees with market price'. Distinguishes from siblings by focusing on edge detection. Built-for statement ('what should I bet on today') clarifies use case.

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

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

Description provides context: 'agents discover opportunities without paging hundreds of markets'. Includes all filters and explains Fed bets exclusion. No explicit when-not-to-use or alternative sibling tool references, but overall guidance is strong.

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

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

Annotations already indicate readOnly, openWorld, idempotent. Description adds rich behavioral detail: snapshot TTL limitations, snapshot gaps, decay computed from daily closes, and response structure. 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?

Description is front-loaded with the key question and is information-dense. Every sentence adds value, though slightly lengthy for a tool with only two parameters. Could be tightened but still efficient.

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

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

Given no output schema, the description fully explains the three response arrays and their fields, plus limitations (60-day TTL, daily closes). Annotations cover safety, and behavioral details are 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%. Description repeats default and range for 'days' and 'window' family, and adds significant value by explaining the response fields (tracked, expired, snapshot_dates) and how parameters affect them.

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

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

Description states it tracks edge persistence and decay from daily snapshots, answering 'how long has this edge existed and is it shrinking?' It distinguishes itself from siblings like polymarket_edges by focusing on historical tracking rather than live 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?

Clear context on when to use: differentiate between fresh and aged edges. Does not explicitly list alternatives but the description implies usage for historical edge analysis. No explicit when-not-to-use, but context is strong.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds behavioral details: walks the ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict) and explains basket behavior including thin_legs and forced_directional_risk. No contradiction with annotations.

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

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

The description is well-structured with caps for key terms and clear sections (SINGLE-MARKET, BASKET). While dense, every sentence adds value. Slightly verbose but justified for complexity.

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

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

Despite no output schema, the description thoroughly covers both modes, return fields, edge cases (thin legs, directional risk), and usage rationale. Complete for a complex tool with risk warnings.

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 extra meaning: explains side default and auto-detection for basket, size_usd interpretation difference between single and basket modes (settlement notional), and clamping range. This goes beyond the schema alone.

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

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

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It differentiates from siblings like polymarket_arbitrage and polymarket_edges by focusing on pre-trade risk assessment.

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 when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Explains the risks of partial fills converting arb into directional positions, providing clear exclusion criteria.

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

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

The description adds significant behavioral context beyond the annotations, including the two modes, response structure, safety fields (compatibility_warning, temporal_alignment, skipped_cross_type), and caveats about when spreads are meaningful. It does not contradict annotations and provides transparency about the tool's limitations.

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 purpose, but it is quite lengthy due to detailed explanations of modes, response fields, and safety warnings. Each sentence adds value, but the length could be slightly reduced without losing clarity.

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

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

Given the tool's complexity and the absence of an output schema, the description thoroughly explains the response structure, including leg-by-leg prices, spreads, and safety fields. It also covers when spreads are meaningful and when compatibility warnings appear, making it self-sufficient for an agent to understand and invoke correctly.

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

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

While the schema already provides descriptions for the three parameters with 100% coverage, the description adds meaningful context by explaining the purpose of the 'topic' parameter as a set of pre-mapped shortcuts and how explicit parameters override the topic. This additional context improves understanding beyond the schema alone.

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

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

The description clearly states the tool's purpose as computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes this tool from siblings by specifying the cross-venue comparison, and the description details two modes (topic and explicit) making it easy to understand what the tool does.

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

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

The description provides clear guidance on when to use the tool, such as for comparing prices across venues and notes that compatibility warnings indicate when spreads are not meaningful. However, it does not explicitly mention alternative tools or when to avoid using this tool in favor of others.

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, idempotentHint, destructiveHint. Description adds scoping detail ('Scoped to your identifier...') and pairing with remember/forget. No contradictions.

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

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

Three concise sentences, each with a distinct role: core action, use cases, and additional context (scoping + pairing). No wasted words, front-loaded with the primary function.

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

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

For a simple tool with one optional parameter and no output schema, the description covers purpose, usage, and behavioral details sufficiently. It is complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100% with description for 'key'. The description adds the behavior of omitting key to list all keys, which aligns with the property description and provides a clear usage pattern.

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

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

Description clearly states the verb ('retrieve' or 'list') and resource ('value previously saved via remember' or 'all saved keys'). It explicitly distinguishes two modes and references sibling tools 'remember' and 'forget'.

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

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

Provides concrete use cases ('user's target ticker, an address, prior research notes') and explains when to use: 'without re-deriving it from scratch'. Does not explicitly state when not to use, but context is clear.

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

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

Adds value beyond annotations by detailing the mark_read side effect ('flag returned events read so the next call only shows newer ones') and confirming polling is acceptable. Does not contradict annotations (readOnlyHint, idempotentHint, destructiveHint).

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?

Compact yet informative; front-loads purpose and return fields, then filters, then behavior. Uses a single sentence with semicolons, which is efficient but could be slightly more structured for quick scanning.

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

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

Covers return fields, filtering, mark_read behavior, polling suitability, and alternative access method. Missing details on error handling or edge cases but sufficient for an alert-retrieval tool with no 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?

Enriches schema descriptions with examples (e.g., 'sec_8k' for type, ISO timestamp for since) and clarifies usage of mark_read and unread_only. Schema coverage is 100%, but description provides additional actionable 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?

Explicitly states the action ('Pull fired events') and the resource ('from your subscription feed'), with specific return fields (source, citation_uri, raw event payload). Clearly distinguishes from sibling tools like list_subscriptions by focusing on retrieving events rather than managing subscriptions.

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

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

Provides usage context (filtering by type/since, marking read) and mentions an alternative direct API endpoint for scripts/dashboards. However, does not explicitly contrast with other sibling tools (e.g., when to use this vs. subscribe or list_subscriptions), though the purpose is clear.

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

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

Annotations already declare safe, non-destructive, idempotent behavior. The description adds value by detailing the multi-source fan-out, fallback mechanism, and output structure (changes[] grouped by source + total_changes + citation URIs). No contradiction with annotations.

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

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

Single paragraph, front-loaded with user-facing query examples. Every sentence adds essential information. No redundancy or 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?

Despite no output schema, the description explains return fields and grouped structure. It covers all 3 required parameters thoroughly, including fallback behavior and limitations (USPTO soft-fail). 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%, and the description enriches each parameter: 'type' is limited to 'company', 'since' accepts ISO or relative shorthand with examples, 'value' can be ticker or CIK. It adds practical tips beyond schema.

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

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

The description clearly states it provides a change feed for a company, listing example queries like 'What's new with X' and specifying the data sources (SEC EDGAR, GDELT→GNews, USPTO). It directly distinguishes from the sibling tool 'entity_profile', so the agent can differentiate.

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

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

Explicit guidance is given: when to use (recent changes) and when not (use entity_profile for static profile). It explains fallback behavior (GDELT→GNews) and provides recommendations for the 'since' parameter ('Use "30d" or "1m" for typical monitoring').

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 idempotentHint=true, destructiveHint=false, readOnlyHint=false. Description adds behavior details: key-value scoped, authenticated vs anonymous persistence (24h). No contradictions.

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

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

Three sentences, front-loaded with purpose, no fluff. Every sentence adds value (purpose, usage guidance, behavioral 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?

For a simple key-value store with no output schema, the description covers purpose, usage, behavior, and pairing with sibling tools. Complete context for the agent.

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

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

Schema provides 100% coverage with clear descriptions for both 'key' and 'value'. Description reinforces with example key patterns (e.g., 'subject_property') but adds limited new meaning beyond schema.

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

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

Description clearly states 'Save data the agent will need to reuse later' and gives concrete examples like 'resolved ticker', 'target address', 'user preference'. It distinguishes from siblings by explicitly pairing with 'recall' and 'forget'.

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

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

Explicitly says when to use: 'when you discover something worth carrying forward'. Provides context for alternative tools (recall, forget) and mentions scope (by identifier, persistent vs 24h).

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds significant behavioral context beyond these: it discloses graceful degradation when GLEIF/OpenFIGI are unavailable ('LEI/FIGI enrichment degrades gracefully'), explicitly reveals that unresolved identifiers appear under 'unresolved' rather than being omitted, and notes that identifiers are labeled with their source. This goes well beyond the annotations and gives the agent a clear mental model.

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 densely packed with valuable information but is overly long as a single paragraph, mixing examples, behavioral details, and type-specific logic. It is front-loaded with a purpose statement and usage directive, but the verbosity delays the core message and could overwhelm an agent parsing it. A more structured layout (bullets for supported types) would improve readability.

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

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

Given the tool's complexity (multiple identifiers, fallback behavior, cross-source resolution) and the absence of an output schema, the description explains return values in detail: identifier names, source labels, the 'unresolved' field, and enrichment failure handling. It also covers edge cases like ISIN-to-LEI mapping and non-US issuers, making it virtually complete for an agent to invoke correctly.

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

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

Although the schema already covers both parameters with 100% description coverage, the tool description adds substantial nuance: it expands the accepted input for company to include ISINs (with the ISIN-to-LEI mapping behavior), explains what 'value' means for each type, gives example inputs (AAPL, 0000320193, 'ozempic'), and describes the output structure for drug lookups. This enriches the parameter semantics considerably beyond the schema's basic text.

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

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

The description clearly states the tool's purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It explicitly lists supported entity types (company, drug) and the identifiers returned (CIK, ticker, LEI, FIGI, RxCUI), distinguishing it from sibling tools by emphasizing it outputs IDs that other tools consume. The 'Use FIRST whenever you have a name but need an ID' directive further sharpens its specific role.

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: 'Use FIRST whenever you have a name but need an ID.' It also gives concrete user-phrase examples ('What's the ticker for...') that signal the input type, and mentions that it 'replaces 2-3 manual lookups,' clarifying the intended use case compared to alternatives like direct lookups or other entity 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 already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive, so the description need not restate safety. The description adds no extra behavioral detail beyond that; the page-cap caveat ('award_count_at_least') appears only in the parameter schema, not the main description. 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 two concise sentences: the first states the core purpose, the second explains parameter usage with examples. No filler or redundant content, front-loaded with the primary action.

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

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

For a simple read-only stats tool with one optional parameter, an output schema, and full annotations, the description adequately sets expectations. It could mention the page-cap behavior for context, but that is already captured in the parameter schema, so overall 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% for the single 'agency' parameter, so the baseline is 3. The description repeats examples already present in the schema and does not add new semantic depth. The schema itself provides the 'DOW' (formerly DOD) detail and the page-cap caveat, so the description adds little beyond the structured data.

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 'Get SBIR/STTR award counts by agency' using a specific verb and resource. It distinguishes itself from sibling tools like sbir_search_awards or sbir_company_awards by focusing on counts by agency, and gives concrete examples ('DOD', 'NASA', 'NSF').

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

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

The description provides clear context for when to use the tool: to get counts by agency, with guidance to specify an agency or omit to see all major agencies. It does not explicitly mention alternatives or exclusions, but the purpose is distinct enough 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?

The description claims to return 'all awards' and calls it 'complete history,' but the schema includes a limit parameter with a default of 50, suggesting the result may be truncated by default. This is a significant behavioral discrepancy. Annotations (readOnlyHint, idempotentHint) cover safety, but the description undermines trust by overpromising completeness without addressing pagination or limits.

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

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

The description is a single sentence, front-loaded with the verb 'Get,' and efficiently communicates the core function and expected output fields. No filler or redundant information is present.

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?

An output schema exists, so return values need no further explanation. However, the description omits critical details about the limit parameter's effect on 'completeness' and does not mention pagination strategies. This is a notable gap for a tool that promises 'complete award history,' despite good annotations and schema coverage.

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

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

Schema description coverage is 100% for both parameters (company and limit), so the description adds minimal parameter-level meaning. It does not clarify how to achieve a truly complete history despite the 'all awards' claim, which would be valuable. The baseline of 3 applies since the schema handles parameter documentation.

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

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

The description clearly states the tool's function: 'Get complete SBIR/STTR award history for a company' with specific return fields (amounts, agencies, topics, funding phases). The verb 'Get' and resource 'award history' are precise, and the company-specific scope distinguishes it from sibling search tools like sbir_search_awards.

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 the tool is for retrieving a company's full award history, which is a clear usage context. However, it does not explicitly name alternatives (e.g., sbir_search_awards) or state when not to use this tool, so it falls short of a full 5. The company-focused input makes the primary use case evident.

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

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

Annotations already indicate a safe, read-only, idempotent operation. The description adds valuable behavioral context beyond that: it reveals that there is no direct lookup endpoint and that the tool performs a search and verification under the hood. This helps set expectations about performance and potential failures. A minor gap is not mentioning what happens if the identifier is not found, but the output schema likely covers that.

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

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

The description is two sentences, front-loaded with the primary purpose and immediately followed by critical usage guidance. Every word is purposeful; no filler or redundancy.

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

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

For a single-parameter, read-only tool with an output schema, the description is complete. It explains the identifier, the lack of a direct lookup endpoint, the need to start from sbir_search_awards, and the verification behavior. The output schema handles return expectations, so nothing else is needed.

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 reinforces the meaning of award_id as a contract number or agency tracking number and emphasizes that it must match the fields from sbir_search_awards, but it does not add new semantic detail beyond the schema's own description. The added context about verification is more behavioral than parameter-focused.

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

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

The description clearly states the verb ('Get full details') and the resource (one SBIR/STTR award), and it distinguishes itself from siblings by specifying the identifier type and the fact that it searches and verifies rather than directly looking up. It explicitly references sbir_search_awards as the source for the identifier.

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

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

The description gives explicit when-to-use guidance: start from sbir_search_awards rather than guessing an id. It also explains why (no lookup-by-id endpoint) and that the tool searches and verifies the identifier, which effectively tells the agent that this tool is for getting details after a search, not for initiating a search.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and openWorld behavior. The description adds useful context beyond annotations by clarifying these are awarded grants ('an agency has already funded') and explaining the DOD/DOW translation in the schema. It does not contradict any annotation.

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

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

The description is efficiently structured: leading examples, then a clear definition of what it searches, then parameter summary, return fields, and an explicit sibling-tool distinction. Every sentence contributes value and nothing is wasted.

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

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

For a search tool with an output schema present, the description is complete: it covers use cases, available filters, return fields, and the distinction from the solicitations tool. Combined with the annotations and schema, the agent has all necessary context to select and invoke the tool.

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

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

The input schema has 100% parameter description coverage, so baseline is 3. The description's prose lists the searchable fields (keyword, agency, year, company, state) but does not add meaningful semantics beyond what the schema already provides. Examples exist in the schema but not in the description itself.

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

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

Description clearly states the tool searches awarded SBIR/STTR grants, using a specific verb ('Search') and resource ('federal small-business R&D money'). It distinguishes itself from the solicitation tool by explicitly saying this is for who WON funding versus open opportunities.

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

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

Provides explicit guidance on when to use this tool and when not: 'This is the tool for who WON federal small-business R&D money and how much; for opportunities still open to bid use sbir_search_solicitations.' This clearly directs the agent to a sibling tool for the alternative use case.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds useful context about what the tool returns (topic descriptions, agency, Phase, dates) and clarifies that it covers open opportunities, going beyond the annotation-only safety profile without contradicting it.

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

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

The description is slightly verbose with the example queries, but they serve as useful intent-matching signals. It is front-loaded and each section has a purpose; a modest trim could improve conciseness without losing value.

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

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

For a search tool with an output schema and comprehensive annotations, the description fully covers the tool's scope, return fields, filtering dimensions, and even sibling differentiation. There are no critical gaps in context for an agent to select and invoke it correctly.

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

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

Schema coverage is 100%, so the parameters are already well-documented. The description adds a bit of extra flavor by naming example agencies like DARPA and mentioning keyword/agency usage, but it doesn't meaningfully extend the schema's parameter definitions. Baseline 3 is appropriate.

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

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

The description uses a specific verb+resource+scope: searches active SBIR/STTR solicitations by keyword or agency, and clearly lists returned fields. It explicitly distinguishes itself from the award-search sibling tool, making its purpose unambiguous.

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

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

Provides clear usage context with natural language examples ('Which SBIR or STTR solicitations are open at [agency]?') and explicitly states when to use this tool versus sbir_search_awards for won funding. This direct alternative guidance is exactly what's needed.

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 non-destructive. The description adds that it probes each entity with ai_visibility_check, ranks by score, and returns per-entity metrics. It also notes the _apiKey requirement for Anthropic. No contradictions.

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

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

Three sentences: first states main function, second explains mechanism, third gives use case and output. No wasted words, front-loaded.

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

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

For a tool with 4 parameters and no output schema, the description adequately covers input (entities, models, context, apiKey), process (probes with ai_visibility_check, ranks), and output (ranked list with score, confidence, signal density). The schema already notes 2-8 entities. No obvious 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?

With 100% schema coverage baseline of 3, the description adds value: it explains that the first entity in the array is treated as the 'subject' for narrative, and the context parameter disambiguates common names. These details are 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 compares AI visibility across multiple entities side-by-side, using ai_visibility_check internally, ranking, and surfacing most/least recognized. It distinguishes itself from single-entity tools like ai_visibility_check.

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

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

The description provides a clear use case ('competitive AI-marketing audits') with an example question. It implies when to use this over ai_visibility_check (multiple entities vs. single). However, it does not explicitly exclude cases or name alternatives like compare_entities.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, so the description focuses on additional behavioral traits: fan-out across deps.dev and bundlephobia, partial failure handling, and timing details (bundlephobia first measurement 5-30s). 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 substantial but every sentence is informative. Front-loading the composite nature and use case helps recognition. Minor redundancy (e.g., 'NPM ecosystem only') could be trimmed, but overall efficient for 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?

For a non-destructive, read-only tool with only 2 parameters and no output schema, the description covers return fields, behavior on partial failure, timing caveats, and ecosystem scope. It leaves no gaps for typical usage scenarios.

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

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

Schema coverage is 100% with clear descriptions. The description adds value by explaining scoped packages for 'package' and default behavior for 'version' (latest). A slight improvement over baseline 3.

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

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

The description clearly states it performs a composite check for npm packages covering license, advisories, version history, and bundle size. It uses specific verbs ('scan', 'fans out') and distinguishes from siblings by specifying the composite nature and ecosystem limitation.

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 use when questions about package safety, popularity, or size arise ('is X safe / popular / small') and quantifies cost ('what does adding lodash cost me'). It also notes ecosystem limitations and provides an alternative for other package managers.

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, openWorld, idempotent), the description discloses the embedding model (BGE-base-en), chunking (500-char overlapping windows), similarity measure (cosine), and truncation behavior (200K cap with flag). These details help the agent understand behavior and limitations.

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: action, usage guideline, technical detail. No fluff. Front-loaded with the core action. Every sentence serves a purpose.

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

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

The description explains the return format (passages with offsets and scores) despite no output schema. It also mentions pairing with a sibling tool. However, it doesn't specify ordering of passages or score ranges, which could add more completeness.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by giving concrete examples for 'text' (e.g., SEC 10-K body) and 'query' (e.g., supply-chain risk), clarifying usage. It doesn't add new parameter details but provides helpful context.

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

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

The description clearly states the tool performs semantic search inside a fetched record, specifying the inputs (text and query) and outputs (top-N passages with offsets and scores). It distinguishes itself from siblings by explaining it saves context and pairs with ask_pipeworx_grounded.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt.' Provides a complementary tool (ask_pipeworx_grounded) for grounding. Also notes the 200K char limit, helping the agent decide.

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

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

The description adds substantial behavioral context beyond annotations: returns subscription id, requires OAuth, details on type-specific parameters, delivery channels with constraints (email validation, SMS cap, webhook HMAC signature and auto-disable). No contradiction with annotations; the idempotentHint is not contradicted.

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

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

The description is fairly long but well-structured with important information front-loaded. Every sentence adds value, though it could be slightly more concise without losing clarity.

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

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

Given the tool's complexity (3 params, nested objects, no output schema), the description covers purpose, auth, type-specific behavior, and delivery details thoroughly. It mentions return value (subscription id) but does not describe full response structure or error scenarios. Still highly complete.

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

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

Schema coverage is 100%, but the description significantly enriches parameter meaning by providing concrete examples for each type and detailed explanations for delivery fields, including constraints like phone verification and webhook signing.

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

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

The description starts with 'Create a proactive monitoring subscription to a live-data event stream,' which is a specific verb+resource. It clearly distinguishes from sibling tools like list_subscriptions, unsubscribe, and recent_alerts.

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

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

The description states the requirement of a Pipeworx OAuth account and that anonymous/BYO cannot persist subscriptions. It lists supported types with examples, providing context for when to use each. However, it does not explicitly compare with alternatives 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?

Description adds significant behavioral context beyond annotations: it explains the tool draws from a live catalog, returns categorized examples, and can be focused by topic. No contradictions with readOnly, openWorld, idempotent, and non-destructive hints.

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

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

The description is front-loaded with example queries and is well-structured, though slightly verbose. Every sentence adds value, but 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?

With one optional parameter and no output schema, the description fully covers the tool's purpose, usage, and what it returns (category-bucketed examples). No gaps remain for the agent to infer.

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

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

Schema coverage is 100%; description enriches the single optional 'topic' parameter by listing example values and explaining what happens when omitted ('cross-category spread'), going beyond the schema's brief description.

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

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

The description clearly states the tool returns category-bucketed example questions with exact tool+argument shapes, and explicitly positions it as the onboarding entry point, distinguishing from siblings like ask_pipeworx and entity_profile.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you', providing clear context and examples of when to call it, though it omits explicit when-not-to-use conditions.

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

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

Description adds beyond annotations by specifying that the row is deactivated (not deleted) and historical events remain, aligning with non-destructive annotation. Ownership enforcement is also disclosed.

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

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

Two concise sentences: first states the primary action, second adds important behavioral nuance. No unnecessary words.

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

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

For a simple one-parameter tool with no output schema, the description covers ownership, deactivation behavior, and data retention, sufficient for an agent to understand the tool's effect.

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 'id' is fully described in the schema (including that it's returned by subscribe). The description does not add additional semantic detail beyond the schema.

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

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

The description clearly states the verb 'Cancel' and resource 'a subscription by id', 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?

Explicitly mentions ownership enforcement ('you can only cancel your own subscriptions'), providing clear context for when the tool is applicable, though it does not list alternatives for canceling others' subscriptions.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses important behavioral nuances: it explains the meaning of each verdict, distinguishes 'could_not_verify' (check did not happen) from 'unsupported' (no source exists), and details the error object. It also notes it replaces 4–6 sequential calls, adding operational context.

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

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

The description is longer than average but every sentence carries operational weight, from usage triggers to result semantics to caller cautions. It is well-structured with a clear intro, return value explanation, and highlighted 'IMPORTANT' section, showing intentional organization rather than bloat.

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

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

With no output schema, the description fully explains return values (verdict list, value with citation, reasoning), error handling, and the two processing paths. It covers edge cases like 'could_not_verify' and 'unsupported' alongside parameter tuning, making it complete for an agent to invoke correctly.

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

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

Schema coverage is 100% with descriptions for both params. The description adds extra semantics: it explains that tolerance_pct overrides the wording-implied tolerance, gives specific use cases (1–2 for hallucination detection), and clarifies the default cap of 5. This goes beyond the schema's basic 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 verifies natural-language claims against authoritative sources, with specific verb 'validate' and resource 'claim.' It lists example phrasings and distinguishes it from siblings by focusing on fact-checking rather than general research or data lookup.

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

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

The description gives explicit when-to-use guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the internal branching for company-financial vs. other claims, but does not explicitly name alternative tools or provide when-not-to-use scenarios.

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