Lens Org

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

Annotations declare it read-only and idempotent. The description adds billing context (free default, BYO key for Anthropic) and default model, which are behavioral traits not captured by annotations.

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

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

Two sentences: first states core function and default, second adds optional key info and return structure. No filler, 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?

Covers main aspects: purpose, models, key handling, return format. Lacks details on error handling, timeouts, or score computation, but adequate given annotations and schema.

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

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

Schema coverage is 100%, so baseline is 3. The description adds minor extra context (e.g., 'BYO key — you pay Anthropic directly') but does not significantly expand on 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 it probes LLMs for business/brand visibility and returns a score per model. It specifies default model and optional Anthropic probe, distinguishing it from sibling tools like 'scan_competitor_ai_presence'.

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

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

The description mentions use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') but does not explicitly state when not to use or suggest alternatives among siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds useful behavioral context: it fills arguments automatically, returns structured answers with citations, and is described as 'one fast call.' It does not detail failure modes or rate limits, but the annotations plus description are sufficient for safe invocation.

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 appropriately so for a broad router tool. It is front-loaded with 'PREFER OVER WEB SEARCH', then gives domains, trigger phrases, examples, and upgrade conditions. Every sentence serves a purpose and there is no redundant filler.

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

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

Given that there is no output schema, the description adequately explains what the agent will receive: a structured answer with stable pipeworx:// citation URIs. It also covers when to use the tool, when to escalate to alternatives, and what kinds of questions are in scope, making it complete enough for correct invocation.

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

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

Schema coverage is 100%, so aliases like q, query, prompt, text, and input are already documented. The description adds value by clarifying that the parameter is a free-form natural language question and by providing many concrete example phrasings, which helps the agent pass the user's raw query rather than trying to construct a structured tool call.

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 names a clear, specific action: it routes factual questions to one of 5,798 tools across verified sources and returns structured answers with stable pipeworx:// citation URIs. It is unmistakably distinct from web search and from siblings like ask_pipeworx_grounded and deep_research.

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

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

The description explicitly says 'PREFER OVER WEB SEARCH', specifies trigger phrases and example questions, and gives concrete upgrade paths: use ask_pipeworx_grounded for hallucination-resistant answers and deep_research for broad multi-part questions. It even notes that breaking-news questions are already handled by ask_pipeworx.

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 cover the safety profile (readOnlyHint, idempotentHint, openWorldHint, non-destructive), so the bar is lower, and the description adds genuinely useful behavioral context beyond them: the routing candidate can be 'enabled live whenever one is under test,' no candidate is active so behavior currently matches ask_pipeworx exactly, and the 'Falls back to nothing — this IS a full working router' note preempts the misconception that the beta is a stub. This is meaningful experimental-edge disclosure, though it could add what the response shape actually is.

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 beta identity and each sentence adds distinct value: identical surface, live-candidate behavior, current no-candidate state, usage instruction, comparison purpose, and non-stub reassurance. It is slightly verbose — '(same 5,798 tools, same arguments, same response shape)' restates 'identical,' and the 'retired on outcome evidence 2026-07-26' date is more granular than needed — but nothing is wasted.

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

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

For a simple one-required-parameter router with complete schema coverage and rich annotations, the description plus schema gives an agent everything needed to invoke it correctly. The remaining gaps are minor: it references 'same response shape' without describing it, and 'routing improvements' is never concretely explained, but the explicit equivalence to ask_pipeworx covers the practical invocation case.

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% — all six parameters are individually documented, five as 'Alias for question' and one as the canonical question parameter — so the schema fully carries parameter meaning. The description's 'same arguments' adds only meta-level confirmation, not param-specific semantics, which matches the baseline 3 for high schema coverage.

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

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

The description states the tool is a 'Beta version of ask_pipeworx: identical universal router' — a specific resource with a clearly implied routing/answering function, and it differentiates itself from the stable ask_pipeworx through the experimental-candidate framing. However, 'universal router' is jargon; the concrete user-facing function (submit a question and get routed to the best of 5,798 tools) is only inferred via 'Use it exactly like ask_pipeworx,' which prevents a 5.

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?

Gives an explicit usage condition: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also clarifies the current-state nuance — no active candidate means it presently matches the stable router — which is exactly what an agent needs to decide between this and ask_pipeworx. It does not provide an explicit when-not-to-use clause or name alternatives like ask_pipeworx_grounded, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, and the description adds substantial behavioral context: the full success return shape {answer, evidence, confidence, source, fetched_at}, the explicit refusal envelope with all five refusal_reason enum values, the processing pipeline (routes → fills arguments → fetches → extracts), and the cost implication of one extra LLM call. 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?

Every sentence earns its place: the headline trait comes first, followed by mechanism, return shapes, usage guidance, and cost trade-off. It is longer than average, but the density of unique behavioral information justifies the length; nothing is redundant with the schema or annotations.

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

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

With no output schema present, the description carries the full burden of explaining return values — and it does so comprehensively for both success and refusal paths, enumerating every refusal_reason. Combined with annotations covering safety and the schema covering the parameter, nothing an agent needs to select and invoke this tool correctly 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% — the schema already documents the single 'question' parameter and its five aliases (query, q, prompt, text, input). The description adds context about what the question feeds into (routing and extraction) but no format or syntax detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb-resource pair ('grounded answer mode' that 'EXTRACTS the answer using ONLY what the tool result contains') and distinguishes itself from the sibling ask_pipeworx by name ('Same routing as ask_pipeworx', 'Costs one extra LLM call vs ask_pipeworx'). The hallucination-resistant angle makes its identity unmistakable.

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

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

Explicitly names when to use it ('whenever an answer will be quoted, cited, or acted on'), gives concrete domains (financial verdicts, legal claims, medical lookups, public statements), and states the exclusion: 'prefer ask_pipeworx for casual lookups.' The alternative tool is named directly, leaving no inference required.

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

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

The description extensively discloses behavioral traits beyond the annotations, which already indicate read-only, idempotent, and non-destructive behavior. It details the resolution process, classification, fan-out, evidence packet structure, market match confidence, closed market handling, wide spread warnings, cancellation rules, and more. 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 very long and detailed, covering many aspects. While well-organized with sections like 'CLASSIFIERS', 'FAN-OUT EXAMPLES', etc., it could be more concise. Every sentence provides useful information, but the length may hinder quick parsing by an AI agent. A tighter focus on essential guidance would 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?

Given the tool's complexity (3 parameters, no output schema, rich behavior), the description is remarkably complete. It covers all states: low-confidence matches, closed markets, wide spreads, cancellation rules, response shapes, error signals, and fallback mechanisms. No gaps are evident.

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

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

With 100% schema coverage, the baseline is 3. The description adds value by providing examples for the 'market' parameter (slug, URL, question text), explaining the 'depth' enum options and defaults, and clarifying when to use 'include_raw'. This additional context improves the score above baseline.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' The verb 'Research' combined with the resource 'Polymarket bet' is specific and informative. The description differentiates from sibling tools like polymarket_edges by focusing on general research rather than just edge detection, though not explicitly.

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

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

The description provides clear usage guidance: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It gives examples of when to use the tool. However, it does not explicitly mention when NOT to use it or suggest alternatives, which would improve the score. Still, the context is clear.

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

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

The description adds significant behavioral context beyond annotations, including data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and return of paired data with citation URIs. Annotations already indicate read-only and idempotent, and description confirms non-destructive nature.

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

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

The description is concise and front-loaded with trigger phrases and purpose. Every sentence adds value, covering usage guidance, parameter behavior, data sources, and output hints without unnecessary elaboration.

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 minimally explains return format ('paired data + citation URIs') and mentions sorting. It covers all key aspects for a two-parameter tool with simple output, though more detail on output structure could improve completeness.

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

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

Schema coverage is 100%, so baseline is 3. The description enriches parameter semantics by explaining how the 'type' enum determines data sources and providing examples for 'values'. It adds meaningful 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 identifies the tool's purpose: side-by-side comparison of 2-5 companies or drugs. It lists trigger phrases and specifies the data pulled for each type, distinguishing it from single-entity tools like entity_profile.

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

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

The description explicitly instructs to prefer this tool over sequential lookups when comparing entities, and provides examples of when to use it. However, it does not directly mention when not to use or list alternative tools.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, so the description doesn't contradict them. It adds substantial behavioral context beyond annotations: account/signup requirements, parallel decomposition, verbatim evidence with gaps[] never-invented guarantee, citation resolution semantics, contradictions[], semantic excerpting, and latency expectations. This is model-rich disclosure of how the tool behaves.

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 information-dense and includes valuable content, but it is long and meandering — the first sentence packs account requirements and a URL into the main behavioral description, and the 'ever-invented' quirk is embedded in a parenthesis-heavy sentence. It earns its content but could be better organized with clear sections or bullet-like separation.

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 2-parameter read-only tool with full schema coverage and rich sibling context, the description is nearly complete. It covers when to use, expected latency, depth behaviors, output shape (findings packet, gaps, contradictions, citation_uri), and preconditions. No output schema, so the description carries the burden of return semantics — which it handles thoroughly. Minor gap: it doesn't define `hop` field meaning, but the overall context is 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%, so the schema already documents both parameters. The description still adds meaningful behavioral nuance beyond the schema: depth values map to facets/hops (quick=3 single hop, standard=3 plus recovery hop, thorough=6 paid), and it clarifies multi-part questions are acceptable. The description doesn't add format-level detail for question, but it does enrich depth semantics.

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 verb ('research'), resource ('Pipeworx's structured data sources'), and differentiates from open-web search and from sibling ask_pipeworx. It explicitly names what the tool is NOT (not open-web search) and mentions the alternative for signed-in/single-lookup cases, so an agent can distinguish it from siblings.

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

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

The description explicitly says when to use this tool: broad/multi-part questions over structured data ('compare X and Y's regulatory + financial exposure'), and when NOT to use it: if not signed in use ask_pipeworx, for a single lookup use ask_pipeworx. It also covers depth-level tradeoffs and expected latency.

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. The description adds valuable behavioral context: it returns full input schemas with curated examples, and each result is ready to call directly. 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?

Two sentences: first states purpose, second gives usage context and return details. Every sentence is necessary and efficient. No fluff.

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

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

The description explains the return format (top-N tools with names, descriptions, full schemas, examples) and that results are ready to call. Given no output schema, this adequately covers what the agent needs to know.

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

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

Schema description coverage is 100%, so baseline is 3. The description reiterates the purpose of the query parameter and lists aliases, but does not add significant new meaning beyond what the schema already provides. Examples in the schema help.

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 that the tool finds tools by describing data or task, listing many domains. Differentiates from siblings by suggesting to call first when many tools are available. The verb 'discover' is specific and the description provides concrete examples.

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

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

Explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist for: [list]' and includes a strong guideline: 'Call this FIRST when you have many tools available.' Also notes that results are ready to call directly, implying no second lookup needed.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, and the description substantially enriches this with operational details: fan-out across multiple data sources, soft-fail behavior for the USPTO PatentsView API sunset, 'empty section is a real no-data, not a bug', private companies returning resolved:false with a notes line, GDELT→GNews fallback, and SEC EDGAR name resolution. These details go well beyond what annotations provide and help the agent interpret results correctly.

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 information-dense, and it is well structured: user intents and the core purpose are front-loaded, followed by the source fan-out, return-section semantics, and parameter guidance. While every sentence carries meaningful operational nuance, the length edges toward verbose; a more compact grouping of return fields could improve scannability without losing detail.

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

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

There is no output schema, so the description must carry the burden of explaining return values, and it does: it enumerates each return section (cik, company_name, recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI) with important qualifications such as 'soft-fails', 'expected, not a failure', and 'sources_used/sources_failed'. For a complex multi-source tool with no output schema, the description is remarkably 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%, so the schema already documents both parameters. The description adds value by providing concrete examples ('AAPL', '0000320193', 'Moderna'), clarifying that type accepts 'company' or 'ticker' interchangeably with identical behavior, and explaining edge cases like private-company resolution. This goes beyond the schema's baseline documentation.

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

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

The description opens with concrete user intents ('Tell me about X', 'brief me on Tesla', 'company profile for Microsoft') and states the core function: 'full cross-source profile of a US public company in ONE parallel call.' This clearly identifies the tool's verb, resource, and scope, and distinguishes it from sibling tools like compare_entities and resolve_entity by focusing on a holistic single-entity profile rather than comparison or bare resolution.

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

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

The description gives explicit usage direction: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' This clearly states when to choose the tool over chained alternatives. However, it does not explicitly name sibling tools such as compare_entities or deep_research or state when those should be preferred instead, so there is clear context but no explicit exclusions.

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

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

Annotations already declare destructiveHint=true. The description adds specific context that it deletes memory by key and clears sensitive data, which is valuable 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 wasted words. Very concise and 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 simplicity (1 param, no output schema), the description is complete. It covers purpose, usage context, and parameter.

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

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

Schema coverage is 100% and already describes the 'key' parameter. The description does not add extra semantics beyond what schema provides.

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

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

The description clearly states 'Delete a previously stored memory by key', specifying a verb (delete) and resource (memory). It distinguishes from siblings by mentioning pairing with remember and recall.

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

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

The description provides clear when-to-use context: 'when context is stale, the task is done, or you want to clear sensitive data'. It does not explicitly state when not to use, but gives sufficient guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. Description adds valuable process details (fetches, extracts title/description/key links) and output format (standard llms.txt markdown, single text blob). No contradictions.

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

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

Three sentences pack purpose, process, output format, and use cases efficiently. No wasted words; front-loaded with main action.

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

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

Covers all key aspects: purpose, process, output format, and usage examples. No output schema needed since description notes output is a text blob. Could mention error handling for invalid URLs, but not required for typical use.

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 url and max_links. Description doesn't add new parameter semantics beyond stating defaults already in schema. 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?

Description uses specific verb 'Generate' with explicit resource 'llms.txt file' for any URL. Includes intended audience (ChatGPT, Claude, Perplexity) and differentiates from sibling tools by focusing on file generation rather than analysis or scanning.

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

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

Lists three concrete use cases (client indexing, own project drafting, competitor auditing). While it doesn't explicitly contrast with siblings like ai_visibility_check or scan_competitor_ai_presence, the examples provide clear context for when to use.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds the list of returned fields (id, type, params, etc.), which is useful but minimal given annotations cover safety and idempotency.

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

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

Two sentences, front-loaded with purpose, no unnecessary words. Every sentence adds value.

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

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

The tool is simple with one optional boolean parameter and no output schema. The description lists return fields, making it complete enough for an agent to use correctly.

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

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

Schema coverage is 100% with a clear description for the only parameter (include_inactive). The tool description does not add further semantics 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 lists the caller's active subscriptions, specifying the verb (list) and resource (subscriptions). It distinguishes from sibling tools like subscribe and unsubscribe by focusing on listing.

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 usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This guides when to use it, though it doesn't explicitly mention when not to use.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds authentication requirements (Bearer token) and specifics about returned data (claims, inventors, priority dates), which are not 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 a single, well-structured sentence (via semicolon) that conveys purpose, required parameter, authentication, and output. Every part is essential, with no wasted words.

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

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

Given the single parameter, rich annotations, and presence of an output schema, the description adequately covers purpose, auth, and return fields. It lacks mention of behavior when the record is not found, which is a minor gap.

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

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

With 0% schema description coverage, the description must compensate. It only mentions 'by its lens_id' without explaining the format or what lens_id represents. The example 'US10123456B2' is in the schema but not elaborated in the description.

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

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

The description clearly states 'Fetch a single Lens.org patent record by its lens_id', specifying the verb, resource, and unique identifier. It distinguishes from the sibling 'patents_search' tool by targeting a single record.

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 indicates it fetches a single record by ID and requires a Bearer token, giving clear context. It does not explicitly exclude usage for search or mention alternatives, but the contrast with 'patents_search' is 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. Description adds authentication requirement, return size limit (up to 1000), and specific fields returned. 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, well-structured sentence conveys all essential information without any redundancy or missing critical details.

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

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

Given presence of output schema, description adequately covers search behavior, returned fields, and authentication. Could optionally mention pagination (from/size) but schema covers it.

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

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

Schema coverage is 67%; description clarifies query parameter supports free-text or Lucene syntax and ties size parameter to the 1000-record limit. 'from' parameter lacks additional context but overall adds value beyond schema.

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

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

Description clearly states the verb 'Search' and resource 'Lens.org patent database'. It mentions returning up to 1000 records, which helps distinguish from a potential singular patent tool, but does not explicitly differentiate from sibling 'patent'.

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?

Only mentions authentication requirement ('requires Bearer token'). No guidance on when to use this tool versus alternatives like 'patent' or other search tools, nor any exclusions or prerequisites.

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

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

The annotations provide no hints (all false), so the description carries full burden. It discloses rate limiting ('Rate-limited to 5 per identifier per day'), quota exemption, and the claim_token flow for checking status, plus team read frequency. 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 paragraph-length but every sentence provides distinct value: purpose, usage scenarios, exclusions, content guidance, token mechanics, rate limits. It is front-loaded with the core purpose 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?

Given four optional parameters, one nested object, and no output schema, the description sufficiently explains return behavior (claim_token), usage constraints, and exclusions. An agent can correctly invoke this tool with or without 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 covers all four parameters with descriptions, but the description adds semantic guidance: 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt,' and illustrates claim_token usage with a concrete call. This exceeds the schema's bare 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 opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' clearly stating the tool's purpose. It enumerates feedback types (bug, feature, data_gap, praise) and explicitly restricts to tools served by this Pipeworx connection, distinguishing it from sibling tools like ask_pipeworx or discover_tools.

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

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

The description provides explicit when-to-use criteria: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also specifies when not to use it, directing users to file with other MCP servers instead, and explains how to check status via claim_token.

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, openWorldHint, idempotentHint, and non-destructive. The description adds valuable behavioral details: 'cached 5min-1h depending on window,' 'self-aggregating signal from CF analytics-engine,' and 'no PII.' No contradictions.

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

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

Three sentences, zero filler. The main output is stated upfront, followed by use cases and operational details. Every sentence adds value.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description fully covers purpose, parameters, use cases, caching, and data source. No gaps given the tool's complexity.

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

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

Schema coverage is 100% with a detailed description for the sole 'window' parameter. The description adds extra semantic guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand,' which helps parameter selection beyond the enum values.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume over a recent window.' It distinguishes from sibling tools like 'ask_pipeworx' or 'discover_tools' by focusing on aggregated trending data from other AI agents.

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

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

The description provides three specific use cases: discovering hot data sources, confirming canonical tools, and checking alignment with agent demand. It does not explicitly exclude scenarios or mention alternatives, but the usage context is clear and actionable.

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

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

Adds extensive behavioral context beyond annotations: describes monotonicity checks, partition_sum logic, Jaccard similarity threshold, placeholder filtering, fill check against CLOB depth, and conditions for not trading.

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

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

Long but well-structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Front-loads key info. Slightly verbose but every sentence adds value.

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

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

Highly complete given complexity: covers return structure (opportunities[], partition_check), edge cases (placeholder slugs, low similarity), and integration with fill_check. No output schema but description compensates admirably.

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

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

Schema coverage is 100%, but description adds meaning: explains that event accepts slugs or full URLs, topic is a seed question, and what each parameter triggers. Richly compensates for lack of output 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 finds arbitrage opportunities via monotonicity violations and partition-sum checks on Polymarket. It distinguishes three modes (no args, event, topic) with specific verbs and resources.

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 explains when to use each mode: no args for trending scan, event for a specific market, topic for cross-event scanning. It also provides alternatives like polymarket_fill_risk for custom sizing.

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

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

The description goes far beyond annotations, detailing caching behavior (1h KV level), response structure with diagnostics, edge calculation methodology, and specific handling of Fed bets. It fully discloses behavioral traits.

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

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

The description is very long and dense, covering extensive methodology and response fields. While well-structured, it is not concise; every sentence may not be essential for quick agent comprehension.

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 (by_segment, diagnostics, edge fields), all parameters, and caching. It is 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%, and schema descriptions are already detailed. The tool description provides additional context and examples for some knobs, but adds limited new 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 tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, with a specific use case. However, it does not explicitly distinguish from sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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

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

The description provides clear context for when to use ('what should I bet on today') and explains the tradeable-edge knobs and filters. However, it lacks explicit guidance on when not to use this tool or mention of 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 declare readOnly, idempotent, not destructive. Description adds details: data from daily snapshots, history limited to 60-day TTL, snapshots on cache-miss (gaps indicate no scan), and decay computed from daily closes. No contradictions.

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

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

The description is long but front-loads the purpose, then organizes response fields and limitations. Every sentence adds value, though slight condensation 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?

No output schema requires the description to explain return values in detail, which it does: tracked[] with edge_pp_net time-series, trend, decay; expired[] with lifespan; snapshot_dates[]. It also covers limitations (60-day TTL, snapshot gaps). Complete for this 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?

Input schema covers both parameters (days, window) with descriptions. The description repeats this without adding new meaning beyond defaults and clamping. Schema coverage is 100%, so baseline 3 applies.

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

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

The description starts with 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots', clearly stating what it does. It contrasts a fresh wide edge vs a 3-week-old wide edge, distinguishing it from sibling tools like polymarket_edges (raw edges) and polymarket_arbitrage.

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

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

The description explicitly states the tool answers 'how long has this edge existed and is it shrinking?' and provides a concrete example of when it's useful. However, it does not explicitly state when not to use it or list alternatives, though the sibling tools suggest context.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and openWorldHint. The description adds substantial behavioral context: it walks the order-book ladder, returns fill details like slippage and shares_filled, and for basket mode highlights forced directional risk. It warns about partial fills causing unhedged directional positions, which is critical for safe usage.

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

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

The description is relatively long but well-structured with clear separation between single-market and basket modes, using all-caps for emphasis. Every sentence adds value, though slightly verbose; it could be trimmed without losing meaning.

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

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

With no output schema, the description comprehensively lists all return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, etc.) and explains edge cases like thin_legs and forced_directional_risk. It is complete for an agent to understand what information the tool provides and how to interpret results.

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

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

Schema coverage is 100%, providing basic descriptions for all 4 parameters. The description adds mode-specific interpretation (e.g., side defaults for basket auto, size_usd interpreted as spend vs target proceeds vs settlement notional) and clamps, which goes beyond schema but is not exhaustive.

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

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

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' with specific modes (single-market vs basket). It explicitly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by stating when to use this tool before acting on their signals.

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

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

The description provides explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains the required parameters (market or event) and warns against partial basket fills converting arbs into unhedged positions, covering both when and when not to use.

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

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

Annotations only signal readOnly, idempotent, openWorld, and non-destructive. The description adds substantial behavioral disclosure: matching is keyword/word-overlap based and not verified against a shared resolution source, unclassified legs are never paired, temporal_alignment null means 'unknown' rather than 'aligned', Kalshi fees are not modeled so spread_pp is gross, and compatibility warnings can appear even when pairs are returned. 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 front-loaded with purpose and uses clear internal labels like 'TWO MODES', 'RESPONSE', and 'SAFETY FIELDS,' making a long text navigable. It is somewhat repetitive across the compatibility-code list and per-entry flags explanation, so it is not maximally concise, but every major section does earn 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?

There is no output schema, so the description fully shoulders the burden of explaining the return shape. It covers top_spreads_pp, compatibility_codes, skipped_unclassified, low_confidence_pairs, temporal_alignment semantics, fees_note, and skipped-cross counters, and even defines each compatibility code. An agent has enough context to invoke the tool and interpret responses correctly.

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

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

Schema coverage is 100%, so the schema already documents the topic list and override semantics well; baseline is 3. The description adds value by framing topic as a pre-mapped shortcut layer, confirming both modes run the identical token-overlap matcher, and clarifying that custom pairings produce the same disclosures. The ticker/slug parameters themselves gain little beyond the schema, keeping this at 4 rather than 5.

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 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' which clearly identifies the resource and the core computation. It expands on this with two modes and the outcome-level matching scope, though it never explicitly names or differentiates itself from sibling tools like polymarket_arbitrage or polymarket_edges.

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

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

The 'TWO MODES' section explicitly tells an agent when to use pre-mapped topic shortcuts versus explicit ticker/slug pairing, and warns that most pre-mapped topics currently return compatibility warnings. It does not include an explicit 'when not to use this tool' statement against sibling tools, so it falls just short of full marks.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds context about the listing behavior when omitting key and scoping to identifier, which supplements annotations without contradiction.

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

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

The description is three sentences, each serving a clear purpose: definition, usage context, and scoping/pairing. 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?

Given the tool's simplicity (one optional parameter, read-only), the description covers the key behaviors: retrieval, listing, scoping, and pairing with remember/forget. No gaps for an agent to infer.

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

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

Schema coverage is 100% with a clear description for the 'key' parameter. The tool description reiterates the listing behavior but adds no new semantic detail beyond the schema.

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

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

The description clearly states the verb 'retrieve' and the resource 'value previously saved' or 'list all saved keys'. It distinguishes itself from sibling tools 'remember' and 'forget' by naming them directly.

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

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

The description provides concrete examples of when to use (look up stored context like ticker, address, notes) and explains scoping. It mentions pairing with remember/forget, but does not explicitly state when not to use it.

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

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

Annotations already indicate read-only and idempotent. The description adds value by detailing what each event carries, the effect of mark_read, and that polling is safe. 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?

Efficient single paragraph with front-loaded purpose. Every sentence contributes value without redundancy.

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

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

Covers return content, parameter usage, side effects, and alternative access methods. No gaps given the tool's complexity and lack of output schema.

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

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

Schema coverage is 100%, so the description adds limited new meaning beyond reinforcing filtering and mark_read behavior. 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 states the tool pulls fired events from the subscription feed, specifying the resource (feed) and action (pull). It distinguishes from sibling tools, as none appear directly related to alerts or feed 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?

Provides guidance on filtering by type and since, explains mark_read behavior for subsequent calls, and mentions polling and alternative HTTP access. While it doesn't explicitly state when not to use, the context is sufficient.

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

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

Annotations already indicate readOnlyHint=true (safe read) and the description adds detailed behavioral context: fan-out to multiple sources (SEC, GDELT→GNews fallback, USPTO with soft-fail), return structure (changes[] with sources and citation URIs), and failure behavior. 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 a single dense paragraph but effectively front-loads purpose and example queries. While concise and information-rich, it could be slightly more structured (e.g., bullet points) for easier scanning without losing any 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 no output schema, the description adequately explains the return format (changes[], total_changes, citation URIs), covers multiple data sources and their failure modes, and provides a complete overview for a 3-parameter 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 for all three parameters. The description adds significant value: explains the `since` parameter with ISO date and relative shorthand examples ('30d', '1y'), suggests typical values ('30d'), and clarifies type/value formats (ticker or CIK).

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 change feed for companies, listing specific example queries and explicitly distinguishing it from the sibling tool 'entity_profile', which provides static profiles.

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

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

The description includes explicit example use cases (e.g., 'What's new with X'), explains the window parameter usage, and advises when to use the alternative tool 'entity_profile' instead, providing clear guidance on 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?

Description adds context beyond annotations: key-value storage scoped by identifier, persistence differences (authenticated vs anonymous). Annotations already readOnlyHint=false, destructiveHint=false, idempotentHint=true — description aligns and adds detail.

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 fluff, each sentence adds value: usage trigger, storage type, persistence details, sibling pairing.

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?

All necessary information is present: purpose, usage, parameters (via schema), persistence, sibling tools. No output schema needed for a write tool.

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

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

Schema coverage is 100%, so baseline 3. Description provides example keys and values but adds little beyond 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?

Description uses specific verb 'save' and resource 'data' with clear examples of what to store (ticker, address, preference). Distinguishes from siblings 'recall' and 'forget'.

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

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

Explicitly states when to use: 'when you discover something worth carrying forward... so you don't have to look it up again.' Mentions pairing with recall/forget and scoping differences.

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 substantial behavioral context beyond those: it explains graceful degradation when LEI/FIGI enrichment is unavailable, the figi_candidates ambiguity behavior, explicit reporting of unresolved identifiers under 'unresolved', source labelling, and internal cascading through lookup endpoints. 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 dense, and it is front-loaded with purpose and usage guidance. Every section adds operational detail relevant to a complex lookup tool. Some parenthetical asides and enumerated examples could be restructured for easier scanning, but there is no filler.

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

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

With no output schema and only two parameters, the description carries the full burden of explaining behavior. It covers what identifiers are returned for each type, how ambiguity is handled, how failures are surfaced, and how partial data degrades gracefully. The agent has enough information to invoke the tool correctly and interpret unusual results.

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

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

Schema coverage is 100%, but the description adds significant practical meaning beyond the schema. It gives concrete accepted input examples (AAPL, 0000320193, 'ozempic'), explains the ISIN-to-LEI mapping behavior, and provides detailed guidance for bond lookups, including passing the issuer exactly as printed and avoiding trailing security-class words. This goes well beyond the schema's simple type/value descriptions.

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

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

The description clearly states the tool's purpose: resolving a user-spoken NAME into canonical/official identifiers that other tools require as input. It names the verb ('resolve'), the resource ('canonical/official identifiers'), lists the supported entity types, and differentiates it from sibling tools by positioning it as the first-step ID lookup ('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 explicitly says 'Use FIRST whenever you have a name but need an ID,' which is a clear when-to-use condition. It also mentions that the tool replaces 2-3 manual lookups. However, it does not explicitly name sibling alternatives or state when not to use it (e.g., when you already have an ID), so it stops short of a full 5.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds behavioral context: it probes each entity with 'ai_visibility_check', ranks results, and returns a ranked list with score, confidence, and signal density. No contradictions to 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 core action and output, no wasted 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 tool with 4 parameters and no output schema, the description covers the purpose, method (using a sibling tool), and output summary (ranked list with metrics). It could mention return format specifics, but overall sufficient for an agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining that the first entity is treated as the 'subject' and that probes use 'ai_visibility_check'. It also clarifies entities are brand/business/product names, which is beyond the schema's generic description.

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

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

The description clearly states it compares AI visibility across multiple entities, using specific verbs like 'compare', 'probes', 'ranks', and 'surfaces'. It distinguishes itself from siblings like 'ai_visibility_check' (single entity) and 'compare_entities' (generic compare).

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

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

The description provides a concrete use case ('competitive AI-marketing audits') and an example question. It implies when to use this tool versus a single entity check, but does not explicitly state when not to use or list 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 indicate idempotent, read-only, and non-destructive behavior. The description adds valuable context: it fans out to two sources, returns specific fields, degrades gracefully on partial failures, and mentions a 5-30s timeout for bundlephobia first measurement. 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 dense and well-structured: composite purpose, usage guidance, return fields, limitations, error handling. It is somewhat long but every sentence adds value. Could be slightly more concise, but the richness justifies the length.

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, yet the description thoroughly explains the return: summary block fields (is_latest, license, etc.), per-advisory detail, links, and alternative versions. It also covers partial failures and ecosystem scope. The description is complete for agents to understand what to expect.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add new parameter semantics beyond what the schema already provides (e.g., version defaults to latest). However, the tool's purpose implies usage, but no extra param details are given. Score remains at baseline.

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

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

The description clearly states it is a composite check for deciding whether to add an npm package, fanning out to deps.dev and bundlephobia. It specifies the ecosystem (NPM v1) and distinguishes alternatives for other ecosystems. The verb 'scan_dependency' and the detailed return block make the purpose unmistakable.

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

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

Explicitly says when to use: when an agent asks about safety, popularity, size, or cost of adding a package. It also notes that for other ecosystems, one should use deps.dev:version directly, providing clear alternatives. Partial failure handling and timeout behavior are also described, guiding expectation management.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. Description adds value by noting authentication requirement and listing return fields (abstract, authors, citations, open-access links). 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?

Single sentence, no redundant words. Front-loaded with main action. Every word 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?

With output schema present, description adequately covers primary return information. Lacks details on error behavior for invalid lens_id. But for a simple one-parameter fetch tool, it's largely 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 0%, so description must compensate. It provides context that the parameter is a Lens.org identifier but does not specify format, constraints, or validation rules beyond the example. More detail needed for the single parameter.

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

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

Description uses specific verb 'Fetch' and identifies the resource as 'a single Lens.org scholarly work by its lens_id'. It clearly distinguishes from the sibling 'scholarly_search' by specifying single work 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?

Description mentions requirement of Bearer token, which is a usage prerequisite. However, it does not explicitly state when to use this tool versus alternatives like 'scholarly_search', nor does it provide exclusion criteria.

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

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

Adds authentication requirement and expected return fields beyond annotations (readOnlyHint, idempotentHint). No contradiction with annotations.

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

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

Single sentence with clear structure, front-loads purpose. Uses semicolon effectively but could be more 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?

Covers return fields and basic behavior but fails to explain pagination parameters ('from', 'size') given schema coverage gap. Output schema partially mitigates return format documentation.

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 no descriptions (0% coverage). Description explains 'query' as free-text or Lucene but omits 'from' and 'size' parameters, which are only hinted as numbers. Insufficient to guide proper parameter usage.

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 verb 'Search', resource 'Lens.org scholarly works', and specifies result fields (title, authors, journal, year, DOI). Differentiates from siblings like 'patent' and 'patents_search' by focusing on scholarly works.

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?

Mentions authentication requirement ('requires Bearer token') but offers no guidance on when to use this tool versus alternatives (e.g., 'scholarly' sibling). Does not specify constraints or best practices for query type 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?

All annotations are already true (readOnly, idempotent, etc.) and the description adds significant behavioral details: embedding model (BGE-base-en), window size (500-char overlapping), similarity metric (cosine), character limit (200K chars with truncation flag). 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?

Very concise: 3-4 sentences front-loading core purpose, then usage guidance, then technical details (embedding, offsets, limit). Every sentence adds value without redundancy.

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

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

Despite no output schema, the description clearly states return format: 'top-N passages with character offsets and similarity scores'. Also addresses edge case (truncation). Complete for a search tool with good annotations.

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

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

Schema descriptions already cover all 3 parameters (100% coverage). The description enhances with additional context: text max length suggestion, natural-language query examples, and limit range (1-20). Provides value beyond schema.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' with specific verb and resource. It gives concrete examples (SEC 10-K, article) and distinguishes from sibling 'ask_pipeworx_grounded' by explaining the pairing workflow.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and describes how it saves context. Also explains pairing with ask_pipeworx_grounded. Lacks explicit when-not-to-use but provides strong contextual guidance.

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

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

Discloses mutating (readOnlyHint=false), idempotent (idempotentHint=true), non-destructive behavior. Adds rich context: account requirements, type-specific params, delivery channel side effects (email, SMS with 10/day cap, webhook with HMAC and auto-disable). 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?

Reasonably concise given the complexity. Front-loaded with purpose, then organized by type and delivery. Every sentence adds value, but could be slightly tighter; still well above average.

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 necessary aspects: requirements, type-specific parameters, delivery options with constraints, return values (subscription ID, webhook secret), and how to retrieve alerts (feed pull). No output schema, but description fills in return behavior adequately.

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

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

Schema coverage is 100%, but description adds significant value: explains enum meanings (e.g., sec_8k items codes), provides detailed param examples for each type, clarifies delivery constraints (verified phone, daily limit, webhook signing). Goes far beyond bare schema descriptions.

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

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

Clearly states it creates a proactive monitoring subscription to a live-data event stream and returns a subscription ID. Distinguishes from sibling tools (list_subscriptions, unsubscribe) by focusing on creation.

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

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

Provides explicit when-to-use context: proactive monitoring with supported types, delivery options, and requirements (OAuth account, verified phone). Does not explicitly mention when not to use, but context is sufficient and no direct alternatives exist among siblings.

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

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

Annotations already mark it as read-only, idempotent, and non-destructive. Description adds behavioral details: it returns example questions with tool calls, no side effects, and can be called without arguments for broad coverage. No contradiction.

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

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

The description is well-structured with common questions at the start, then a clear explanation of functionality and usage. It is slightly verbose but every sentence adds value; no wasted words.

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

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

Given the tool's role as an onboarding entry point, the description is complete: it explains what it returns (categories, exact tool calls), how to use it (with/without topic), and when to use it. No output schema needed.

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

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

Schema covers 100% of parameters with a brief description. Description adds significant value by listing the acceptable topic values and explaining behavior with and without the parameter, going 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 ('Returns category-bucketed example questions') and clearly states the resource ('Pipeworx') and purpose (onboarding entry point). It distinguishes from siblings by being the first tool to use when learning what Pipeworx can do.

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 ('first when you do not yet know what Pipeworx can do'), provides alternatives ('meta-tools like ask_pipeworx, entity_profile'), and explains when to pass topic vs. omit.

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

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

Adds significant context beyond annotations: ownership enforcement, deactivation not deletion, and link to recent_alerts. 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?

Two sentences, front-loaded with action, each sentence adds unique information. No redundancy or fluff.

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

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

Covers purpose, side effects, and relationship to sibling tool. Lacks error handling details but acceptable for a simple operation with good annotations.

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

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

Schema covers param fully with description. Description adds no additional param details but does explain operation effect. 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?

Clearly states 'Cancel a subscription by id' with specific verb and resource. Distinguishes from siblings like subscribe and list_subscriptions by explaining deactivation vs deletion and link to recent_alerts.

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

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

Explicitly mentions ownership enforcement and that historical events remain available via recent_alerts, guiding when to use. Could explicitly mention when not to use but context is clear.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses crucial behavioral details: the dual-pipeline routing (structured SEC EDGAR vs. grounded), return value composition (verdict, value, citation, reasoning), and the precise meanings of 'could_not_verify' and 'unsupported' verdicts. It also explains the error structure (verification_error{stage,detail}) and explicitly warns not to treat 'could_not_verify' as evidence. 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 appropriately sized for the tool's complexity and is well-structured. It front-loads the purpose and trigger phrases, then provides routing details, return formats, and an important caller warning. Every sentence adds value, from the trigger list to the consolidation benefit. No fluff or redundancy.

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

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

Given the absence of an output schema, the description explains the return value structure (verdict, actual value, citation, reasoning) and defines the key ambiguous verdicts ('could_not_verify' and 'unsupported'). It covers all critical aspects an agent needs to invoke and interpret results correctly, including tolerance semantics and fallback behavior. The description is complete for a tool of this scope.

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

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

The input schema already documents both parameters thoroughly (100% coverage), so the baseline is 3. The description adds extra semantic context for 'claim' by explaining the company-financial vs. other-claim routing, and for 'tolerance_pct' by mentioning hallucination detection use cases. This goes beyond mere schema repetition, justifying a 4 rather than a 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 the tool's purpose: natural-language claim verification against authoritative sources. It provides specific trigger phrases like 'fact check' and 'verify the claim that,' and distinguishes this tool from general Q&A siblings by focusing on factual correctness of user statements. The explicit mention of replacing 4–6 sequential calls further clarifies its intended role.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' which is a clear when-to-use directive. It also explains the specialized paths for company-financial claims vs. other claims. However, it does not explicitly name alternative tools or state when NOT to use this tool, so it stops short of a 5.

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