Outlook Mail

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds value by explaining probing behavior, cost implications for Anthropic (BYO key), and return structure. No contradictions between description and 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 concise sentences: core function and default model, optional key and return format, use cases. Front-loaded, no redundant phrases. 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?

No output schema, but description explains return format (per-model score, confidence, signals, raw_response + combined view). Covers parameters well. Lacks explicit mention of rate limits or limitations, but overall adequate for an AI 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?

All 4 parameters have descriptions in schema (100% coverage). Description adds context: default model is workers-ai, _apiKey only needed for anthropic, and context helps disambiguate. Schema and description together provide rich parameter meaning.

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

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

Description clearly states the verb ('probe') and resource ('LLMs for business/brand/product visibility'), with scoring range and default model. It distinguishes from sibling tools like 'ask_pipeworx' or 'deep_research' by focusing on AI visibility auditing.

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?

Lists use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains when to provide an API key. However, does not explicitly guide when not to use this tool or mention alternatives among siblings like 'entity_profile' or 'scan_competitor_ai_presence'.

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

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

Annotations already declare readOnly, non-destructive, idempotent behavior, so the description adds value by explaining the routing mechanism across 5,439 tools and 1,412 verified sources, stable citation URIs, and the 'one fast call' behavior. It also hints at a limitation by recommending ask_pipeworx_grounded for verbatim evidence and confidence, implying this tool may not offer that level of grounding.

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 front-loaded with the most important directive ('PREFER OVER WEB SEARCH') and densely packs usage guidance, examples, and alternatives. Every sentence contributes to selection or invocation decisions, although a few phrases (e.g., 'works on every tier') are tangential to the core task.

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 absence of an output schema, the description covers purpose, typical use cases, alternatives, and even performance characteristics ('one fast call'). It could be more explicit about response format details, but 'structured answer with stable pipeworx:// citation URIs' provides enough for an agent to know what to expect.

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

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

The input schema already documents the 'question' parameter and all aliases with 100% coverage. The description repeats the natural-language nature of queries via examples but does not add meaningful parameter-level detail beyond what the schema provides. Baseline 3 is appropriate because schema does the heavy lifting.

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

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

The description opens with a clear directive ('PREFER OVER WEB SEARCH') and identifies the tool as a router that handles factual questions across many domains (SEC filings, FDA data, FRED/BLS, etc.), returning structured answers with citation URIs. It distinguishes itself from siblings by naming ask_pipeworx_grounded and deep_research as alternatives for specific use cases.

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 abundant: 'Use whenever the user asks...' with concrete example queries, plus clear escalation paths ('Step up only when needed') to ask_pipeworx_grounded for hallucination-resistant answers and deep_research for multi-part questions. It also specifies when not to use it (breaking news still routes here, but alternatives exist for broader fan-out).

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

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

The description discloses live candidate routing improvements, the current no-active-candidate state, and that it is a full working router with no fallback. This goes beyond annotations by describing the experimental nature and comparison process, while annotations already establish read-only, open-world, and idempotent behavior.

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

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

The description is four sentences and front-loads the core purpose and current status. Some specifics (5,439 tools, 2026-07-26 date) add length but each sentence contributes meaningful context, so it's efficient without being overly verbose.

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

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

The description covers the beta status, parity with stable, usage guidance, and functional fallback, which is sufficient given strong annotations and full schema coverage. It references 'same response shape' for output expectations, though it could optionally mention error behavior or example usage.

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

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

Schema coverage is 100% with all six parameters described as aliases of 'question'. The description adds that it uses the 'same arguments' as ask_pipeworx, but does not add new syntax or format details beyond what the schema provides. Baseline 3 is appropriate given high schema coverage.

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

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

The description clearly defines the tool as 'Beta version of ask_pipeworx' and explains it is an identical universal router with 5,439 tools. It distinguishes itself from sibling ask_pipeworx through the beta/experimental framing, making the purpose explicit and non-tautological.

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

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

It explicitly states 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router, giving clear when-to-use guidance. It also clarifies the current state (no active candidate) so agents know it matches the stable version exactly.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses the refusal behavior with exact refusal_reason values, the return shape, and the extraction constraint ('using ONLY what the tool result contains'), which is critical behavioral context not captured by annotations.

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

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

The description is front-loaded with the core purpose and then systematically covers return values, refusal modes, usage context, and cost tradeoff. Every sentence adds distinct value, and the structure is logical for a high-stakes tool where such detail is necessary.

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

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

Given the tool's complexity, the absence of an output schema, and the presence of nuanced refusal behavior, the description fully covers what an agent needs: usage context, alternatives, return format, failure modes, and cost implications. It is contextually complete for reliable invocation.

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

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

The input schema has 100% coverage, documenting the 'question' parameter and all its aliases. The description does not add parameter-level detail, but the schema already fully specifies the semantic meaning, so the baseline of 3 applies.

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

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

The description clearly identifies this as a 'hallucination-resistant answer mode' with a specific verb ('extracts') and resource, and explicitly distinguishes it from the sibling tool ask_pipeworx by describing the same routing but with grounded extraction. This is a specific, actionable purpose statement.

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 ('whenever an answer will be quoted, cited, or acted on... must not invent facts') and explicitly names the alternative ask_pipeworx for casual lookups, including the cost tradeoff (one extra LLM call). This is strong usage guidance.

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

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

Exhaustively details resolution process, fan-out, response shapes, safety checks, and edge cases (wide spreads, resolution rules). No contradiction with annotations; adds much context beyond readOnlyHint, openWorldHint, etc.

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

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

Very detailed but verbose. Important information is front-loaded with purpose and usage, but the description could be more structured (e.g., sections) to improve readability. However, every sentence provides 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?

Completely covers response shapes, resolver contract, parent event extractor, news fields, safety mechanisms, and resolution rules. Without output schema, this description fully compensates.

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

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

Adds meaning beyond schema: market accepts slug/URL/text, depth defaults to thorough, include_raw default false with explanation of when to use true. Covers all 3 parameters thoroughly.

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

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

Clearly states it researches a Polymarket bet by pulling Pipeworx data in one call. Provides specific use cases ('should I bet on X') and distinguishes from siblings like polymarket_edges.

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

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

Describes when to use ('should I bet on X') and what input types are accepted. Explains blocking conditions (low confidence, closed markets) but does not explicitly name alternative tools for specific scenarios.

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

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

Annotations already indicate safe, read-only, idempotent behavior. The description adds valuable behavioral details: it handles off-calendar fiscal years correctly, sorts results by primary metric, and replaces 8-15 sequential lookups. 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 well-structured: trigger phrases first, then core function, then type-specific details, then behavioral notes. Every sentence adds value, but it is somewhat lengthy. It could be slightly more concise without losing information, but it remains clear and informative.

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

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

Given the tool's complexity (2 entity types, multiple data fields, sorting, citation), the description covers all necessary aspects: triggers, usage constraints, data sources, output format, and efficiency claim. No output schema is present, but the description specifies 'paired data + pipeworx:// citation URIs per entity', which is sufficient. The annotations handle safety and idempotency.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds extra context: for type, it explains what each enum value retrieves (company: financials from SEC EDGAR/XBRL; drug: FAERS, FDA, trial counts). For values, it provides examples and constraints (tickers/CIKs, drug names, 2-5 items). This goes beyond the schema definitions.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 entities (companies or drugs) in one call, with specific data pulled for each type. The trigger phrases (e.g., 'X vs Y', 'rank these companies') directly match common user intents. This clearly distinguishes it from single-entity tools like 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 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing strong guidance. It also enumerates use cases (comparison queries, ranking) and implies when not to use (single entity lookups) by mentioning alternatives like sequential lookups and the sibling entity_profile.

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?

Despite annotations already marking readOnlyHint and openWorldHint, the description adds rich behavioral details: decomposition into facets, routing to 5,439 tools in parallel, the findings packet structure, gaps[] for unanswered facets, contradictions[] for standard/thorough, semantic excerpting, hop field, citation URIs, and latency expectations. No contradiction with annotations.

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

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

The description is long but every sentence carries critical information: account requirements, differentiation from open-web search, use cases, return format, edge cases, and timing. It is densely packed but not verbose. A more structured layout (line breaks or bullets) would improve readability, but the content is efficiently organized by topic.

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 lack of an output schema, the description fully covers what is needed: it explains the findings packet elements, gaps[], contradictions[], hop, citation_uri, and semantic excerpting. It also covers account tiers, expected runtime, and provides explicit guidance for when to use alternatives. 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 coverage is 100%, so baseline is 3. The description adds meaningful context beyond the raw schema by explaining the depth values in more operational terms: 'quick=3 (single hop)', 'standard adds a gap-recovery hop and contradictions[]', 'thorough adds a full iterative hop plus contradictions[], and requires a paid plan'. It also gives examples for the question parameter, demonstrating decomposition.

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: 'Grounded multi-source research across Pipeworx's 1412 STRUCTURED data sources' in one call. It distinguishes from siblings by explicitly saying 'For a single lookup use ask_pipeworx' and 'prefer ask_pipeworx' for breaking news, making it unique.

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

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

Provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data', with concrete examples. Also specifies exclusions: 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx' and notes that users without an account should use ask_pipeworx instead. This is thorough and actionable.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that results include full schemas with examples and are ready to call directly – useful context beyond annotations. No contradiction.

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

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

Moderately sized (100+ words) but front-loaded with purpose. Every sentence adds value – domains, return format, usage guidance. 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?

Despite missing output schema, descriptions explains what is returned (names, descriptions, full schemas, examples). Parameter count is 6, all documented. Provides sufficient context for an agent to use correctly.

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

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

Schema coverage is 100%. Description repeats that query accepts aliases (already in schema) and mentions limit. Adds no new semantic details beyond what the schema provides. 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?

Description starts with 'Find tools by describing the data or task' – a specific verb+resource. It lists many concrete domains (SEC filings, FDA drugs, etc.) and distinguishes itself from sibling tools by being a discovery/catalog tool. No tautology.

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?

Ends with explicit guidance: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It tells when to use, but does not explicitly state when not to use (e.g., when you already know the tool). Still clear and helpful.

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

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

Discloses fanning across multiple sources, patent soft-fail due to API sunset, return fields, and that names are unsupported. No contradiction with annotations.

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

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

Long but well-structured with examples and front-loaded key guidance. Every sentence adds value, though slightly dense.

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

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

Despite no output schema, description details return fields (cik, recent_filings, fundamentals, patents, news, LEI) and data sources, making behavior fully transparent.

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

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

Schema already covers both parameters at 100% coverage. Description adds context on CIK format and reiterates name restriction, adding value beyond schema.

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

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

Description clearly states the tool provides a 'full cross-source profile of a US public company' with specific examples. It distinguishes from chaining single-pack lookups and siblings like resolve_entity.

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

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

Explicitly says 'ALWAYS PREFER over chaining' for holistic views and notes to use resolve_entity if only a name is available.

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

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

Annotations already declare destructiveHint=true, so the description's mention of 'Delete' aligns but adds little extra behavioral context. No contradiction with annotations.

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

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

Three sentences, front-loaded with action, no unnecessary words. Efficient and 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 parameter and no output schema, the description covers purpose, usage context, and sibling relationships. Fully sufficient.

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

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

Schema coverage is 100% and the description adds no additional information about the 'key' parameter beyond what the schema provides. 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 (Delete) and resource (previously stored memory by key). It also distinguishes from siblings by explicitly naming 'remember' and 'recall' as complementary tools.

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

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

Provides explicit when-to-use scenarios: 'when context is stale, the task is done, or you want to clear sensitive data'. Also mentions pairing with remember and recall, offering clear context and alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, establishing safety. The description adds behavioral details: fetches the page, extracts title/description/key links, and emits standard markdown. This provides context beyond the annotations, though no mention of rate limits or caching.

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

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

The description is three sentences: purpose, process, use cases. Every sentence adds value with no redundancy. Front-loaded with the core action.

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

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

Given the simple read-only nature, annotations cover safety, schema covers params, and description covers purpose, process, output format ('single text blob'). No missing details 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 description coverage is 100%, so baseline is 3. The description does not add extra meaning beyond the schema for either 'url' or 'max_links'. It mentions 'extracts links' but does not elaborate on the limit parameter.

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

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

The description clearly states the verb 'Generate' and the resource 'llms.txt file for any URL'. It distinguishes the tool from siblings by specifying it produces a standard llms.txt markdown format for AI crawlers, which is unique compared to other tools like ai_visibility_check or scan_competitor_ai_presence.

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

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

The description provides explicit use cases: getting a client's site indexed, drafting for own project, or auditing a competitor. It implies when to use but does not explicitly mention when not to use or name alternative tools. However, the context is clear enough.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint, so safety is clear. The description adds value by specifying default behavior (active subscriptions) and the exact fields returned.

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

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

Two sentences: first defines purpose and output, second gives usage guidance. 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 one optional parameter and no output schema, the description is complete enough. It explains what is returned and when to use it. Minor omission: no mention of pagination or limits, but not critical for this tool's simplicity.

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

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

Schema coverage is 100% with a clear description for the only parameter. The description adds no further parameter-level detail, but the baseline of 3 is appropriate as the schema already does the job.

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 'List the caller's active subscriptions' with a specific verb and resource. It also lists the return fields, distinguishing it from sibling tools like 'subscribe' and '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 states to use this tool to review subscriptions before adding more or to find an id to cancel. While no explicit when-not-to-use is given, the context is clear and helpful.

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

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

With no meaningful annotation hints (all false), the description takes on full disclosure burden. It reveals rate limiting ("Rate-limited to 5 per identifier per day"), quota impact ("Free; doesn't count against your tool-call quota"), and downstream effect ("The team reads digests daily and signal directly affects roadmap"). It also warns about wasted effort for non-Pipeworx tools, adding operational context beyond structured data.

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?

Though fairly long, every sentence earns its place: purpose, timing, exclusions, content guidelines, and rate limits are all packed efficiently. The description is front-loaded with the core action and then flows naturally through use cases and constraints. No fluff or repetition.

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

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

The tool is simple but has nested context and routing nuances. The description covers what to report, which tools are eligible, what not to include (end-user's prompt), rate limits, quota treatment, and how feedback is processed. Given the lack of an output schema, the description fully compensates for any need to understand return 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 coverage is 100% (all parameters have descriptions). The description adds prose mapping to the enum ("broken, missing, or needs to exist") and reinforces the context parameter's intent ("Describe the issue in terms of Pipeworx tools/packs"), but it does not introduce syntax or meaning absent from the schema. Baseline 3 is appropriate when the schema already carries the full parameter burden.

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

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

The description opens with a specific verb+resource: "Tell the Pipeworx team something is broken, missing, or needs to exist." It clearly distinguishes this from sibling tools by framing it as a feedback channel for tools served by this connection, not a research or query tool. The type categories (bug, feature, data_gap, praise) further clarify the 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?

Explicit when-to-use guidance is given: "Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise)." It also states when NOT to use: "ONLY for tools served by this Pipeworx connection... if the tool came from a different MCP server... file it with that server instead." This is a textbook example of exclusions and alternatives.

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

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

Annotated as read-only and idempotent; description adds caching details and data source (CF analytics, no PII), enhancing transparency beyond annotations.

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

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

Concise, front-loaded, uses bullet points for use cases, no wasted words.

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

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

Despite no output schema, description covers return fields, caching, privacy, and window logic—fully adequate for a simple 1-param tool.

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

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

Schema has 100% coverage with enum and description; description adds meaningful context on window behavior (hot vs. steady-state).

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

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

The description clearly states it returns top tools, packs, and call volume over a window, distinguishing it from siblings like discover_tools or 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?

Provides three explicit use cases and insight into window selection, but does not explicitly contrast with sibling tools for when not to use.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false) are consistent. Description adds substantial behavioral context: scanning modes, semantic anchor (Jaccard similarity >= 0.30), partition filter (placeholder exclusion), fill check (realizable edge vs theoretical), and response structure. 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 relatively long but well-structured and front-loaded with the core purpose. Every sentence adds value, but could be slightly more concise. Minor redundancy in explaining the partition filter twice.

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 (two modes, algorithmic checks, fill validation, response details) and no output schema, the description is exceptionally complete. It covers all necessary context: how to invoke each mode, semantic anchoring, partition filtering, fill check, and response shape. Users can confidently understand and use 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?

Despite 100% schema coverage, the description adds deep meaning: explains event vs topic modes, provides examples of slugs and seed questions, and details the behavior of each mode (single-event with partition check, cross-event with flattening and comparator). Goes far beyond the schema descriptions.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between two modes (event and topic) and explains each explicitly, differentiating 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?

Explicit guidance on when to use each parameter: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. Also provides context on when not to use (e.g., when realizable_edge_pp <= 0) and mentions alternative tool for custom sizing.

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

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

Extensive behavioral details beyond annotations: caching (1h KV), three model families with formulas, response segments, diagnostics for empty segments, and tradeable-edge knobs. No contradiction with readOnlyHint.

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

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

Very long but dense with necessary information. Front-loaded with purpose, but overall verbose; could be more concise without losing critical 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?

Exceptionally complete for a complex tool with 9 parameters and no output schema. Covers model families, edge calculation, caching, diagnostics, and usage guidance for each segment.

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

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

Schema already provides detailed parameter descriptions (100% coverage). Description adds value by explaining logic context for parameters like min_partition_leg_kelly and tradeable-edge filters.

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?

Clear verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' Distinguishes from siblings like polymarket_arbitrage by focusing on daily betting discovery.

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

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

Implied usage as daily bet discovery tool, but no explicit when-to-use vs siblings such as polymarket_arbitrage or polymarket_edge_tracker.

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 behavior. The description adds rich behavioral context: how snapshots are written (on cache-miss), interpretation of gaps, and detailed response structure with trend classifications and decay calculations. 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 lengthy but well-structured and front-loaded with purpose. Every sentence adds essential information. Could be slightly more concise without losing clarity, but efficient for the complexity.

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

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

Despite no output schema, the description comprehensively explains all response fields (tracked[], expired[], snapshot_dates[]) with meanings, edge cases, and limitations. Covers everything an agent needs to invoke and interpret results 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 covers 100% of parameters with descriptions. The description reinforces and expands: clarifies days default/max, window family options. Minor inconsistency (schema says clamp 2-30, description omits min 2) but overall adds value beyond schema.

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

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

The description clearly states the tool's function: edge persistence and decay telemetry from daily snapshots. It answers specific questions about edge history and shrinking, and distinguishes itself from sibling tool 'polymarket_edges'.

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

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

The description provides explicit context on when to use (to check edge persistence and decay) and includes important details like the significance of fresh vs old edges, data limits, and what the response contains. It implicitly differentiates from alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context: it is a risk check against live order book depth, walks the ladder, and warns about forced directional risk. It does not contradict annotations. The description enhances understanding beyond what annotations alone provide, though it omits potential rate limits or authentication details (not critical for a read-only tool).

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

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

The description is well-structured with clear mode breakdowns and front-loaded purpose. Every sentence provides value. However, it is relatively long; while justified by complexity, it could be slightly more concise without losing clarity. Overall, it is efficient given the tool's sophistication.

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 (two modes, four parameters, no output schema), the description is remarkably complete. It covers return fields, usage context, risk warnings, and different parameter interpretations. The annotations cover safety. No gaps are evident; an AI agent should be able to use this tool correctly based on the description alone.

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

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

Schema coverage is 100%, but the description adds significant semantics: it explains that 'market' is for single-market mode and 'event' for basket mode, details the side defaults and auto-detection for basket, and clarifies how 'size_usd' is interpreted differently (spend vs target proceeds for single-market, settlement notional for basket). This goes well beyond the schema descriptions.

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

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

The description clearly states it checks realizable vs theoretical edge on Polymarket's CLOB order book depth. It distinguishes two modes (single-market and basket) and explicitly tells agents to use this before acting on sibling tools like polymarket_arbitrage or polymarket_edges, making its purpose highly specific and distinguishable.

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: before acting on polymarket_arbitrage signals or any polymarket_edges trade above ~$500. It also explains why (theoretical overround often uncapturable on thin books, partial basket fills create unhedged directional positions) and mentions the dominant loss mode. This gives clear context for tool selection.

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

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

Disclosure goes beyond annotations: explains compatibility_warning conditions, temporal alignment, skipped cross types. No annotation 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?

Long, detailed description with multiple concepts; while well-structured, could be more concise to 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?

Thorough coverage: explains modes, response fields (leg prices, spread, safety, temporal), and edge cases. No output schema, so description compensates fully.

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

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

Schema coverage is 100%, but description adds context for modes, example values, and response fields beyond basic schema descriptions.

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

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

The description clearly states the tool computes cross-venue spreads for the same outcome, with two modes. It distinguishes from siblings like polymarket_arbitrage by focusing on two venues.

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

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

Describes when to use (comparing same question across venues) and when not (compatibility warnings, most pre-mapped topics not tradeable). Lacks explicit naming of alternative tools but context is clear.

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

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

Annotations already show readOnlyHint=true and idempotentHint=true, so safety is clear. The description adds value by disclosing scoping (by identifier) and the behavior when key is omitted (list all). 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 two efficient sentences, front-loaded with the main purpose, and every phrase earns its place. No wasted words.

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

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

With no output schema, the description explains what the return values are (value or list of keys). It covers the primary use case and scoping. Minor gap: no mention of error handling for missing key, but this is acceptable given simplicity.

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

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

Schema coverage is 100%, and the description reiterates the key parameter's behavior (omit to list all) while adding context about scoping. This provides meaningful guidance beyond the schema's description.

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

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

The description clearly states the tool's purpose: retrieve a saved value or list all keys, with specific examples (ticker, address, research notes). It distinguishes itself from siblings (remember, forget) by focusing on retrieval.

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

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

The description explains when to use the tool ('look up context the agent stored earlier') and implies alternatives (pair with remember/forget). It could be more explicit about when not to use, but the context is clear.

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

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

Annotations declare readOnly, openWorld, idempotent, non-destructive. The description adds important behavioral details: mark_read behavior (flagging returned events read) and that the feed is also accessible via a GET endpoint. No contradictions.

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

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

The description is concise yet comprehensive, covering purpose, parameters, return fields, and usage notes in a single paragraph with no redundant sentences.

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

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

Despite no output schema, the description explains return fields and behavior. Combined with high schema coverage and informative annotations, the tool is fully understandable for correct invocation.

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

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

Schema already has 100% coverage. The description adds meaning by providing examples (e.g., 'sec_8k' for type), clarifying ISO timestamps, and explaining the side effect of mark_read. This enhances the schema's purely structural descriptions.

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

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

The description clearly states the tool pulls fired events from a subscription feed, specifying return fields (source, citation_uri, payload) and filter options. It distinguishes from siblings like list_subscriptions by focusing on recent alerts with specific payload details.

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

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

The description provides context by noting polling is fine and mentions an alternative REST endpoint for scripts/dashboards. However, it does not explicitly contrast with sibling tools like list_subscriptions or when to use this vs other alert-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 set readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as safe. The description adds valuable behavioral details: parallel call execution, GDELT→GNews fallback, USPTO soft-fail, and citation URIs. 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 compact yet comprehensive, front-loading example queries. Every sentence adds necessary information without redundancy. Efficient use of language.

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 specifies the return structure (changes[] grouped by source, total_changes count, citation URIs). It covers source behavior, fallback, caching, and gives a clear alternative tool. Adequate for the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the supported entity type, date format options with recommended values, and acceptable input formats for value (ticker or CIK). This enhances usability beyond the schema.

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

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

The description clearly states the tool provides a change feed for a company over a time window, listing specific sources (SEC EDGAR, GDELT→GNews, USPTO). It distinguishes from the sibling tool entity_profile by specifying when to use the alternative.

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 concrete query examples ('What's new with X', 'latest on Y') and explicitly instructs when to use entity_profile instead. It also explains source selection logic, fallback behavior, and date format recommendations.

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 give idempotentHint=true and destructiveHint=false. The description adds value by explaining persistence details (24-hour retention for anonymous, persistent for authenticated) and the scoping mechanism. However, it doesn't discuss idempotency implications or confirm read/write behavior beyond what's in annotations.

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

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

Concise, front-loaded with purpose, then usage, then behavioral details. Each sentence adds value; no redundancy.

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

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

Given the simplicity of the tool (2 params, no output schema), the description is mostly complete. It explains scope, persistence, and pairing. Minor gap: doesn't mention if key can be overwritten or if storage is case-sensitive.

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

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

Schema covers both parameters with descriptions. The description adds practical usage examples and naming conventions (e.g., 'subject_property') that go beyond the schema. However, it doesn't provide format or length constraints.

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 ('Save data'), the resource ('key-value pair'), and the context ('across conversations/sessions'). It distinguishes from sibling tools like 'recall' and 'forget' by explicitly mentioning pairing.

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 the tool: 'when you discover something worth carrying forward' with concrete examples. Also tells when not to use implicitly by pairing it with recall/forget, and specifies scope (by identifier).

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

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

Annotations already indicate idempotent, read-only, and non-destructive behavior. The description adds valuable behavioral context: 'Each call cascades through several lookup endpoints internally — using resolve_entity replaces 2-3 manual lookups.' No contradictions with annotations.

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

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

Two well-structured paragraphs. First paragraph states core purpose and when to use. Second paragraph details supported types with concrete examples. Every sentence is informative and earns its place. Front-loaded with critical usage info.

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

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

Given the tool's moderate complexity (2 parameters, 1 enum, no output schema), the description is thorough. It explains the purpose, usage context, input formats, return values (including citation URIs), and internal behavior. No gaps remain for an agent to correctly select and invoke this tool.

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

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

Schema coverage is 100%, so baseline is 3. The description significantly enriches parameter semantics by explaining the specific return values for each type (e.g., ticker + CIK + company_name for 'company', RxCUI + ingredient + brand for 'drug') and acceptable input formats (ticker, CIK, name for company; brand or generic for drug). This goes well beyond the schema's minimal descriptions.

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

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

Description uses specific verbs and resources: 'resolve a user-spoken NAME to the canonical/official identifier other tools require as input.' It also provides example queries ('What's the ticker for…') and explicitly lists supported types. This clearly distinguishes it from siblings like 'compare_entities' or 'entity_profile' which serve different purposes.

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 includes an explicit directive: 'Use FIRST whenever you have a name but need an ID.' It also details what each entity type returns and accepted input formats. However, it does not explicitly state when not to use the tool or mention alternative tools for cases where one already has an ID.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds that it calls ai_visibility_check internally, ranks results, and returns a ranked list with score, confidence, and signal density. This provides useful behavioral context beyond annotations without contradiction.

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

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

Three sentences with front-loaded primary action and result. Every sentence adds value: purpose, internal mechanism, use case, output summary. No redundant or filler content.

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

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

The description covers purpose, usage, output structure (ranked list with score, confidence, signal density) despite no output schema. Parameters are fully described in the schema. It lacks details on error handling or limitations, but given the annotations and schema richness, it is largely sufficient for an agent to decide to invoke.

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

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

Schema coverage is 100%. The description adds that the first entity in 'entities' is treated as the subject and the rest as competitors, which is not in the schema. For 'models', it reiterates the default but omits the API key discussion, which is in the schema. Overall, it adds modest value beyond the schema.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, ranks by score, and surfaces most/least recognized. It specifies the resource ('AI presence of entities') and verb ('scan/compare'), distinguishing it from siblings like 'ai_visibility_check' (single entity) and 'compare_entities' (general comparison).

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

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

The description provides a concrete use case ('competitive AI-marketing audits: does Claude know about us as well as our competitors?') and explains that it probes each entity with ai_visibility_check. It implicitly suggests when to use (comparing multiple entities) but does not explicitly state when not to use or name alternative tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description goes beyond by disclosing: 'Partial failures degrade gracefully — bundlephobia's first measurement on a new version can take 5-30s; sources_failed will list it if it times out, the rest still returns.' This is valuable behavioral context not captured in annotations.

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

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

The description is well-structured with a clear purpose statement first, followed by details. It is moderately long but each sentence adds value (usage, scope, return fields, caveats). Slightly verbose but not wasteful. Front-loaded with key purpose.

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

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

For a tool with no output schema, the description is remarkably complete. It enumerates the return block fields (is_latest, license, advisory_count, bundle sizes, etc.), mentions per-advisory details, links, and alternative versions. It also covers limitations (NPM only, partial failures, timing). This compensates for the missing output schema.

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

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

Schema description coverage is 100%, so the schema already documents both parameters (package, version) clearly. The description adds minimal additional meaning for the parameters themselves, mostly focusing on the composite nature and return fields. 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 composite nature of the tool, combining deps.dev and bundlephobia, and explicitly frames it as answering 'should I add this npm package'. It distinguishes from siblings by focusing on npm dependency scanning (NPM ecosystem only), which contrasts with related tools like check_url_safety or deep_research.

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

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

Explicit usage advice: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also provides clear exclusion guidelines: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This helps the agent decide when to use this tool versus alternatives.

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

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

The description adds significant behavioral details beyond annotations: it reveals the embedding model (BGE-base-en), similarity metric (cosine), chunking strategy (500-char overlapping windows), character limit (200K chars), and truncation behavior. Annotations already indicate idempotency and safety, and description aligns well.

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

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

The description is concise (4 sentences) and front-loaded with the core purpose. Every sentence adds essential information without redundancy.

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

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

Given the lack of an output schema, the description adequately explains what the tool returns (passages with character offsets and similarity scores). It also mentions limitations (200K char cap). Slight gap in describing output structure formally, but sufficient for an agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds contextual examples for the 'query' parameter (e.g., 'supply-chain risk') and confirms the character limit for 'text'. This adds meaningful guidance beyond the schema's own descriptions.

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

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

The description explicitly states 'Semantic search INSIDE a fetched record' and provides concrete examples (SEC 10-K, article, long tool result). It distinguishes from siblings by mentioning pairing 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?

The description clearly states when to use ('when the record is too big to cram into the prompt') and suggests an alternative pairing (ask_pipeworx_grounded). It does not explicitly list when not to use, but the guidance is clear enough.

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

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

The description contradicts the idempotentHint annotation. While annotations indicate the tool is idempotent (same effect on repeated calls), the description says 'Returns the new subscription id', implying each call creates a new subscription, which is not idempotent. This contradiction is critical. The description does add other behavioral context (OAuth requirement, phone verification, SMS cap, webhook auto-disable), but the contradiction invalidates trust.

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 a clear first sentence defining the purpose, followed by requirements, type examples, and delivery details. It is somewhat verbose but every sentence adds value. It could be tightened by moving very specific technical details (like HMAC signing) to the schema or a separate reference.

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 types, nested parameters, no output schema), the description covers parameter semantics well and mentions the return of a subscription id. However, it lacks details about the full response object, subscription lifecycle (update/deletion), error scenarios, or rate limits beyond SMS. The absence of output schema makes the description more critical, and it falls short.

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 schema description coverage is 100%, the description significantly enriches parameter understanding with concrete examples and type-specific details (e.g., item codes for sec_8k, topic for polymarket_edge, series_id for fred_series). It also explains delivery channel constraints like phone verification and webhook signing. This goes well beyond the schema.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream. It uses specific verbs ('create', 'subscribe') and identifies the resource ('subscription'). The title is consistent. It distinguishes from sibling tools like 'unsubscribe' and 'list_subscriptions' by defining the creation action.

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

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

The description explicitly states when to use the tool (proactive monitoring) and lists prerequisites (Pipeworx OAuth account). It provides supported subscription types with examples and details delivery options. However, it does not explicitly state when NOT to use it or compare with alternatives like 'recent_alerts' or 'search_within', though the context implies use cases.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds that it draws from a live catalog of thousands of tools, describes behavior with and without arguments, and does not contradict 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 longer but well-structured, front-loading the purpose with alternative phrasings and listing outputs clearly. Every sentence serves a purpose, though minor redundancy could be trimmed.

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

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

For an onboarding tool, the description is fully complete: it explains the return format (category-bucketed examples with tool shapes), usage scenarios, and relationship to meta-tools. No output schema is needed given the explicit description.

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

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

Schema coverage is 100% with a well-described optional topic parameter. The description adds context on usage (full spread vs. focused) and provides example topics, surpassing the baseline for high-coverage schemas.

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 returns category-bucketed example questions with exact tool+argument shapes, serving as an onboarding entry point. It distinguishes from siblings like ask_pipeworx and discover_tools by specifying its unique 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 advises using this tool FIRST when the user doesn't know what Pipeworx can do, and mentions how to narrow by topic. It does not explicitly state when not to use, but the context is clear and actionable.

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

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

Discloses that the row is deactivated, not deleted, and that historical events remain available via recent_alerts. This adds behavioral context beyond annotations (readOnlyHint, destructiveHint, idempotentHint), though annotations already cover safety and idempotency.

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

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

Two sentences front-load the purpose and immediately follow with key behavioral details. No extraneous information; every sentence adds value.

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

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

Given the low complexity (1 parameter, no output schema, full schema coverage) and existing annotations, the description covers ownership, effect on data, and archival behavior, making it fully informative 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?

Input schema covers 100% of parameters with a clear description for 'id'. The description does not add further detail beyond what the schema provides, meeting the baseline expectation.

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

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

The description clearly states 'Cancel a subscription by id' with a specific verb and resource, distinguishing it from siblings like subscribe and list_subscriptions. Ownership enforcement adds further specificity.

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

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

Explicitly states 'Ownership is enforced — you can only cancel your own subscriptions,' providing clear context on when to use. Mentions that deactivation preserves historical events, guiding user expectations, though no explicit alternatives to other tools are given.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context: dual-path verification logic, verdict types, citation format, and efficiency gains. 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 front-loaded with the core purpose and usage cues. While somewhat lengthy, each sentence adds value. Could be slightly more concise but remains effective.

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

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

Despite no output schema, the description fully covers tool behavior: input parameters, dual verification pathways, output verdict types, citation format, and efficiency. No gaps for the agent.

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

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

Schema coverage is 100% (baseline 3). The description adds meaning beyond the schema by explaining tolerance_pct override and default behavior, and provides examples of claim inputs.

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

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

The description starts with a clear verb phrase and multiple natural-language query examples, explicitly distinguishing the tool from siblings by noting it replaces 4-6 sequential calls.

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

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

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct' and details the two verification paths (structured SEC EDGAR vs. grounded pipeline), providing clear guidance on when to invoke.

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