Photon

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

Annotations already indicate read-only, idempotent, non-destructive behavior. Description adds valuable context: default model cost, API key requirement, and return structure (per-model + combined view). No contradictions.

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

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

Two highly informative sentences with no wasted words. First sentence covers main action and output, second addresses optional parameters, third lists use cases. Information is front-loaded and scannable.

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 explicitly mentions the return format (per-model score, confidence, signals, raw_response + combined view). All 4 parameters are explained. No missing critical information for an agent to use the tool correctly.

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

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

Schema coverage is 100% (all 4 params described). Description enriches by explaining the default model for 'models', the purpose of '_apiKey' (BYO key, direct billing), and how 'context' disambiguates. Adds 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 uses a specific verb ('probe') and resource ('LLMs... score visibility'), clearly distinguishing from siblings like scan_competitor_ai_presence. It explicitly states the output (score 0-100) and target entities.

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 use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and context (default free model, optional Anthropic with BYO key). Lacks explicit when-not-to-use or direct sibling differentiation, but the use cases are sufficiently indicative.

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 and non-destructive behaviors. The description adds valuable context about routing across 5,529 tools, stable citation URIs, and one-call/all-tier behavior. It does not contradict annotations, and the extra detail is meaningful without over-explaining 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 longer than typical but every section earns its place: the preference directive, domain list, examples, and escalation paths. It is well-structured with clear scannability, though slightly verbose due to repeated examples.

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 no-output-schema tool, the description explains the structured answer with citations, the routing mechanism, and when to step up to alternatives. It covers the full decision space for a default entry-point tool, making it 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%, with all parameters described as aliases for 'question'. The description adds no parameter-specific semantics beyond restating that a natural-language question is accepted, which is already in the schema. Baseline 3 is appropriate as no compensation 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 answers factual questions by routing to thousands of tools and returning structured answers with citations. It distinguishes itself from siblings by naming ask_pipeworx_grounded and deep_research and explaining when each is appropriate.

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 'PREFER OVER WEB SEARCH', 'START HERE', and gives step-up guidance for ask_pipeworx_grounded and deep_research. Provides example queries and trigger phrases, making usage criteria unambiguous.

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 useful context: no candidate is active, it currently matches ask_pipeworx, and it is a full working router, not a stub. This complements the annotations without contradicting them.

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

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

The description is three sentences, front-loaded with the beta identity, and each sentence adds necessary context. It avoids redundancy while covering current behavior, usage, and relationship to the stable router.

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 as a router covering 5,529 tools, the description adequately explains its purpose, current state, and relationship to the stable variant. The response shape is referenced via 'same response shape', and the rich annotations and full schema compensate for any missing details.

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, with 'question' described and all aliases (q, text, input, query, prompt) individually documented. The description only mentions 'same arguments' as ask_pipeworx, adding no new parameter semantics, but the schema already provides the necessary detail.

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

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

The description explicitly identifies the tool as a beta version of ask_pipeworx, a universal router with identical toolset and response shape. It distinguishes from the stable sibling by mentioning candidate routing improvements and the fact that it currently matches ask_pipeworx exactly.

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

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

It gives a clear condition: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also notes that results are compared against the stable router to decide merges, implying the stable variant should be used when experimental routing is not desired. It doesn't explicitly list exclusions, but the experimental framing is sufficient 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 goes far beyond the annotations by disclosing the exact success/failure return shapes, including evidence as a verbatim quote, confidence, source, and specific refusal_reason values. It also reveals the extra LLM call cost, which is not indicated by annotations. No contradiction with readOnlyHint, openWorldHint, or idempotentHint.

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

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

The description is dense with useful information, but it is somewhat long — four sentences covering purpose, mechanism, return types, usage, and cost. Every sentence earns its place, but slightly more conciseness could be achieved without loss. Front-loaded with the primary purpose, so structure is strong.

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 compensates by detailing the exact return structure on success and failure, listing all refusal reasons, and providing cost/usage context. This makes the tool fully comprehensible for an agent without needing additional information about returns or edge cases.

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

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

The schema already provides 100% coverage with descriptions for all six parameter aliases, stating each is an alias for 'question'. The description adds no further parameter-level information, only referring to 'question in natural language' which is already in the schema. Baseline 3 is appropriate given complete 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 starts with "Hallucination-resistant answer mode for high-stakes reads," which clearly defines the tool's specific purpose and scope. It also explicitly distinguishes itself from ask_pipeworx by noting it uses the same routing but adds a grounded extraction step, making it distinct among siblings.

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

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

It provides explicit when-to-use guidance: "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 names the alternative and gives a preference rule: "prefer ask_pipeworx for casual lookups" and mentions the extra LLM call cost.

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

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

The description goes far beyond annotations by detailing response shapes, resolver contracts, parent extractor, news fallback, safety mechanisms, closed market handling, wide spread warnings, and resolution-rule 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 lengthy but front-loaded with purpose and structured logically. Every sentence adds value for a complex tool, though some trimming could improve conciseness.

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 documents all output fields and edge cases (low confidence, closed markets, wide spreads, cancellation rules). It fully equips an agent to use the tool correctly.

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

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

All 3 parameters are described in the schema (100% coverage). The description adds contextual value by elaborating on input formats, depth options, and include_raw usage, aiding selection.

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

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

The description clearly states it researches a Polymarket bet using Pipeworx data, explaining input types (slug, URL, question text) and the process (resolve, classify, fan out). It is specific and distinct from sibling tools.

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

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

Explicit use cases are given ('should I bet on X', etc.), providing clear context for when to invoke. It does not explicitly list non-use cases or compare to siblings, but the examples suffice.

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

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

Annotations already indicate safe, read-only behavior. The description adds valuable details: correct handling of off-calendar fiscal years, results sorted by primary metric, and return of paired data with citation URIs. No contradictions with annotations.

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

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

The description is somewhat long but efficient; every sentence adds value. It front-loads common query patterns. Minor redundancy could be trimmed, but overall well-structured.

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

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

No output schema exists, but the description mentions return type (paired data + citation URIs). It explains what metrics are returned for each type. For a two-parameter tool, this is fairly complete, though more detail on response format would be beneficial.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning: explains what each type pulls (financials for company, adverse events for drug) and specifies value formats (tickers/CIKs vs. drug names). 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 companies or drugs in one call, specifying data sources (SEC EDGAR, FAERS) and metrics. It distinguishes from siblings by noting it replaces 8-15 sequential lookups.

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

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

The description lists explicit user triggers (e.g., 'Compare X and Y', 'which is bigger') and instructs to always prefer over sequential lookups. It provides clear context for when to use this tool over 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 richly discloses behavior beyond annotations: it mentions decomposition into facets, parallel routing, the exact return packet structure (verbatim evidence, confidence, source, gaps, contradictions), citation fetchability, semantic excerpting, latency expectations, and account/plan constraints. Nothing contradicts 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?

While long, the description is front-loaded with the critical account requirement and every sentence provides operational value—no filler. It is structured with clear use-case contrasts and parameter semantics, making the length appropriate for the tool's 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?

The tool has no output schema, so the description correctly explains the return findings packet including gaps[] and contradictions[], plus performance expectations and constraints. It covers prerequisites, limitations, and exceptions, making the description fully self-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 schema already documents question and depth. The description adds substantial meaning: it explains each depth level's facet count and hop behavior, describes expected latency, and clarifies that broad questions are acceptable. 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 performs grounded multi-source research across Pipeworx's 1455 structured data sources in a single call, with a specific verb and resource. It also explicitly distinguishes itself from open-web search and sibling tools like ask_pipeworx, making its purpose unmistakable.

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

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

It gives explicit guidance on when to use: best for broad/multi-part questions over structured data, and when not to use, such as for single lookups (use ask_pipeworx) or breaking news (prefer ask_pipeworx). It also notes account/plan prerequisites and points to alternatives, providing complete usage context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral details: returns top-N relevant tools, includes full schemas with examples, and is 'ready to call directly.' This goes beyond annotations but omits potential constraints like rate limits.

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

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

The description is moderately concise, front-loading the core purpose, then listing supported domains, return value, and usage recommendation. Every sentence adds value, though it could be slightly shorter without losing 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?

Given the absence of an output schema, the description adequately explains return structure (names, descriptions, schemas, examples). It addresses the agent's need for tool discovery and integrates well with the sibling set, leaving 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?

Schema coverage is 100% with descriptions for each parameter. The description adds value by explaining that 'query' accepts natural language, lists example inputs, notes aliases (task, q, search, description), and specifies default/max for 'limit.'

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 'Find tools by describing the data or task,' enumerates specific domains (e.g., SEC filings, FDA drugs, weather), and distinguishes itself from siblings like 'search' by advising 'Call this FIRST when you have many tools.' It clearly communicates the tool's role as a discovery mechanism.

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 specifies when to use (browse/search/discover tools) and recommends calling it first in a multi-tool scenario. While it doesn't explicitly list when not to use, it provides sufficient context for appropriate invocation.

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

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

Annotations already declare safe, read-only, idempotent behavior. The description adds operational details like parallel fan-out, soft-fail on patents, and exact return fields, providing valuable context beyond annotations.

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

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

The description is dense with examples and details but remains well-structured and front-loaded. Every sentence adds value, though slightly long; 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?

No output schema, but the description thoroughly lists all return components (cik, filings, fundamentals, etc.) and notes limitations. Sufficiently complete for a complex tool with multiple data sources.

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 reinforces that value expects ticker or zero-padded CIK and that type is currently limited to 'company'. Adds practical usage context.

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

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

The description clearly states it provides a full cross-source profile of a US public company in one parallel call. It uses specific verbs like 'profile' and distinguishes from sibling tools such as compare_entities and 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 advises to prefer this tool over chaining multiple single-pack lookups for holistic views, and specifies that names are not supported, directing to resolve_entity first. Clear when to use and when not.

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 and destructiveHint=true. The description adds usage context but not additional behavioral traits like what happens if the key doesn't exist or if the deletion is permanent.

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

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

Two sentences, front-loaded with the action, no redundant words. Every sentence earns its place.

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

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

For a simple tool with one parameter, strong annotations, and no output schema, the description is nearly complete. It could mention that no return value is expected, but not necessary.

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

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

The schema has 100% coverage for the single parameter with description, so baseline is 3. The description does not add extra semantic meaning beyond the schema.

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

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

The description clearly states the action ('delete'), the resource ('memory'), and the means ('by key'). It distinguishes from sibling tools 'remember' and 'recall' by specifying deletion vs. storage and 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 explicitly lists when to use the tool (context stale, task done, clear sensitive data) and recommends pairing with 'remember' and 'recall', providing guidance on alternatives.

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

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

Discloses key behaviors: fetches page, extracts title/description/key links, emits standard markdown format. With annotations declaring readOnlyHint and destructiveHint false, the description adds useful detail beyond them.

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

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

Two concise sentences plus a bulleted list of use cases. No wasted words; purpose, behavior, and output format are 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 the annotations (readOnlyHint, idempotentHint, no destructive) and full schema coverage, the description sufficiently covers purpose, behavior, output format, and use cases. No output schema needed as output is a string.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description does not add significant new meaning beyond the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states it generates an llms.txt file for any URL, specifying the verb 'generate' and resource 'llms.txt' with scope 'for any URL'. It distinguishes from siblings by being the only tool focused on this task.

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 use cases ('getting a client's site indexed, drafting your own project, auditing a competitor') but does not explicitly mention when not to use or compare to alternatives. Context is sufficient for an agent.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. Description adds value by listing the exact return fields and mentioning the optional parameter, providing extra behavioral context beyond annotations.

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

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

Two sentences, front-loaded with action, no unnecessary words. Efficient and clear.

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 simple tool with one optional param and no output schema, description includes return fields and usage guidance, covering all necessary context.

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

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

Schema coverage is 100% (single parameter fully described). Description does not add extra meaning beyond schema, so 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?

Description clearly states 'List the caller's active subscriptions' – specific verb and resource. Includes return fields, differentiating 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 advises use 'to review what you're monitoring before adding more or to find an id to cancel', giving clear context for when to use this listing tool.

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

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

Annotations are minimal (all hints false), so the description carries the burden and fully delivers. It discloses the claim_token workflow, rate limit of 5 per identifier per day, free/no quota impact, and daily digest handling—details far beyond what annotations provide. 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 front-loaded with the core purpose followed by usage, exclusion, workflow, and constraints. Every sentence contributes value, though it is slightly dense and could be tightened without losing information.

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

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

Covers all essential aspects: purpose, scope boundaries, how to frame feedback, what to expect (claim_token), operational constraints, and cost. Despite no output schema, the description explains the main return artifact and resolution status sufficiently for an agent to invoke and follow up correctly.

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

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

Schema coverage is 100% and schema descriptions are already detailed, so baseline is 3. The description adds workflow semantics: filing without an account returns a claim_token, passing it back later with no other args reads status, and feedback should reference Pipeworx tools/packs, which clarifies the context and message fields. This is a meaningful supplement.

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 action ('Tell the Pipeworx team...') and clearly defines the resource (Pipeworx tooling). It enumerates feedback types (bug, feature/data_gap, praise) and explicitly distinguishes this from other MCP servers' feedback mechanisms, making it easy to select among siblings.

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

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

Provides explicit when-to-use conditions tied to feedback categories and a hard exclusion: only tools served by this Pipeworx connection; if the tool is from another MCP server, file it there. It also gives practical framing guidance (describe in terms of Pipeworx tools, don't paste the end-user prompt), which is especially 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?

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds value by detailing data source (CF analytics-engine), privacy (no PII), and caching (5min-1h). This exceeds what annotations alone provide.

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

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

The description is a single efficient paragraph with no wasted words. Key actions and outputs are front-loaded, and use cases are listed compactly. Every sentence earns its place.

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

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

Despite no output schema, the description explains the return format (top tools, top packs, total call volume). Data source, caching, and privacy are covered. The tool is simple (one optional param, safe semantics), so no additional detail 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?

The single parameter 'window' is fully described in the schema (100% coverage). The description adds context about how window length affects results ('shorter windows surface what's hot right now; longer windows show steady-state demand'), enriching the bare schema enum.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume' with a specific resource (Pipeworx trending) and time windows. It differentiates from siblings like 'discover_tools' by focusing on aggregated call volume trends rather than tool 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?

Three concrete use cases are listed (discovering hot data sources, confirming canonical tool, checking alignment). While it doesn't explicitly say when not to use it, the use cases provide clear guidance. No alternative tools are named, but the sibling list implies such alternatives exist.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral context: how monotonicity and partition checks work, semantic anchor (≥0.30 Jaccard), partition filter (placeholder drops), fill check logic, 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 thorough but slightly verbose. Every sentence adds value, but some sections could be condensed. Front-loaded with main purpose and modes, then detailed technical specifics. Very informative but not maximally 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?

Despite no output schema, the description fully explains the response structure: opportunities array with gap_pp, suggested_trade, reasoning; partition_check with sum_yes_prices, gap_from_1, etc.; fill_check with book depth details. Covers edge cases like low similarity and placeholder filters. Complete for a complex tool.

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

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

Schema covers 100% of parameters. Description adds value beyond schema by providing examples (event slugs like 'fed-decision-may-2026'), explanation of modes, and the fact that full Polymarket URLs are accepted. This helps the agent use parameters correctly.

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 via monotonicity violations and partition-sum checks, and distinguishes three modes (no args, event, topic) with specific use cases. It differentiates from sibling tools like 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 says when to use each mode: no args for trending scan, event for a specific market, topic for cross-event scanning. Provides alternative guidance ('For custom sizing use polymarket_fill_risk'). Clear when-not-to-use via fill check.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds extensive behavioral details: caching (1h KV), model family breakdown, tradeable-edge knobs, diagnostics, and handling of Fed bets. 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 efficiently packs useful information. It front-loads the main purpose and then logically structures segments, knobs, and diagnostics. Slightly verbose but each 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 complexity (9 parameters, multiple segments, no output schema), the description fully explains return structure, edge calculations, Kelly sizing, and diagnostics. It compensates for the lack of output schema with detailed behavioral context.

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

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

Schema coverage is 100% with detailed descriptions for each parameter. The tool description adds little parameter-level information beyond what the schema provides, though it explains how knobs interact. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also explicitly targets the use case 'what should I bet on today,' distinguishing it from siblings that may focus on tracking or arbitrage alone.

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

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

The description provides context for when to use the tool (e.g., discovering opportunities without paging hundreds of markets) and implies differentiation from siblings like polymarket_arbitrage, but it doesn't explicitly state when not to use it or offer 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 readOnly and idempotent. Description adds significant behavioral details: snapshot-based, cache-miss writes, TTL bounds, daily close computation, and no intraday data. 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?

Front-loaded with purpose, each sentence adds value. Slightly verbose but packed with necessary details. Could be tightened without loss.

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

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

Despite lacking an output schema, the description fully explains the response structure (tracked, expired, snapshot_dates) and all relevant constraints. Complete for a complex tool.

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

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

Schema coverage is 100% with descriptions. The description rephrases and ties parameter meanings to the tool's function ('lookback', 'snapshot family'), adding context beyond the schema.

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

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

The description uses specific verbs ('answers', 'telemetry') and identifies the resource ('edge persistence and decay'). It asks a clear question that defines its purpose and distinguishes it 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?

Provides explicit context on when it's useful (comparing fresh vs. old edges) and details limits (60-day TTL, daily closes). Lacks direct 'when not to use' but 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, openWorldHint, idempotentHint true, and destructiveHint false. The description adds valuable behavioral context: it walks the order book ladder, returns specific fields like slippage and verdict, and warns about forced directional risk and partial fills. No contradiction with annotations.

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

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

The description is lengthy but well-structured with clear sections (SINGLE-MARKET, BASKET) and bullet points for outputs. It front-loads the purpose and requirements. Every sentence adds value, though some minor redundancy could be trimmed for even tighter conciseness.

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 return values for both modes, covers all parameters, usage scenarios, and provides warnings. It also integrates context by referencing sibling tools. The description is complete for a risk-check tool.

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

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

Schema coverage is 100% with parameter descriptions, but the description adds significant meaning: explains the `side` parameter's default logic in basket mode, defines `size_usd` as settlement notional for baskets, and states the requirement that either `market` or `event` must be provided. 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's purpose: a realizable-vs-theoretical edge check against live CLOB order-book depth. It distinguishes between single-market and basket modes, specifies required inputs, and lists outputs. It also explicitly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by advising when to use this tool.

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

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

The description provides explicit usage guidance: use this before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above $500. It explains why (theoretical overround not capturable, partial fills cause directional risk), giving 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?

Beyond annotations (readOnly, idempotent), description details behavior: compatibility_warning conditions, temporal alignment, skipped cross types, and the unlikelihood of real trades. No contradiction with annotations.

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

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

Well-structured with bold section headers, no wasted words. Every sentence adds value given 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?

Comprehensive coverage of behavior, safety fields, edge cases (compatibility_warning, temporal_alignment). Compensates for absent output schema by detailing response fields.

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

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

Schema has 100% coverage, but description adds extra context: lists all 10 topics, explains override behavior, and clarifies the two modes. Slightly above 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 computes cross-venue spread between Kalshi and Polymarket, with two modes. It distinguishes from siblings by focusing on this unique cross-venue 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?

Provides explicit when-to-use guidance: two modes explained, warns that most pre-mapped topics return compatibility warnings, and clarifies when spreads are meaningless via temporal_alignment and compatibility_warning fields.

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 context (anonymous IP, BYO key hash, account ID) and explains the tool's non-destructive nature. No contradictions.

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

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

Four sentences, front-loaded with purpose, no superfluous content. Each sentence adds clear 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?

Complete for a simple retrieval tool with good annotations. Covers purpose, usage, scope, and relationships. No missing information.

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

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

Schema has 100% coverage with description of 'key' parameter. Description adds that omitting key lists all keys, but this is already in schema. Minimal additional 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?

Clearly states the tool retrieves a value by key or lists all keys, with specific verb+resource. Distinguishes from siblings 'remember' and 'forget'.

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

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

Explicitly describes when to use: to look up previously stored context without re-deriving. Mentions pairing with remember and forget for full lifecycle.

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

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

The description discloses that setting mark_read:true flags events as read, which is a write operation, but annotations declare readOnlyHint=true, indicating no state modification. This contradiction (annotation_contradiction=true) reduces the transparency score to 1, as per scoring guidelines.

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 with no verbose or redundant content. The first sentence front-loads the core purpose, making it 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?

Without an output schema, the description adequately explains return fields (source, citation_uri, payload) and mentions an alternative access method (alerts.json). It covers filtering and mark_read behavior. Minor gaps like limit defaults are covered by the 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 coverage is 100% with param descriptions, but the description adds value by explaining the effect of mark_read (ensuring next call shows newer events) and clarifying the use of since as an ISO timestamp. This goes beyond the schema, earning a 4.

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

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

The description clearly states the tool pulls fired events from a subscription feed, specifying the returned fields (source, citation_uri, raw payload) and optional filters. This verb+resource combination is specific and distinguishes it from sibling tools like list_subscriptions or search.

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

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

The description mentions polling works fine, but does not explicitly state when to use this tool versus alternatives. No exclusions or alternative tool references are provided, leaving usage context implied.

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

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

Beyond annotations (readOnly, idempotent), the description reveals parallel execution across sources, fallback logic, soft-fail for USPTO post-May 2025, and the return structure with citation URIs. No contradictions with annotations.

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

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

The description is compact but dense with information: example queries, source details, parameter hints, and alternative tool—all in one paragraph. Every sentence adds value, and the most critical info (purpose and usage) 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?

Despite lacking an output schema, the description fully describes the return format (changes grouped by source, total_changes, citation URIs). It also notes USPTO limitations, making it self-contained for an info retrieval tool with 3 params.

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 all 3 parameters (100% coverage), so baseline is 3. The description adds value by explaining the relative shorthand for `since` (7d, 30d, etc.) and that `value` can be a ticker or CIK. This extra context justifies a 4.

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

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

The description gives explicit use cases ('What's new with X', 'latest on Y') and names the specific resources it queries (SEC EDGAR, GDELT→GNews, USPTO). It clearly distinguishes from sibling entity_profile by stating when to use each.

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

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

The description explains fallback behavior between GDELT and GNews, and explicitly tells the agent to use entity_profile for static profiles. It provides `since` format examples but does not list scenarios where the tool should not be used.

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

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

Annotations indicate write, non-destructive, idempotent. Description adds scoping by identifier and persistence details (24 hours for anonymous, persistent for authenticated). No contradiction.

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

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

Three sentences, each earning its place: purpose, usage, and behavioral details. Front-loaded and concise with no redundancy.

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

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

Description covers purpose, usage, parameters, and behavioral details sufficiently. No output schema needed; the explanation is complete for an agent to use correctly.

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

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

Schema has 100% coverage with descriptions. Description adds naming conventions and value types (e.g., 'subject_property' and 'any text'), providing useful context beyond the schema.

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

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

The description clearly states the tool saves data for reuse later, specifying key-value pairs. It distinguishes from siblings like recall and forget by describing its role as storing versus retrieving or deleting.

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 advises using this tool when discovering something worth carrying forward, with concrete examples. It mentions pairing with recall and forget, but lacks explicit when-not-to-use guidance.

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

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

Beyond the read-only/idempotent annotations, it describes cascading lookups, graceful degradation when external sources fail, explicit `unresolved` identifier reporting, and source labeling. This adds significant behavioral context without contradicting 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 long but densely packed with valuable details, front-loaded with examples and a clear directive. Each sentence adds context about supported types, sources, and failure behavior, making it appropriately sized for the tool's 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?

Given no output schema, the description compensates well by explaining return values, unresolved identifier handling, source citations, and fallback behavior. It fully covers both supported entity types and edge cases, making it contextually 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?

The schema already describes both parameters and their values, so baseline is 3. The description adds extra meaning by explaining input formats (ticker, CIK, name) and what identifiers are returned (CIK, LEI, FIGI, RxCUI), enhancing the semantic understanding 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 resolves user-spoken names to canonical identifiers, with explicit examples and supported types (company, drug). It distinguishes itself from siblings by positioning it as the first tool to use when a name needs to be converted to an ID.

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

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

It explicitly says 'Use FIRST whenever you have a name but need an ID' and provides query examples. However, it does not mention specific alternative tools or when not to use it, so it lacks the when-not guidance that would make it a 5.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds that it returns the 'nearest place name', but does not elaborate on other behaviors like support for multiple results (via limit parameter) or any constraints. Consistent 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 extremely concise at one sentence, which is good. However, it sacrifices completeness for brevity, missing details that could be helpful.

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 an output schema, the description is too minimal. With 6 parameters and low schema coverage, it should provide more context about optional parameters and the exact nature of the output (e.g., what 'nearest place name' entails).

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 only 17% (only radius has description). The description does not provide any additional meaning for parameters like lat, lon, lang, layer, or limit. It fails to compensate for the poor schema coverage.

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

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

The description clearly states it performs reverse geocoding, converting coordinates to a nearest place name. While it is specific and use case is clear, it does not explicitly distinguish itself from sibling tools like 'search' which might do forward geocoding.

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?

No guidance is provided on when to use this tool versus alternatives. There is no mention of when it is appropriate or when not to use it, nor any reference to sibling tools.

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

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

Annotations already indicate readOnlyHint true, idempotentHint true, etc. The description adds that it probes each entity with ai_visibility_check, ranks by score, and returns ranked list with score/confidence/signal density per entity. 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?

Three sentences: first states action, second explains process, third adds use case. Front-loaded and efficient with no wasted words. Earns a perfect score.

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 4 parameters and no output schema, the description fully covers what the tool does (compares visibility), how it works (probes via ai_visibility_check), and what it returns (ranked list with metrics). Complete for its complexity level.

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 context: first entity treated as 'subject' for narrative, and explains the purpose of models, _apiKey, context beyond their schema descriptions. Adds moderate value.

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

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

The description clearly states 'Compare AI visibility across multiple entities side-by-side.' It specifies the action (compare), resource (AI visibility across entities), and distinguishes from siblings like ai_visibility_check (single probe) and compare_entities (generic 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?

It explicitly states 'Useful for competitive AI-marketing audits' with an example question, suggesting when to use. It implies alternatives (ai_visibility_check for single entity) but could be more explicit about when not to use. Still clear and valuable.

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 rich behavioral details: fans out across two services, returns specific data fields, handles partial failures gracefully, and mentions timing for bundlephobia first measurement (5-30s). 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 detailed but each sentence adds value. It is front-loaded with purpose, then usage, then return details, then caveats. Slightly long 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, the description sufficiently explains the return structure (summary block, per-advisory detail, links, alternative versions). It covers complexity, edge cases (partial failures, timing), and ecosystem boundaries, making it complete.

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

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

Schema description coverage is 100% for both parameters. The description adds minimal value beyond the schema (e.g., version defaults to latest), which aligns with the baseline score of 3.

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

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

The description clearly states it is a composite check for npm packages combining deps.dev and bundlephobia data. The verb 'scan' and resource 'dependency' are specific and the purpose is well-defined, distinguishing it from sibling tools which are mostly research/query tools.

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

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

Explicitly states when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also notes NPM ecosystem only in v1 and points to direct deps.dev usage for other ecosystems, providing 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?

Adds behavioral info (strong on partial queries) beyond the comprehensive annotations (read-only, idempotent). No contradictions.

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

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

Two succinct sentences, front-loaded with purpose, no fluff.

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

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

Given the rich schema, annotations, and output schema, the description is sufficient. Could mention return format but output schema covers that.

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

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

Schema has 100% coverage of parameter descriptions, so description adds no further parameter meaning beyond the schema.

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

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

Clearly states it does forward geocoding (place name to coordinates) and highlights strength on partial/autocomplete queries, distinguishing it from siblings like reverse.

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

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

Provides context that it excels on partial/autocomplete queries, but does not explicitly state when not to use or specify alternatives beyond the implied reverse geocoding.

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

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

Annotations declare readOnlyHint, idempotentHint, etc. Description adds substantial detail: embedding model (BGE-base-en), cosine similarity, 500-char windows, 200K char cap with truncation flag, and output format (passages with offsets and scores). No contradictions.

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

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

Single paragraph, three sentences. Front-loaded with purpose, then usage, then technical details. Every sentence earns its place with no fluff.

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

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

Despite no output schema, description explains return values (passages with offsets and scores, truncation flag) and embedding details. Covers all parameters and provides sufficient context for agent 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 provides full coverage of parameters with descriptions. Description adds usage context: e.g., 'pass the text you already pulled' and query examples, and explains limit purpose. Valuable but not essential beyond schema.

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

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

Clearly states 'Semantic search INSIDE a fetched record' with specific verb and resource. Distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and positioning as a tool for large documents.

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 ('when the record is too big to cram into the prompt') and mentions an alternative tool (ask_pipeworx_grounded). Lacks an explicit 'when not to use' statement, but guidance is clear overall.

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 return value, delivery channel behaviors (always-on feed, optional email/sms with limits, webhook with HMAC signing and auto-disable), going well beyond annotations.

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

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

Single dense paragraph packs detailed information without waste. Could benefit from bullet points for readability, but remains efficient and front-loads the key action and return.

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 all crucial aspects: types, parameter structures, delivery channels, prerequisites, behavioral notes (webhook signing, auto-disable). Sufficient for agent to use correctly without external references.

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

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

Adds significant meaning beyond schema: explains type enumerations with examples, provides exact structure for params per type, details delivery options with constraints. Schema coverage is 100%, yet description enriches understanding.

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

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

Clearly states 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' Identifies specific verb and resource; distinguishes from list_subscriptions 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?

Provides explicit prerequisites (Pipeworx OAuth account) and supported types, aiding in when-to-use decisions. Lacks direct exclusions but context implies it's for persistent monitoring, not one-off queries.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. The description adds the specific return format (category-bucketed examples with exact tool+argument shapes) and that calling without arguments gives a full spread. This enriches the behavioral understanding beyond annotations.

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

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

The description is a single paragraph but well-structured: it starts with alternate phrasings, then explains purpose, return format, and usage. While it contains some redundancy (multiple phrasings), every sentence provides value and the front-loading is effective.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description is comprehensive. It explains what the tool returns, how to use it (with/without topic), and when to use it (first-time onboarding). 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% for the single optional parameter. The description adds context beyond the schema by explaining the effect of omitting vs. specifying a topic, and lists example values. This adds meaningful guidance for parameter use.

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 category-bucketed example questions for an onboarding entry point. It distinguishes from siblings by marking itself as the first tool to use when unfamiliar with Pipeworx and references meta-tools as separate capabilities.

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

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

Explicitly says 'Use this FIRST' and describes when to use the topic parameter. It covers the primary usage scenario but does not explicitly state when not to use it or name alternative tools for specific queries, though the onboarding 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 indicate non-destructive mutation (readOnlyHint=false, destructiveHint=false, idempotentHint=true). Description adds that row is deactivated (not deleted) and historical events remain, providing context beyond annotations.

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

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

Two sentences: first states action, second provides key behavioral details. Front-loaded and no redundant words.

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

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

For a simple tool with one param, no output schema, and good annotations, the description covers purpose, ownership, deactivation behavior, and links to recent_alerts for history. Complete and 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% with one parameter (id) described as 'Subscription id (uuid) returned by subscribe.' Description does not add new info; baseline score 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 clearly states 'Cancel a subscription by id', specifying verb (cancel) and resource (subscription). It distinguishes from sibling 'subscribe' 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?

States ownership enforcement ('you can only cancel your own subscriptions'), guiding when to use and implicitly when not. Does not explicitly contrast with other tools like list_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?

The description goes well beyond annotations by disclosing the two-path routing, the return verdict values, the citation mechanism, and the crucial distinction between 'could_not_verify' (check failed) and 'unsupported' (no source). It includes an explicit caller warning about misinterpreting 'could_not_verify'. This is rich behavioral context that annotations alone do not provide.

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

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

The description is long but every section earns its place: example intents, routing logic, return values, and the caller warning. It is front-loaded with clear language and structured into coherent sections. Some redundancy exists ('confirm or refute' overlaps with 'fact check'), but overall it is efficient for the complexity it covers.

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, the meaning of verdict types, and error semantics. It also notes that it replaces 4–6 sequential calls, giving context on efficiency. No critical information appears missing for a complex tool like this.

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 fully with examples and constraints (100% coverage). The description adds semantic context by explaining the 'exact percent-delta math' and how tolerance_pct overrides implied tolerances, which clarifies parameter behavior. It does not introduce entirely new meaning but reinforces 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 does natural-language claim verification with specific verb ('verify', 'fact check') and resource ('against authoritative sources'). It distinguishes this from sibling search tools by emphasizing it checks factual correctness and returns a verdict. Examples of user intents and the two verification paths make the 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?

Explicit guidance is given: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains when to prefer the structured SEC path vs the grounded pipeline. However, it does not explicitly name alternatives or exclusion cases, though the singular purpose makes this less critical.

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