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 mark the tool as read-only, open-world, idempotent, and non-destructive, so the description adds meaningful behavioral detail: it routes questions across thousands of tools, fills arguments, returns stable pipeworx:// citation URIs, and makes one fast call on every tier. No statement 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?

The description is longer than average, but it is front-loaded with the key preference directive and uses the domain list, examples, and sibling-routing notes efficiently. Some redundancy exists between the domain enumeration and the examples, so it is not perfectly 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?

For a broad entry-point tool with no output schema, the description explains what the caller gets (structured answer, citation URIs) and how to decide between this tool and its close siblings. It is sufficiently complete for an agent to invoke it correctly and know when to escalate.

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

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

Schema coverage is 100%, so the schema already documents the question parameter and its five aliases with descriptions. The tool description contributes example question formats, but this is additive rather than necessary; the baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as a factual question-answering entry point that routes to internal tools and returns structured answers with citation URIs. It distinguishes ask_pipeworx from ask_pipeworx_grounded and deep_research by framing it as the default, lighter option.

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 trigger phrases ('what is', 'look up', 'get the latest'), concrete examples, and the instruction to prefer it over web search for most factual queries. It also names the exact conditions for stepping up to ask_pipeworx_grounded or deep_research, giving clear when-to-use and when-not-to-use guidance.

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

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

Beyond the annotations, it discloses live behavior: candidate routing improvements are enabled live when under test, no candidate is currently active, and it currently matches ask_pipeworx exactly. It also clarifies that this is a full working router, not a fallback, which is valuable behavioral context not present in annotations.

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

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

The description is front-loaded with the core purpose and provides necessary context about current status and candidate testing. The specific retirement date is marginally transient, but it earns its place by explaining why the tool currently behaves identically to ask_pipeworx. Slightly verbose but not wasteful.

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 natural-language router with a simple schema and read-only annotations, the description covers purpose, current behavior, relationship to the stable router, and response-shape consistency. Everything an agent needs to call it correctly and interpret its output is present.

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 aliases and the question field fully documented in the schema. The description adds no additional parameter semantics, but the baseline of 3 is appropriate since the schema already carries the burden.

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

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

The description states a specific action and resource: it is a beta version of ask_pipeworx acting as a universal router over 5,743 tools with the same arguments and response shape. It explicitly distinguishes itself from the stable ask_pipeworx by positioning itself as the experimental routing edge.

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

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

It gives clear guidance: "Use it exactly like ask_pipeworx when you want the newest routing." This implies the stable ask_pipeworx is the alternative for normal/stable routing. It does not fully spell out when not to use it, but the experimental-edge framing makes the intended use 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?

With annotations already marking this as read-only, idempotent, and non-destructive, the description adds substantial behavioral detail: refusal behavior, refusal_reason enum, verbatim evidence, source and confidence fields, and the guarantee to use only tool-retrieved data. This goes far beyond what annotations alone communicate.

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

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

The description is dense and mostly earns its length, with return shapes compactly specified and the cost tradeoff front-loaded near the usage guidance. There is minor redundancy between the first sentence and the later use-case sentence, but no wasted words overall.

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

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

For a complex tool with no output schema, the description provides everything needed for correct selection and invocation: routing behavior, success/refusal response shapes, refusal reasons, example high-stakes domains, and sibling preference. Nothing critical is missing.

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

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

Schema description coverage is 100%, and the schema fully documents that all six parameters are aliases for the single required question. The description adds no per-parameter syntax or value guidance, so the baseline of 3 is appropriate.

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

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

The description clearly identifies this as a grounded, hallucination-resistant answer mode that reuses ask_pipeworx's routing but differs by extracting answers only from tool results. This distinguishes it from the main sibling ask_pipeworx without requiring the agent to open schemas.

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 it ('whenever an answer will be quoted, cited, or acted on') and when not to ('prefer ask_pipeworx for casual lookups'), including the concrete cost tradeoff of one extra LLM call. This gives the agent actionable decision criteria.

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

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

The description 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the bar for additional context is met richly: the description adds authentication requirements, parallel routing across 5,743 tools, gap reporting with explicit gaps[], contradiction detection, citation behavior, latency expectations, and the guarantee that findings are never invented. This far 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 long but every sentence earns its place: auth constraints, sibling routing, output packet contents, gap behavior, depth semantics, citation resolvability, and latency are all packed densely with no filler. It is front-loaded with the most decision-critical fact (account requirement) and then builds logically through use cases, behavior, and performance.

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

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

For a complex tool with no output schema, the description is remarkably complete: it explains the findings packet structure, the gaps[] field, contradictions[], hop field, citation_uri, semantic excerpting, and expected latency. An agent has enough context to invoke it correctly, interpret its output, and know when to route elsewhere.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics beyond the schema: it explains what 'standard' and 'thorough' do at the behavioral level (gap recovery, lead chasing, contradictions[] scan) and gives concrete example questions for the question parameter. This enriches the enum meanings without contradicting 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 immediately names a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1500 STRUCTURED data sources' in one call. It also sharply distinguishes itself from siblings by saying 'this is NOT open-web search' and naming ask_pipeworx as the alternative, so an agent can confidently separate them.

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?

Usage guidance is explicit and actionable: it states when to use deep_research ('broad/multi-part questions over structured data'), when to use ask_pipeworx instead ('single lookup', 'BREAKING or colloquial CURRENT-NEWS'), and even the auth condition ('If you are not signed in, use ask_pipeworx instead'). This leaves no ambiguity about tool selection.

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

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

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?

Beyond the readOnly/idempotent annotations, the description discloses fan-out behavior across eight sources, soft-failure of USPTO patents, expected empty fda_products for non-biologic companies, and sources_used/sources_failed semantics. This is exactly the operational detail an agent needs to interpret empty results as real 'no data' rather than bugs.

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 and dense, but it is front-loaded with the core promise and 'ALWAYS PREFER' guidance before enumerating outputs and edge cases. The example list could be trimmed, yet nearly every clause carries operational 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?

There is no output schema, so the description rightly takes on the burden of describing the returned fields: cik, resolved_to, recent_filings with URIs, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI. It also covers input constraints, failure modes, and source-status reporting, making it complete for safe 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 coverage is 100%, so the baseline is 3; the description adds meaningful value by explaining that type accepts 'company' or 'ticker' interchangeably, that value can be a ticker, zero-padded CIK, or name, and that name resolution goes through SEC EDGAR. This goes beyond the schema's basic field descriptions.

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

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

The description opens with concrete user phrasings and states the core purpose: 'full cross-source profile of a US public company in ONE parallel call.' It names specific sources and output sections, making the tool's scope unmistakable and distinguishing it from single-source lookups.

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

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

It explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' naming the alternative and the triggering condition. It also clarifies accepted input forms and what happens for private companies, so an agent knows when to expect a resolved:false result.

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?

Annotations already declare readOnly/openWorld/idempotent/non-destructive, and the description adds substantial behavioral disclosure beyond that: both modes run the identical token-overlap matcher, returned pairs may still carry compatibility codes, gross spreads exclude Kalshi fees, unknown legs are never paired, and temporal_alignment null means 'unknown', not 'aligned'. This is exactly the kind of caveat-rich behavior an agent needs.

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

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

The description is long, but the length is earned: with no output schema, it documents return fields, compatibility codes, skipped counters, and fee behavior. It is reasonably front-loaded (definition and modes first), though the dense all-caps labeling and long code list make it harder to scan than it could be with actual bullets.

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

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

For a tool with no output schema and a complex return contract, the description covers the main output (leg prices, top_spreads_pp, flags), all compatibility codes, skipped_unclassified/low_confidence_pairs, temporal alignment semantics, and the gross-vs-net fee caveat. Nothing needed to invoke or interpret the tool correctly is obviously missing.

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

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

All three parameters are already documented in the schema (100% coverage), so the baseline is 3. The description adds real semantic value by explaining that topic auto-fetches the matching event on each venue, that the two explicit parameters override the topic-mapped side, and that both modes use the same matcher — so a 4 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 opens with a precise definition — 'Cross-venue spread between Kalshi and Polymarket for the same resolving question' — and specifies two modes plus the key output (top_spreads_pp). It is clearly a comparison/matching tool rather than an edge-finder, but it never names sibling tools like polymarket_arbitrage or polymarket_edges to draw an explicit line, so it stops short of full sibling differentiation.

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 mode selection (topic pre-mapped shortcuts vs explicit kalshi_event_ticker + polymarket_event_slug) and warns that pre-mapped topics frequently yield compatibility_warning and are not necessarily tradeable. It doesn't say when to prefer a sibling tool such as polymarket_arbitrage or polymarket_edges, so exclusions/alternatives are absent.

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?

Annotations already mark the tool as read-only, idempotent, and non-destructive, and the description adds meaningful behavior beyond that: graceful degradation when GLEIF/OpenFIGI are unavailable, explicit reporting of unresolved identifiers, source labels for every identifier, and internal cascading through multiple lookup endpoints. No contradiction with 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 front-loaded with examples and the 'Use FIRST' instruction, which is good. However, the company details are packed into one very long, heavily parenthetical clause that is hard to scan, with nested asides and redundancies. It would benefit from bullets or shorter sentences, though most content is relevant.

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

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

For a tool with no output schema, the description is remarkably complete: it covers accepted inputs, supported entity types, output shape (identifiers, source labels, `unresolved`, `figi_candidates`), citation format for drugs, and degradation behavior. An agent has enough information to decide when to call it and what to expect back.

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

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

Although schema coverage is 100%, the description adds substantial semantic value: it specifies admissible input forms (ticker, CIK, ISIN, or company name; brand or generic drug name), explains the ISIN-to-LEI resolution path, and provides a critical formatting caveat to pass only the entity name and not trailing security-class words. This materially reduces invocation errors.

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

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

The description clearly states the tool's function: resolve a user-spoken name to canonical/official identifiers that other tools require as input. It names supported types (company, drug), lists the identifiers returned (CIK, LEI, FIGI, RxCUI), and gives example user phrasings. It differentiates itself from tools like entity_profile or reverse by focusing on name-to-ID resolution and explicitly says 'Use FIRST whenever you have a name but need 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?

The description gives an explicit trigger condition: 'Use FIRST whenever you have a name but need an ID.' It also explains behavior in ambiguous cases, such as returning `figi_candidates` when a name matches multiple instruments. It does not explicitly name alternatives or list situations where the tool should not be used, but the context is clear enough.

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

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

Annotations already 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.