Prozorro

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

Description adds behavioral context beyond annotations: mentions default model is free, Anthropic requires BYO key, and lists return fields (score, confidence, signals, raw_response). Annotations already declare readOnlyHint, etc., so the description complements well.

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

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

Description is four sentences with no wasted words. Front-loaded with primary purpose and default behavior, then optional configuration, output summary, and use cases. Each sentence adds distinct 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?

Covers purpose, default vs optional models, API key requirement, output structure, and use cases. Lacks error handling or rate limit information, but output schema is absent so description compensates reasonably well.

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 4 parameters. Description adds nuance: '_apiKey' is only needed if 'anthropic' in models, and 'context' helps disambiguate. Provides clarity 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?

Description clearly states the tool probes LLMs for entity visibility and outputs a score range (0-100). It specifies the default model and lists use cases. No sibling tool offers the same functionality, so distinction is implicit.

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 lists use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and conditionally explains when to use the Anthropic model via API key. Does not explicitly state when not to use it, but context is clear enough for an agent.

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

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

Annotations already establish readOnly/openWorld/idempotent and non-destructive behavior. The description adds non-obvious behavioral detail: it fills arguments automatically, routes across thousands of tools, and returns structured output with stable citation URIs, which is exactly the kind of context an agent needs before calling. It does not contradict the annotations.

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

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

The description is long but organized: top directive, mechanism, trigger examples, then routing caveats. It front-loads the most actionable instruction ('PREFER OVER WEB SEARCH') and every block earns its place, though it is more verbose than strictly necessary.

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

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

For a high-complexity router with no output schema, the description covers the return format (structured answer with citation URIs), the input form, and when to skip in favor of siblings. It does not enumerate every failure mode, but nothing essential to selecting or invoking the tool 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 coverage is 100%: every parameter (question, q, text, input, query, prompt) is already documented as an alias for the natural-language question. The description adds useful examples and trigger language, but does not need to elaborate further because the schema already carries the semantic weight.

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

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

The description opens with a directive ('PREFER OVER WEB SEARCH') and names the exact job: routing a factual question to one of 5,798 tools across 1,517 verified sources and returning an answer with pipeworx:// citation URIs. This is a specific verb+resource and clearly separates it from web search and from sibling tools like deep_research and ask_pipeworx_grounded.

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

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

It gives explicit trigger phrases ('what is', 'look up', 'find', 'get the latest', 'current'), concrete examples, and says 'even if web search could also answer it'. It also states exclusions: opinions/synthesis/multi-hop → deep_research, citation-verified → ask_pipeworx_grounded, and source exploration/filtering → search_within, so an agent knows exactly when to choose alternatives.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds meaningful context beyond that: it discloses experimental candidate routing may be enabled, that no candidate is currently active as of a specific date, that results are compared against the stable router, and that it falls back to nothing because it is a full working router. This is genuine behavioral disclosure beyond annotations.

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

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

The description is compact but information-dense, front-loading the beta identity and shared interface, then explaining current state, usage guidance, and fallback behavior. Every sentence contributes value, and no irrelevant details are included.

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

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

The description covers the tool's experimental nature, current parity with the stable version, usage intent, and the absence of output schema is partially mitigated by the statement that the response shape is identical to ask_pipeworx. It could be slightly stronger by pointing to ask_pipeworx's own output docs, but it is complete enough for an agent to invoke it with appropriate care.

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 fully documents the parameters. The description adds the critical semantic context that q, text, input, query, and prompt are aliases for question, which is useful but partially redundant with the schema's alias notes. Since the schema already carries the parameter details, baseline 3 is appropriate.

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

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

The description clearly identifies this as the beta variant of ask_pipeworx with an identical universal routing interface, names the specific scope (same 5,798 tools, same arguments, same response shape), and distinguishes it from siblings like ask_pipeworx and ask_pipeworx_grounded. It explicitly explains its current state as matching the stable router when no candidate is active, which gives an agent precise expectations.

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 to use it exactly like ask_pipeworx when wanting the newest routing, and clarifies that results are compared against the stable router. It does not explicitly list when not to use it or name alternatives like ask_pipeworx_grounded, but the contextual guidance is strong enough to route correctly.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, and the description layers substantial behavior on top: the exact success envelope with verbatim evidence quote, the refusal envelope with five enumerated refusal_reason values, the strict no-invention constraint, and the extra-LLM-call cost. No contradiction with annotations — readOnlyHint matches the fetch-and-read behavior and the refusal semantics align with an open-world, non-destructive tool.

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

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

Every sentence carries unique information and the core purpose is front-loaded. The routing sentence is slightly over-specified ('5,798 across 1517 sources') and the overall length is near the upper bound for a tool description, but there is no fluff or repetition of schema 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?

With no output schema, the description fully carries return-value disclosure: both the success envelope and the refusal envelope with all refusal_reason values enumerated. For a complex routed tool, it covers selection, invocation, result interpretation, cost tradeoff, and safety profile — nothing an agent needs in order to call it 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 coverage is 100% for all 6 parameters, which are fully documented aliases of the single 'question' input. The description adds no parameter-level detail beyond establishing that the input is a natural-language question to be routed and answered, so the baseline 3 applies since the schema does the heavy lifting.

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

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

Opens with a specific verb+mode+use-case ('Hallucination-resistant answer mode for high-stakes reads') and precisely describes the pipeline: same routing as ask_pipeworx, picks a tool from a large corpus, fetches data, then extracts the answer only from the tool result. It explicitly names the sibling ask_pipeworx and differentiates itself as the grounded variant, so an agent can tell them apart without opening schemas.

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

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

Gives explicit when-to-use conditions ('whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts') with concrete domains (financial verdicts, legal claims, medical lookups, public statements), plus an explicit when-not-to with the preferred alternative ('prefer ask_pipeworx for casual lookups') including the cost reason. Nothing is left to inference.

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

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

The description goes far beyond the annotations (readOnlyHint, idempotentHint, etc.) by detailing internal behaviors: fan-out to specific data sources for each classifier, response shapes (e.g., result.market fields), resolver contract (market_match_confidence, alternatives), parent event extraction, news fallback handling, safety mechanisms for low-confidence and closed markets, spread warnings, and resolution-rule risk. 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 front-loaded with core purpose but is very long (multiple paragraphs with detailed examples and edge cases). While thorough, it could be more concise by trimming redundant examples or grouping details more efficiently.

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

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

Despite having no output schema, the description comprehensively covers input handling, internal behavior, all response fields (market, analysis, evidence, resolver, parent_event, news), edge cases (low confidence, closed markets, wide spreads), and resolution-rule risk. Everything an agent needs to use the tool effectively is present.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds value by explaining the 'market' parameter accepts multiple formats (slug, URL, question), and for 'include_raw' it advises 'recommended false' and describes when to use true. It also clarifies 'depth' enum with quick vs. thorough behavior. This adds meaningful usage context beyond the schema.

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

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

The description clearly states it 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It lists input types (slug, URL, question text) and explicitly specifies use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This distinguishes it from sibling tools like polymarket_edges or polymarket_arbitrage by covering holistic 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 provides clear context for when to use (e.g., 'should I bet on X') and includes warnings about low-confidence matches and closed markets. While it doesn't explicitly state when not to use, the context is sufficient for an agent to decide.

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

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

Annotations indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: results sorted by primary metric, returns paired data with citation URIs, explains off-calendar fiscal year handling for companies, and notes it is a single parallel call. 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 concise at ~150 words, front-loaded with trigger phrases, and every sentence adds value. No redundant or unnecessary information.

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

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

Given no output schema, the description adequately explains return format (paired data + citation URIs) and sorting. It could mention potential limits or error handling, but overall is complete for a comparison 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% (both parameters described in schema). The description adds meaningful context: clarifies values as tickers/CIKs for companies and drug names, and explains what data each type pulls. This goes beyond the enum description in the schema.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs, with specific trigger phrases ('compare X and Y', 'X vs Y', etc.) and explicitly distinguishes from sequential lookups. It specifies the data pulled for each entity type.

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 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and mentions it replaces 8-15 sequential lookups. However, it does not explicitly state when not to use the tool (e.g., for single entity queries), though this 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?

Despite strong annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false), the description adds substantial behavior: parallel decomposition across 5,798 tools, gap recovery hops, contradictions[] highlighting, citation URI fetchability guarantee, semantic excerpting of large records, and timing expectations. It also discloses that thorough requires a paid plan and that citations are only present when resolvable.

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

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

The description is dense and information-rich, but it is long and somewhat stream-of-consciousness — mixing account requirements, tool routing, mechanism, return format, and timing in a continuous paragraph. It is front-loaded with the most critical operational requirement (account) but could benefit from clearer paragraph breaks or bullet-style structure. Every sentence earns its place though.

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 research tool with 2 parameters and no output schema, this description is remarkably complete. It covers preconditions (account, paid tier), expected inputs (broad/multi-part questions), behavior (parallel routing, hop counts, gap recovery), return format (findings packet with verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[]), edge cases (unanswerable facets never invented), and performance expectations. No output schema exists, and the description compensates fully.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds meaningful semantics about depth levels ('quick=3 single hop', 'standard adds gap-recovery', 'thorough=6 paid iterative') and explains that question decomposition is the point, going beyond the schema's enum descriptions. Not a 5 because the schema already carries most parameter meaning.

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

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

The description clearly identifies the tool as grounded multi-source research over Pipeworx's 1517 structured data sources, explicitly distinguishing it from open-web search. It names the specific verb (research/decompose/route/return) and resource (structured data sources), and contrasts with sibling ask_pipeworx for when to use it.

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 this tool (broad/multi-part questions over structured data) versus when to use ask_pipeworx instead (if not signed in, or for a single lookup). Also explains depth tiers and expected latency. This is excellent routing 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 safe properties (readOnly, idempotent, non-destructive). The description adds value by explaining that results are 'ready to call directly, no second schema lookup needed' — a behavioral trait beyond annotations. It also notes the return structure (top-N most relevant tools with full schemas). 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, well-organized paragraph that front-loads the core purpose. It lists use cases compactly and ends with a strong usage directive. Slightly long but every sentence adds value; 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?

All 6 parameters are documented in the schema. The description explains what the tool returns (top-N tools with names, descriptions, and full schemas) and explicitly states the return is ready to call. With no output schema, this provides sufficient completeness for an agent to understand the tool's value.

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%, including aliases. The description reiterates aliases but doesn't add new meaning beyond the schema's property descriptions. For example, 'query' is described as 'Natural language description of what you want to do' — the schema already includes that. Thus baseline 3 is appropriate.

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

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

The description uses a specific verb ('Find') and resource ('tools'), and explicitly distinguishes itself by saying 'Call this FIRST when you have many tools available and want to see the option set.' It lists concrete data domains (SEC filings, FDA drugs, etc.) and clarifies it returns top-N tools with schemas, making it unmistakably a tool-discovery function.

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

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

The description clearly states when to use: 'when you need to browse, search, look up, or discover what tools exist' and provides example queries. While it doesn't explicitly exclude alternatives, the phrasing 'Call this FIRST' offers strong contextual guidance. A slight deduction because it doesn't enumerate specific sibling tools to avoid.

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

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

Beyond the read-only/idempotent annotations, the description reveals rich behavioral details: it fans out across eight sources, soft-fails on the USPTO patents source, reports sources_used/sources_failed, treats empty sections as real 'no data', and returns resolved:false with a notes line for private companies. This goes far beyond what annotations communicate.

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

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

The description is long but densely packed with useful information, and the core purpose plus preference rule are front-loaded. It could be trimmed slightly, but given the tool's complexity, the length is justified and every sentence adds either usage guidance or behavioral clarification.

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

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

With no output schema, the description fully documents the return shape: CIK, company_name, resolved_from/to, recent_filings with URIs, fundamentals, sources_used/failed, and LEI. It also covers input variants, private-company behavior, and failure semantics, so an agent has everything needed to invoke and interpret results correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining that 'company' and 'ticker' are interchangeable, that names resolve via SEC EDGAR company-name match, and by giving concrete examples of valid values. This is a meaningful complement to 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 states a specific action: returns a full cross-source profile of a US public company in one parallel call, with trigger-phrase examples. It clearly differentiates itself from chained single-source lookups by explicitly preferring this tool for holistic views.

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

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

It explicitly says to prefer this over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view, and includes concrete trigger phrases. However, it doesn't explicitly name sibling tools like deep_research or compare_entities or state when NOT to use it, leaving some exclusion guidance implicit.

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 destructiveHint=true, so deletion is clear. The description adds contextual use cases (stale context, clearing sensitive data) that go beyond annotations, without contradicting them.

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

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

Two sentences, no wasted words. Purpose is front-loaded, and usage guidance follows immediately.

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 1-parameter destructive tool with annotations covering safety, the description provides complete context: purpose, when to use, and related tools.

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 schema already describes the 'key' parameter as 'Memory key to delete'. The description adds minimal extra meaning beyond restating 'by key'.

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 the verb (Delete) and resource (memory by key). The pairing with 'remember and recall' distinguishes it from these sibling tools.

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

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

Explicitly states when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' Also pairs with related tools 'remember and recall'.

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 safety (readOnly, non-destructive, idempotent). Description adds process details (fetches page, extracts title/description/links, outputs markdown), enhancing transparency beyond annotations.

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

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

Description is concise at three sentences, no wasted words. Front-loaded with action, followed by output format and use cases. Efficient and well-structured.

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

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

Given no output schema, description adequately explains the output format (single text blob ready to drop). With only two simple parameters and minimal complexity, the description provides sufficient context.

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

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

Schema coverage is 100%, so baseline is 3. Description does not add further parameter meaning, but schema already provides adequate descriptions for url and max_links.

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

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

Description clearly states the tool generates an llms.txt file for any URL, specifying verb and resource. It distinguishes from siblings like ai_visibility_check by focusing on producing a specific file format for AI crawlers.

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 lists use cases (client indexing, personal drafting, competitor auditing), providing clear context for when to use. Does not mention when not to use or alternatives, but 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 cover readOnlyHint, destructiveHint, and idempotentHint. The description adds return field details (id, type, etc.), which is useful but not extensive. No pagination or ordering info, but acceptable for a simple list.

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

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

Two sentences, front-loaded with the main action, no superfluous words.

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

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

With annotations and schema covering all necessary aspects (safety, parameter, return fields), the description is complete for this simple tool.

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

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

Schema covers both the only parameter (include_inactive) with 100% coverage. The description does not add extra meaning beyond the schema, so baseline 3.

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

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

The description uses a specific verb ('List') and resource ('subscriptions'), clearly stating it returns active subscriptions. It distinguishes from sibling tools like 'subscribe' and 'unsubscribe'.

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

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

Explicitly states when to use: 'review what you're monitoring before adding more or to find an id to cancel.' No explicit 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?

Annotations are all false, leaving the description to carry the behavioral burden. It discloses rate limits, token-based retrieval of resolution status, and that reports are read by humans daily. It stops short of stating whether a persistent record is created, but the token mechanism strongly implies it. 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 the core purpose and followed by usage categories, exclusions, and mechanics. It's longer than a simple two-sentence description, but every sentence adds new information needed for correct invocation (boundaries, token flow, rate limits). The structure is logical, though slightly dense.

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

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

The description covers purpose, usage boundaries, input guidance, side effect context, and token-based follow-up, making it self-sufficient for an agent. The lack of an output schema is mitigated by describing what filing returns (a claim_token). Slight ambiguity about the exact response format prevents a 5.

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 parameters with descriptions (100% coverage), so the baseline is 3. The description adds value by explaining the claim_token lifecycle (returned when filing without an account, can be passed back later to check status) and reinforces the context object's pack/tool/vertical structure. This elevates it above the 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 function with a specific verb ('Tell the Pipeworx team something is broken, missing, or needs to exist') and immediately distinguishes it from sibling query tools by focusing on feedback. It uses concrete categories (bug, feature/data_gap, praise) that map directly to the schema's type enum.

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

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

It explicitly tells when to use (bug/data gap/praise), when not to use (different MCP server), and how to frame the report (in terms of Pipeworx tools, not end-user prompts). This is a model of usage guidance, offering both positive and negative selection 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?

Beyond annotations that already declare readOnlyHint and idempotentHint, the description adds valuable context: the data source (CF analytics-engine), privacy (no PII), and caching behavior (5min-1h). This fully informs the agent of the tool's behavior.

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

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

The description is concise (4 sentences) and well-structured: first sentence states what it returns, then bullet-style use cases, followed by technical details. Every sentence adds value with no fluff.

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

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

Given a simple tool with one parameter and no output schema, the description covers everything needed: return fields, window options, caching, and data source. It is complete for an AI 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?

The single parameter 'window' has 100% schema coverage with an enum. The description adds semantic meaning by explaining the trade-off: shorter windows for hot trends, longer windows for steady-state demand. This goes beyond the schema's enum labels.

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 what the tool returns: top tools, top packs, and total call volume over a recent window. The verb 'returns' is specific, and the resource (trending data on Pipeworx) is well-defined. It distinguishes itself from sibling tools like 'ask_pipeworx' or 'discover_tools' by focusing on usage statistics.

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

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

The description lists three explicit use cases (e.g., discovering hot data sources, confirming popular tools, aligning use case with agent needs). It does not explicitly state when not to use the tool or suggest alternatives, but the context is clear enough for an AI agent to decide.

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

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

Annotations declare readOnly=true, idempotent=true. Description adds extensive behavioral details: algorithm steps (monotonicity, partition check), semantic anchor (Jaccard similarity), partition filter (placeholder slugs), fill check (realizable vs theoretical edge). No contradictions.

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

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

Front-loaded with purpose and usage. Although lengthy, every sentence adds value for a complex tool. Could be slightly more concise but appropriate given the technical 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?

Highly complete for a complex tool with no output schema: covers all modes, parameters, algorithmic edge cases, fill check, and references sibling tool. Describes response structure. No gaps.

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

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

Schema covers 100% of parameters with descriptions. Description adds meaning beyond schema: explains how each parameter affects behavior (e.g., event walks child markets, topic searches related events), provides examples of slug format.

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

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

Description clearly states it finds arbitrage opportunities via monotonicity violations and partition-sum checks, distinguishes two modes (event, topic) and no-arg trending scan. Specific verb+resource with clear differentiation from siblings like polymarket_edges.

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

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

Explicit guidance on when to use each mode: event for specific market, topic for cross-event scan, no args for trending scan. Does not explicitly state when not to use but provides context and mentions fill risk tool for custom sizing.

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

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

The description is highly transparent, detailing the three model segments, tradeable-edge knobs, output structure with diagnostics, caching behavior (1h at KV level), and a warning about edges being priced in. Annotations already cover safety traits; the description adds significant behavioral context beyond annotations.

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

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

The description is long but well-structured, front-loaded with purpose, then breaking into segments, output fields, knobs, and response format. Every section adds value for a complex tool, though some details could be condensed. Structure earns a 4.

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 (9 parameters, no output schema), the description is comprehensive. It explains return values (e.g., edge_pp_net, kelly_fraction), diagnostics, caching, and tradeable-edge filters, covering all necessary context for an agent to invoke and interpret results correctly.

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

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

Schema coverage is 100%, so each parameter already has a description. The tool description does not add substantial new semantic detail for parameters beyond what the schema provides, though it reiterates the purpose of key knobs in context. 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 the tool scans Polymarket markets for opportunities where Pipeworx data disagrees, with a specific verb and resource. It positions the tool for 'what should I bet on today' but does not explicitly differentiate from sibling tools like polymarket_arbitrage or polymarket_edge_tracker, limiting sibling distinction.

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

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

The description implies usage for discovering opportunities without paging hundreds of markets, but does not provide explicit guidance on when not to use this tool or direct comparisons to alternatives. Usage context is implied rather than explicit.

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

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

Annotations indicate read-only, open-world, idempotent, and non-destructive. The description adds substantial behavioral detail: response structure (tracked, expired, snapshot_dates), decay computation method, sign convention, snapshot gaps, and TTL limits. 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 moderately long but efficiently packed with essential details. It is front-loaded with the core purpose and then provides structured response fields and limitations. Could be slightly more concise, but no sentences are 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?

Given no output schema, the description thoroughly explains the return structure with three arrays (tracked, expired, snapshot_dates) and their contents. It also covers data limitations (TTL, gaps). The tool's purpose is fully covered.

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

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

Schema coverage is 100% for both parameters. The description adds value by explaining defaults and clamps for 'days' and the meaning of 'window' as 'snapshot family' with examples. This enhances understanding 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 defines the tool as providing 'edge persistence and decay telemetry' from daily snapshots. It answers specific questions about edge longevity and shrinkage, and the contrast with a raw edge tool (sibling polymarket_edges) is implicit but effective.

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

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

The description explains when to use the tool (to assess edge persistence and decay) and provides an example scenario (fresh wide edge vs. old wide edge). It does not explicitly list alternatives or when not to use, but the context is clear.

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

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

Disclosures go well beyond annotations. Explains internal mechanism: 'walks the ladder', 'returns top_of_book, vwap_fill_price, slippage_pp...' and the verdict system. Warns that 'partial basket fills convert an arb into an unhedged directional position'—a key risk. Consistent with readOnlyHint and non-destructive annotations.

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

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

Description is well-structured with sections (REQUIRES, SINGLE-MARKET, BASKET, USE THIS). Front-loaded with core purpose. While lengthy, every sentence is informative. Minor redundancy could be trimmed, but highly organized.

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

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

Given no output schema, description exhaustively lists return fields for both modes (e.g., theoretical_sum, realizable_sum, capture_ratio, profit_usd, thin_legs, forced_directional_risk). Addresses parameter combinations, defaults, and edge-case risk. Highly complete.

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

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

Schema covers 100% of parameters with descriptions. Description adds value by explaining nuanced differences: size_usd interpretation as 'settlement notional S' for basket mode, side defaults, and mode-specific behavior. Justifies 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?

Description explicitly states it is a 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes single-market from basket modes and specifies return values. It differentiates from siblings by stating 'USE THIS before acting on any polymarket_arbitrage...' making the purpose highly specific.

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: before acting on arb signals or trades above ~$500. Explains consequences of partial fills converting arb to directional risk. Details mode selection based on input parameters (market or event). Offers clear prerequisites and behavior for each mode.

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

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

Beyond the read-only and idempotent annotations, the description discloses many non-obvious behaviors: the fee model (Kalshi fees not modeled, spread is gross), the meaning of null in temporal_alignment, the fact that compatibility fields can be non-empty even when pairs are returned, and that unknown metric types are never paired. It also cautions that returned pairs are keyword-matched, not verified by a shared resolution source.

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

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

The description is long and dense, but it is structurally organized: core definition, modes, response, safety fields, codes, fee note, counters, and a closing caution. Every sentence contributes meaningful information, though the lack of clear section breaks makes it a heavy wall of text.

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

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

For a complex cross-venue matching tool with no output schema, the description thoroughly enumerates the response structure, safety codes, flags, fee caveat, and comparison behavior (including skipped leg types and how unknown legs are handled). An agent has nearly everything needed to invoke the tool and interpret its results correctly.

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

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

The schema already has 100% parameter coverage with descriptions and examples, so the baseline is 3. The description adds mode-level semantics: `topic` auto-fetches the matching event on each venue, while `kalshi_event_ticker` and `polymarket_event_slug` are explicit overrides meant to be used together for custom pairings. This contextualizes the parameters 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 leads with a specific verb and resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It then details the two modes, response contents, and safety fields, making it distinct from siblings like polymarket_arbitrage and polymarket_edges, which focus on other trading concepts.

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

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

The description clearly explains when to use each mode: the `topic` mode for pre-mapped shortcuts and the explicit mode for custom pairings, with both running the same matcher. It also warns that 'pre-mapped ≠ tradeable' and that most topics currently return compatibility warnings. However, it does not explicitly contrast this tool with sibling tools like polymarket_arbitrage or polymarket_edges.

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 read-only and idempotent, and the description adds meaningfully beyond that: it warns that tender_value is the ORIGINAL ASKING PRICE, not money spent, and that cancelled or unsuccessful tenders still contain a populated tender_value. It also clarifies the OCDS award/contract interpretation and that text is largely Ukrainian, which materially affects how the agent reads results.

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 every section carries useful semantics: return fields, the asking-price caveat, award/contract interpretation, language note, and source of the input id. It is front-loaded with the core purpose, and the detail is justified by the lack of an output schema, though a few commas and clauses make it slightly harder to parse than needed.

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 there is no output schema, the description carries the full burden of explaining the return shape, and it does so thoroughly: tender metadata, buyer info, periods, line items, award/contract stages, and the critical monetary interpretation. It also names the sibling tools that supply the required id and notes the language of the returned text, covering everything needed to invoke it correctly.

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

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

The schema already documents the single id parameter at 100% coverage, so the baseline is 3. The description adds value by restating the 32-char format and explicitly warning it is not the human-visible tenderID like 'UA-2026-...', reducing the risk of passing the wrong identifier.

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

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

The description opens with a specific verb-resource pair: 'Full detail for a single Ukraine ProZorro tender by id.' It enumerates the exact returned fields and distinguishes it from sibling tools by noting it consumes ids from prozorro_recent_tenders / prozorro_search_tenders, so an agent can identify what this tool is for.

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

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

It explicitly states the tool accepts the 32-char tender id from prozorro_recent_tenders / prozorro_search_tenders, indicating when it should be selected: after a list/search has produced a tender id. It does not literally say 'use x for listing, use this for details,' but the routing is clear enough from the context.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds behavioral context: data source (OpenProcurement public feed), language (Ukrainian titles), and returned fields. No contradictions. Slightly less than 5 because it doesn't mention pagination or rate limits, but annotations cover safety.

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 wasted words. First sentence states main function, second lists returned data, third gives usage advice. Front-loaded and efficient.

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

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

For a simple list tool with one optional parameter, clear annotations, and no output schema, the description fully covers what the agent needs: purpose, data format, language, and when to use it. No gaps.

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

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

Only one parameter 'limit' with 100% schema coverage (type, default, range). Description does not add new meaning beyond schema, which already fully documents the parameter. Baseline 3 is appropriate.

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

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

The description clearly states the tool returns 'most recently updated tenders' from Ukraine's ProZorro system, listing specific fields returned (id, tenderID, title, etc.). It distinguishes itself from sibling tool 'prozorro_get_tender' by specifying scope (browsing recent tenders vs. specific tender).

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

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

Explicitly states 'Use for browsing current Ukrainian public tenders; for a specific tender use prozorro_get_tender.' This provides clear when-to-use and when-not-to-use guidance with an alternative named.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive behavior. The description adds useful context beyond annotations: the lookup is 'keyless' (no auth needed), uses ProZorro's organization index, and returns an edrpou value for downstream use.

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 with no filler: the first states the tool's core purpose, and the second provides the critical workflow. The most important distinction is front-loaded, and every clause earns its place.

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

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

For a simple 2-parameter tool with strong annotations and no output schema, the description is complete: it explains the lookup, the keyless access, the relevant sibling tool, and what to do with the result. No critical information for calling it 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%, so both parameters are already documented in the input schema. The description reinforces the meaning of role by relating it to the next tool's tenderer/buyer parameters, but it does not add substantial new syntax or format details 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?

States a specific verb and resource: 'Resolve a Ukrainian company or public buyer NAME to its EDRPOU code.' It also distinguishes itself from prozorro_search_tenders by noting that tool filters by EDRPOU while this one resolves names.

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 it: 'This is the entry point for supplier due diligence.' It also names the alternative (prozorro_search_tenders) and gives the exact call sequence: call this first, then pass the returned edrpou as tenderer or buyer.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context beyond that: it explains that the search uses ProZorro's own analyzed index with stemming, mentions the date-filtering caveat that 'DROPS records that have no tender period,' and discloses fixed 20-results-per-page pagination. It also notes that Ukrainian queries stem correctly, which is a behavioral nuance. 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 concise relative to the tool's complexity. It front-loads the core purpose and then methodically lists filters and return fields. Every sentence provides distinct information: scope, stemming behavior, filter options, return fields, and a pointer to the sibling. No filler, but it is fairly long; considering the 10 parameters and the need to explain caveats, the length is justified. It earns a 4 because it is efficiently structured, though slightly dense.

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

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

The tool is complex with 10 optional parameters and no output schema, so the description must carry the burden of explaining what to expect. It covers the return fields (tenderID, title, value, buyer name + EDRPOU + region, status, total match count), the keyless nature, pagination (fixed 20 per page, page 1-500), and critical caveats (date filtering dropping records). It also routes to the sibling for full detail. Combined with the rich annotations, the description is complete for an agent to invoke the tool correctly without additional clarification.

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 every parameter is already documented. The description adds extra meaning: it highlights that the 'tenderer' parameter is the primary supplier due-diligence filter, clarifies that 'query' is optional when a filter is provided, and explains the date filtering caveat. This goes beyond the schema's basic descriptions, adding nuance that helps the agent select parameters correctly. Not a 5 because the schema already covers basic semantics, but the added context is valuable.

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

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

The description opens with a precise statement: 'Full-text search over ALL Ukraine ProZorro tenders back to 2015 (keyless).' It names the specific verb (search), the resource (ALL ProZorro tenders), and the scope (back to 2015). It also distinguishes itself from the sibling prozorro_get_tender by explicitly stating that the sibling should be used for full detail, making the purpose unambiguous.

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

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

The description gives clear context on when to use the tool (full-text search, filtering by various criteria) and explicitly redirects to a sibling: 'Use prozorro_get_tender for the full detail of one result.' It also emphasizes the tenderer filter for supplier due diligence, guiding the agent on when to choose this search over others. While it doesn't list exhaustive 'when-not' conditions, the explicit alternative and the context of its keyless search versus the sibling's detail retrieval sufficiently guide usage.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. Description adds scoping to identifier and the behavior of listing when key is omitted. No contradictions.

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

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

Three sentences, front-loaded with purpose, no redundant information.

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

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

Given lack of output schema, the description is sufficient: covers purpose, usage, scoping, and relationship to sibling tools. Complete for a simple retrieval tool.

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

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

Schema covers the key parameter 100%. Description adds crucial semantics: omitting key lists all, which goes beyond schema 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?

Clearly states verb 'retrieve' and resource 'value saved via remember', and distinguishes between retrieving a specific key and listing all keys. No ambiguity.

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 (look up stored context) and when not (omit key to list). Also pairs with sibling tools remember and forget, guiding the agent on alternatives.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive. The description adds behavioral details: events carry source, citation_uri, and raw payload; mark_read:true flags events as read to affect subsequent calls. This enriches understanding beyond annotations.

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

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

Four sentences: purpose, content of events, filtering and mark_read behavior, polling and alternative access. No filler, front-loaded with key info, each 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?

No output schema, but description details return fields (source, citation_uri, payload). It covers filtering, mark_read, polling, and alternative HTTP endpoint. For a read-only retrieval tool, this provides comprehensive context for correct usage.

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

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

Schema coverage is 100% so baseline is 3. The description adds an example filter type ('sec_8k'), explains the effect of mark_read:true, and clarifies limit range (1-200, default 50). This provides useful context beyond bare parameter names.

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

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

The description starts with 'Pull fired events from your subscription feed,' providing a specific verb (Pull) and resource (fired events from subscription). It differentiates from siblings like list_subscriptions and recent_changes by focusing on alert events and offering filtering by type and since.

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 notes that polls work fine and mentions the same feed is available via HTTP for scripts and dashboards, giving alternatives. It implicitly suggests using this tool for programmatic access with features like mark_read, 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?

Beyond annotations (readOnlyHint, etc.), the description details multi-source parallel fan-out, fallback logic, parameter formatting, and return structure. It also notes soft-fail for USPTO due to API sunset, which is critical behavioral context not covered by annotations.

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

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

The description is front-loaded with natural language queries, followed by concise, structured details. Every sentence serves a purpose: defining scope, listing sources, explaining parameters, and contrasting with sibling. No filler or repetition.

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

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

Given the tool's complexity (multiple sources, fallback, parameter options) and no output schema, the description covers most aspects well. It explains return structure and fallback behavior. However, it could briefly mention error handling or response shape beyond what is stated, leaving 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 100% schema coverage, the schema already describes parameters well. The description adds value by explaining the `since` parameter formats with concrete examples and typical usage ('Use "30d" or "1m" for typical monitoring'). This enriches understanding 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 explicitly states the tool provides a 'change feed for a company in the last N days/weeks/months in ONE parallel call' and lists specific data sources. It distinguishes itself from the sibling tool `entity_profile` by contrasting dynamic vs static profile retrieval.

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

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

The description gives clear example queries and explicitly recommends using `entity_profile` for static profiles. It also explains the fallback behavior between GDELT and GNews under rate-limiting or errors, providing practical guidance for when to use this tool.

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

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

Adds behavioral details beyond annotations: scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous sessions. Does not contradict annotations.

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

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

Concise 4 sentences, front-loaded purpose and usage, no unnecessary words.

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

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

Covers storage, scope, persistence, and companion tools. No output schema needed; minor gap: behavior on duplicate key not explicitly stated but hinted by idempotent annotation.

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 description echoes schema examples but does not add significant new meaning beyond it; baseline 3 is appropriate.

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

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

The description clearly states the tool saves data for reuse, specifies key-value pair storage, and distinguishes from sibling tools 'recall' and 'forget' by mentioning them.

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

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

Provides explicit guidance on when to use (discover something worth carrying forward) and pairs with recall/forget, but lacks explicit when-not scenarios.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses important behaviors: identifier resolution across multiple upstream sources, graceful degradation if GLEIF/OpenFIGI are unavailable, explicit `unresolved` fields, and a `figi_candidates` mechanism for ambiguous matches. This is substantial context that the annotations alone do not provide.

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

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

The description is front-loaded with examples and the 'Use FIRST' directive, but it is a single dense paragraph with deeply nested parentheticals and long asides. The complexity of the tool justifies length, but the lack of paragraph or bullet structure makes it harder for an agent to quickly extract the critical guidance.

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

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

Despite having no output schema, the description explains expected return elements (`figi_candidates`, `unresolved`, source-labelled identifiers, RxNorm citation). It also covers supported input formats, entity types, ambiguity behavior, and fallback behavior across upstream APIs. An agent has enough information to call and interpret the tool correctly in 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?

The input schema already covers the parameters at 100%, so the baseline is 3. The description adds genuine semantic value by explaining that ISIN inputs resolve to the issuing legal entity via GLEIF, that non-equity instruments without tickers still resolve, and that exact-ticker mapping differs from name search. These nuances go beyond the schema's parameter 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 names a specific verb and resource: it resolves user-spoken names to canonical/official identifiers, and enumerates the exact identifiers produced (CIK, ticker, LEI, FIGI, RxCUI). It also differentiates itself from siblings by stating it supplies IDs that 'other tools require as input' and instructs the agent to 'Use FIRST' when a name but not an ID is available.

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 context for when to use this tool: 'Use FIRST whenever you have a name but need an ID.' It also clarifies supported types (company and drug) and handles ambiguity correctly. However, it does not name concrete alternative tools or state when NOT to use it, 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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false. The description adds value by explaining the internal process: 'Probes each entity with ai_visibility_check, ranks by score, surfaces which is most/least recognized.' It also describes the output structure. This is consistent with annotations and provides sufficient behavioral context beyond what annotations offer.

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

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

The description is four sentences, each earning its place: purpose, mechanism, use-case, output. It is front-loaded with the main action and avoids unnecessary details. 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 tool's complexity (multiple entities, optional models, API keys, and context), the description covers how it works (calling ai_visibility_check), what it returns (ranked list with score, confidence, signal density), and when to use it. Combined with rich annotations (readOnly, idempotent) and full schema coverage, the description leaves no significant gaps for an AI agent.

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

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

Schema description coverage is 100%, so the input schema already explains all parameters. The description adds context such as the first entity being the 'subject' for narrative, but this is also present in the schema description. The example usage is helpful but does not significantly enhance understanding beyond the schema. Thus, a 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 the tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It specifies the verb (compare), the resource (AI visibility of entities), and distinguishes itself from siblings like ai_visibility_check (single entity) by emphasizing multiple entities. The use-case example 'does Claude know about us as well as our competitors?' further clarifies its role in competitive audits.

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: it is for comparing multiple entities in competitive AI-marketing audits. It implies that ai_visibility_check would be used for single-entity checks, and the phrase 'Compare... multiple entities side-by-side' indicates when to use this tool. However, it does not explicitly state when not to use it or mention alternative tools like compare_entities, which is a minor gap.

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

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

Description adds significant behavioral context beyond annotations: fans out to deps.dev and bundlephobia, first-measurement delay, graceful degradation, and return content. 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?

Single dense paragraph that front-loads purpose and is clear, though could be slightly more structured. Every sentence adds value.

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

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

Given complexity (composite call, multiple sources, timing, partial failures) the description is thorough, covering return content, limitations, and behavior. No output schema, so the description compensates well.

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

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

Schema covers 100% of parameters. Description adds minor extra info about scoped packages and default version, but not extensive. Baseline 3 is appropriate.

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

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

The description clearly states it's a composite check for npm package assessment, combining multiple data sources. It distinguishes from sibling tools by being specific to npm.

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 (agent asks about safety/popularity/size of npm packages) and when not (other ecosystems fall under deps.dev directly). Also mentions partial failures and timing.

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

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

Annotations indicate a safe, idempotent read operation. The description adds critical behavioral details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncated flagging. This goes well beyond the annotations, fully disclosing how the tool works.

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 is purposeful: core function, usage scenario, pairing advice, technical details. No redundant or vague statements. The description is front-loaded with the main purpose, then adds necessary depth.

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

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

Despite no output schema, the description explains return values (passages with character offsets and similarity scores) and handling of large inputs (truncation flagging). Parameters are fully documented. Sibling tools are many, but the description clearly distinguishes this tool's niche.

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 usage patterns ('pass the text you already pulled'), providing example queries, and clarifying that limit controls top-N passages. It doesn't restate schema details but enhances understanding.

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

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

The description clearly defines the tool's function: semantic search inside a fetched record. It uses specific verbs (search, fetch, return) and resources (passages with offsets and scores). It differentiates from siblings by emphasizing its role for large records and pairing with ask_pipeworx_grounded.

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

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

Explicitly states when to use ('when the record is too big to cram into the prompt') and how to pair with ask_pipeworx_grounded. While it doesn't list when not to use, the context and alternative tool reference provide sufficient guidance.

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

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

The description adds significant behavioral context beyond annotations, such as the requirement for a Pipeworx OAuth account, delivery channel constraints (SMS cap, webhook auto-disable after 10 failures), and that the subscription is persistent. No contradictions with annotations.

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

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

The description is well-structured with a front-loaded purpose statement, followed by requirements, types, and delivery details. It is long but every sentence adds value for a complex tool; slight improvement possible by more concise examples.

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

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

Given the tool's complexity (multiple types, delivery channels, constraints, and error conditions), the description covers all necessary aspects: purpose, requirements, parameter details, behavioral notes, and return value. No output schema exists, but the description mentions the return of a subscription id, which 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?

Despite 100% schema coverage, the description enriches parameter understanding with concrete examples for each subscription type (e.g., sec_8k items codes), detailed delivery channel behaviors (email validation, SMS verification, webhook HMAC signing), and required/optional fields, surpassing schema definitions.

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

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

The description clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It specifies the action (create), resource (subscription), and differentiates from sibling tools like list_subscriptions and unsubscribe.

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

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

The description provides clear context on when to use the tool (creating subscriptions) and includes requirements (Pipeworx OAuth account) and constraints (delivery caps, phone verification). However, it does not explicitly mention alternatives like list_subscriptions or unsubscribe, though this is implied by the sibling list.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds valuable context: it returns question examples with exact tool+argument shapes from a live catalog of thousands of tools, and explains the tool's role in onboarding. 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 fairly long but well-structured, with a front-loaded list of example queries and clear sections. Every sentence serves a purpose, though it could be slightly more concise without losing clarity.

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

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

Given the simple tool (1 optional param, no output schema, rich annotations), the description fully covers all aspects: purpose, usage, parameter behavior, and when to use it. No gaps detected.

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 good description for the optional 'topic' parameter. The description goes further by listing example topics (finance, pharma, betting) and explaining the effect of omitting vs. providing a topic. This adds semantic value beyond the schema.

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

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

The description clearly identifies the tool as an onboarding entry point that returns category-bucketed example questions. It lists multiple user intents and distinguishes itself from sibling tools like ask_pipeworx by focusing on suggestions rather than direct answering.

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 'Use this FIRST when you do not yet know what Pipeworx can do for you' and provides guidance on calling with no arguments for full spread or passing a topic for focus. This is excellent usage direction.

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

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

Adds value beyond annotations: describes deactivation vs deletion, ownership enforcement, and availability of historical events. Annotations indicate mutation but not destructive; description confirms. No contradiction.

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

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

Three concise sentences, front-loaded with action, then constraints, then side effects. No redundant information.

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

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

Adequate for a simple mutation with one parameter. Covers behavior, ownership, and effect on history. Could mention return value, but details are sufficient for agent invocation.

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

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

Schema covers 100% of parameter details. Description adds minimal extra meaning (ownership context), but baseline 3 is appropriate since schema already explains the 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?

Clear verb ('cancel') and resource ('subscription'), with specific scope ('by id'). Distinguishes from siblings like subscribe and list_subscriptions by stating ownership and deactivation behavior.

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

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

Explicitly states ownership enforcement ('you can only cancel your own subscriptions'), which defines when to use. Does not list alternatives but context from siblings 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 substantial behavioral context beyond the annotations: it explains the two processing paths, defines each verdict type, and crucially clarifies that 'could_not_verify' means the check did not happen and is not evidence for or against the claim. It also describes the return format with citations. 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 longer than two sentences but every sentence carries information: usage intent, routing rules, return values, and special caveats. It is front-loaded with examples and a clear verb, and the structure is logical. Slightly verbose but not wasteful.

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

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

The tool is complex with two processing paths and multiple verdict states, and the description covers all of it, including error semantics and a note about replacing sequential calls. Without an output schema, it fully compensates by describing return values, verdicts, and citations. No gaps for an agent to misuse the tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra meaning for tolerance_pct by explaining its role in hallucination detection (set 1–2) and the default cap of 5, which is not in the schema. Claim parameter is already well-described in the schema with examples.

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 with specific verbs and resources: 'natural-language claim verification against authoritative sources', with examples of user intents. It distinguishes between company-financial claims (SEC EDGAR fast path) and any other factual claim (grounded pipeline), which sets it apart from sibling tools like deep_research or ask_pipeworx_grounded.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and details how different claim types are routed. It does not name alternative tools or exclusion cases, but the context is clear and actionable for an agent deciding between this and similar research tools.

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