Openreview

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

Annotations already indicate read-only and idempotent. Description adds value by detailing the probing process, scoring mechanism, and API key handling, which goes 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 with no redundancy. Front-loaded with primary action and output. 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?

Even without an output schema, the description specifies return structure (per-model score, confidence, signals, raw_response + combined view). Sufficient for a read-only probe tool with moderate complexity.

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

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

Adds substantial meaning beyond schema: explains default model, free usage of workers-ai, optional Anthropic key with pass-through, and context for disambiguation. Schema coverage is 100% but description 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?

Description clearly states the tool probes LLMs for awareness of a business/product and scores visibility. It distinguishes itself from siblings by being a visibility-specific tool, not a general Q&A or entity profile tool.

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

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

Provides clear use cases (AI-marketing audits, brand checks) and explains when to use the _apiKey for Anthropic. Lacks explicit 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?

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description adds substantial context: it routes to 5,529 tools across 1,455 sources, fills arguments automatically, returns citations via URI, works on every tier, is a fast default entry point. This enriches the behavioral profile well beyond what annotations capture.

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 efficiently packed: it covers use cases, examples, alternatives, and behavioral notes in one cohesive block. Every sentence adds value, though it could arguably be trimmed; the length is justified for the tool's complexity.

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

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

Given the tool's complexity, the description covers all essential aspects: when to use, examples, return type (structured answer with citations), relationship to alternatives, and scope of sources. No gaps are apparent even without an output schema.

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

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

Schema coverage is 100% and all six parameters are aliases for a single question field. The description adds no additional parameter semantics beyond what the schema already states, so baseline 3 is appropriate.

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

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

The description clearly states the tool's function: a meta-query tool that routes questions to thousands of sources and returns structured answers with citations. It explicitly distinguishes from siblings like ask_pipeworx_grounded and deep_research, making its unique role 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?

Extremely explicit guidance: it tells agents to prefer this over web search, provides concrete phrasing triggers ('what is', 'look up', etc.), gives examples, and names alternative tools with specific when-to-use criteria ('step up only when needed'). This is model-tier usage guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds significant context: it is beta, currently no candidate is active (matches ask_pipeworx exactly), and it is a full working router. This goes beyond the annotations and helps the agent understand the experimental nature and current equivalence to the stable version.

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

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

The description is information-dense but each sentence earns its place: it states beta identity, equivalence to ask_pipeworx, current state, usage, and experimental purpose. It is front-loaded and not overly verbose, maintaining clarity without redundancy.

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

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

Given the tool's complexity (a universal router with thousands of tools), the description is complete: it explains the beta context, current behavior, relationship to the stable sibling, and confirms full functionality. No output schema exists, but saying 'same response shape' adequately covers return expectations.

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 covers 100% of parameters with clear descriptions, including aliases for 'question'. The description mentions 'same arguments' as ask_pipeworx but adds no new parameter semantics beyond what the schema already provides. Baseline 3 is appropriate because 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?

The description clearly states this is the beta version of ask_pipeworx, an identical universal router with the same 5,529 tools and response shape. It distinguishes itself from the stable ask_pipeworx by being the experimental edge for candidate routing improvements. The verb 'ask' is implied through the tool name, and the purpose is 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?

It explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and notes that results are compared against the stable router. This provides clear when-to-use guidance and implies the alternative (stable ask_pipeworx). It also clarifies that it is a full working router, not a partial fallback.

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

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

Beyond the annotations (readOnly, idempotent), the description discloses the refusal behavior with specific refusal_reason values, the return structure including evidence and confidence, the grounding mechanism, and the extra LLM call cost. This adds significant behavioral context not present in 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 dense yet logically organized: it opens with the defining purpose, then explains process, return/refusal shapes, and ends with usage guidance and cost trade-off. Every sentence adds value without redundancy.

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

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

For a tool with no output schema, the description thoroughly documents success and refusal formats, lists specific refusal reasons, and covers use cases and cost implications. It is complete enough for an agent to understand both behavior and when to invoke it.

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

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

Schema coverage is 100% and all aliases are documented in the input schema, so the description doesn't need to repeat parameter meaning. It adds some context about the type of question (high-stakes reads) but doesn't alter or enrich the parameter semantics beyond the schema's 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 uses a specific verb ('extracts the answer') and resource ('using ONLY what the tool result contains') and immediately distinguishes it from the sibling ask_pipeworx by calling it 'hallucination-resistant answer mode for high-stakes reads.' This clearly states what the tool does and why it differs from alternatives.

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 when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and when not to: 'prefer ask_pipeworx for casual lookups,' naming the alternative tool directly. This gives clear decision-making 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 indicate read-only, idempotent, non-destructive behavior. The description goes far beyond, detailing status codes, cancellation rules, spread warnings, news fallback mechanisms, and resolver contract behavior—all adding transparency.

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

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

Long but well-structured with clear sections (CLASSIFIERS, FAN-OUT EXAMPLES, etc.). Front-loads core purpose and usage. Every sentence adds information; length is justified by tool complexity.

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

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

Extremely thorough: covers input formats, classification, fan-out examples, response shapes, resolver contract, parent events, news fields, safety, spread warnings, cancellation rules. No output schema needed given comprehensive description.

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

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

Schema covers 100% of parameters, baseline 3. Description adds value by explaining accepted formats for 'market' (slug, URL, question text), effect of 'depth' (quick vs thorough), and 'include_raw' (response size impact).

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

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

The description clearly states it researches Polymarket bets by pulling Pipeworx data, with specific verbs and resources. It distinguishes from sibling tools like polymarket_edges by focusing on evidence gathering rather than edge calculation.

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 use cases ('should I bet on X', 'what does the data say about Y') and mentions safety checks (low-confidence short-circuit, closed market handling). However, lacks explicit when-not-to-use or alternative tool references.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context beyond annotations: it explains how off-calendar fiscal years are handled for companies, that results are sorted by primary metric, and that the tool returns paired data with citation URIs. This provides additional behavioral insight the agent needs.

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

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

The description is a single paragraph that efficiently front-loads example usage patterns, then explains the tool's behavior. It is dense but every sentence adds value. It could be slightly more concise, but the information density is appropriate for the tool's complexity.

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

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

Given the context (2 parameters, 100% schema coverage, no output schema, good annotations), the description is complete enough. It explains the purpose, input types and constraints, and behavioral aspects like sorting and data sources. The lack of return schema description is acceptable as it's not provided. The description covers all necessary aspects for an agent to select and invoke the tool correctly.

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

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

The input schema has 100% coverage with descriptions for both parameters. The description adds value by explaining the meaning of the enum values (company vs drug) with concrete examples of what data each pulls (10-K financials for company, FAERS data for drug) and provides usage examples for the values parameter (tickers for company, names for drug). 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 uses specific verbs like 'compare', 'rank', and 'head to head' to clearly define the tool's function. It distinguishes itself from siblings by explicitly stating it replaces 8-15 sequential lookups and should be preferred over single-pack lookups when comparing entities. The tool is positioned as the go-to for side-by-side comparisons of 2-5 companies or drugs.

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

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

The description provides explicit usage context with example intents ('compare X and Y', 'which is bigger'), and strongly advises preferring this tool over sequential lookups. It also explains the behavior for different entity types. However, it does not explicitly state when not to use the tool (e.g., for single entities or more than 5), but the constraints are implied by the schema.

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), the description adds extensive behavioral context: account/paid-tier requirements, internal parallel decomposition across 5,529 tools, output packet contents (verbatim evidence, confidence, source, fetched_at, pipeworx:// citations), gaps[] never inventing answers, contradictions[] for standard/thorough, citation_uri resolvability guarantees, semantic excerpting of large records, and expected latency ranges. 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?

Though long, the description is dense with operational value and has zero filler. It front-loads the account requirement, then the core capability, followed by alternatives, internal mechanics, depth modes, citation guarantees, and latency. Every sentence earns its place, and the semicolon/parenthetical structure keeps related concepts grouped without unnecessary verbosity.

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 compensates by enumerating the findings packet fields (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), gaps[], contradictions[], hop field, and citation_uri semantics. It also covers account prerequisites, alternatives, internal mechanism, and timing. For a complex tool with two params and no output schema, this description is exceptionally complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaningful param-level context beyond the schema: the question parameter is clarified as 'Broad/multi-part is fine — decomposition is the point', and depth:'thorough' is tied to the paid plan. These are useful operational details that help an agent select appropriate values, but the core depth semantics are already 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 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' in one call, and explicitly differentiates it from siblings: 'this is NOT open-web search' and contrasts with ask_pipeworx. The scope, verb, and resource are all specific and 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?

Provides explicit when-to-use guidance ('Best for broad/multi-part questions over structured data'), when-not-to-use ('For a single lookup use ask_pipeworx'; 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'), and a fallback alternative if not signed in ('If you are not signed in, use ask_pipeworx instead'). This is textbook alternative differentiation.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds that results are 'ready to call directly, no second schema lookup needed' and returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)', which provides behavioral detail 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 front-loaded with purpose and usage, followed by examples and return details. While slightly long, every sentence adds value and it is well-structured.

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

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

Despite no output schema, the description fully explains what is returned (top-N tools with schemas and examples) and when to use it (first, for exploration). It is complete for this tool's purpose.

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

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

Schema description coverage is 100%, so baseline is 3. The description provides example queries and mentions aliases, adding marginal value beyond the schema descriptions.

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

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

The description clearly states 'Find tools by describing the data or task', indicating a specific verb and resource. It distinguishes itself from sibling tools by positioning itself as the first call for exploring available tools, unlike the specialized siblings.

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

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

The description explicitly says 'Call this FIRST when you have many tools available', providing clear usage context. It lacks explicit when-not guidance, but the context strongly implies appropriate use.

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

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

Annotations already declare readOnly, idempotent, not destructive. Description adds context: fans out across multiple sources, returns specific fields, patents soft-fails, news via fallback. Adds value beyond annotations without contradiction.

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

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

Description is thorough but not overly verbose. Structured with examples, then functionality, then details. Could be slightly more concise, but all sentences earn their 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, so description must explain return values. It lists fields (cik, company_name, recent_filings, fundamentals, patents, news, LEI) and notes limitations like patents sunset. Complete for a multi-source profile 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%, but description adds meaning: explains value can be ticker or CIK, names not supported. Also notes type currently limited to 'company'. Adds context beyond schema.

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

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

The description clearly states the tool's purpose: 'full cross-source profile of a US public company' with specific examples like 'Tell me about X'. It distinguishes from siblings by preferring over chaining single-pack lookups and referencing resolve_entity for name resolution.

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

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

Explicit guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also notes limitation: 'names not supported (use resolve_entity first if you only have a name)' and mentions patents sunset.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds no new behavioral traits beyond stating deletion, which is consistent. It mentions 'clear sensitive data' as a use case but no additional details like permissions or irreversible effects.

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: purpose, when to use, and pairing suggestion. No fluff or redundancy. Every sentence adds value.

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

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

For a simple tool with one parameter and no output schema, the description is complete. It covers purpose, usage context, and sibling relationships, and annotations cover safety properties.

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 single 'key' parameter described as 'Memory key to delete'. The description's 'by key' adds no new meaning beyond what the schema provides, so the 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 deletes a previously stored memory by key, distinguishing it from siblings 'remember' (store) and 'recall' (retrieve). The verb 'delete' and resource 'memory by key' are 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?

The description explicitly tells when to use the tool: when context is stale, the task is done, or to clear sensitive data, providing clear context. It also recommends pairing with 'remember' and 'recall', guiding the agent on appropriate usage relative to siblings.

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

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

Description discloses fetch behavior, extraction (title/description/key links), output format (standard markdown), and deployment location (site-root/llms.txt). This adds detail beyond the readOnlyHint and idempotentHint annotations, fully describing the tool's safe, non-destructive operation.

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

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

Two concise sentences plus a bulleted list of uses. Every sentence adds value, no redundancy, front-loaded with the core action.

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

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

Given the simple input (2 params, no output schema) and informative annotations, the description covers purpose, usage, behavior, and parameter meaning thoroughly. No gaps remain.

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

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

Schema coverage is 100% with clear descriptions for url and max_links. The description echoes these without adding new constraints or examples, warranting the baseline score.

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 ('generate'), identifies the exact resource ('llms.txt file'), and clarifies the target (any URL for AI crawlers). It distinguishes well from sibling tools, none of which produce llms.txt.

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 three use cases (client site indexing, own project drafting, competitor auditing), providing clear context. Lacks explicit when-not-to-use or alternatives, but no sibling overlaps, so it's 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?

Description adds minimal behavioral context beyond the annotations (readOnlyHint, idempotentHint). It correctly implies a read operation but does not disclose return format or pagination.

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

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

Single sentence, front-loaded with key information. No wasted words, though could be slightly more descriptive without becoming verbose.

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

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

Given the output schema exists, the simple parameter set (2 params,1 required), and clear annotations, the description is complete enough for basic usage. No notable gaps.

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

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

Schema coverage is 100% and the description does not add new information about parameters. The schema already documents id and details sufficiently, so baseline 3 is appropriate.

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

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

Description clearly states 'Single note — paper, review, comment, decision, etc.' which specifies the resource (note) and its scope (various types). It distinguishes from sibling tools like search_notes and list_submissions.

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

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

Implied usage: use this tool to get a single note by ID. No explicit when-to-use or alternatives provided, but the purpose is straightforward given the tool name and input schema.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, indicating a safe read operation. The description adds valuable behavioral context by listing the exact child notes returned (reviews, rebuttal, decision, metareview), which is 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 extremely concise with two sentences. It front-loads the purpose and immediately follows with the essential parameter instruction. No redundant or unnecessary content.

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

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

Given the output schema exists, the description does not need to detail return values. It covers the tool's purpose, parameter, and behavioral traits sufficiently. For a simple retrieval tool with complete annotations and schema, this is fully adequate.

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

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

Schema coverage is 100% and the description restates that forum_id is the paper note id. The description adds minimal new meaning beyond the schema description, so 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 retrieves a paper and all its child notes (reviews, rebuttal, decision, metareview). This distinguishes it from siblings like get_note (single note) or list_submissions (list without full details).

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

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

The description specifies the required parameter (forum id) and its equivalence to paper note id. While it implicitly suggests use for fetching a complete paper, it does not explicitly mention when to avoid or compare to alternatives like search_notes.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive nature. The description adds no behavioral context beyond 'metadata', which does not enhance the understanding beyond 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 concise at one sentence, front-loading the primary purpose. It could be slightly more descriptive, but fits the tool's simplicity.

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 has only one parameter, no nested objects, and an output schema, the description adequately covers the core functionality. It does not mention the output format, but that is handled by the output schema.

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

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

With 100% schema coverage, the description 'by group id' aligns with the required parameter, but adds no new meaning beyond the schema's description of group_id.

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 retrieving metadata for a venue/group by its ID. It is specific but does not differentiate from sibling tools like 'list_venues', which might list all venues.

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

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

The description implies usage for fetching a specific venue's metadata, but provides no explicit guidance on when to use this tool versus alternatives, nor any prerequisites or exclusions.

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

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

Annotations already indicate readOnly=true, destructive=false, idempotent=true. Description adds that it lists submissions but doesn't explain pagination or sorting behavior, which are partially covered by the schema.

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

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

Two sentences, front-loaded with purpose and examples. Every part is useful; no wasted words.

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

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

Given the output schema exists and annotations cover safety, the description is complete for a list tool. It provides relevant examples and context about similar venues, though could mention that results are limited to submissions at the specified venue.

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

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

Schema has 100% coverage, so baseline is 3. Description adds value for venue_id (how to find it) but doesn't elaborate on other parameters like sort, limit, or offset beyond what's 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 lists papers submitted to conference venues, with specific examples like ICLR and NeurIPS. It distinguishes itself from sibling tools like list_venues and get_paper by focusing on submissions aggregated by venue.

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 tells when to prefer this tool (e.g., 'what papers were submitted to ICLR') and how to find the venue_id using list_venues. Lacks negative examples but provides clear usage context.

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

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

Annotations already declare readOnlyHint and idempotentHint; the description adds value by specifying the exact return fields (id, type, params, etc.), confirming the non-destructive 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?

Two highly efficient sentences: first states purpose, second provides usage guidance. No fluff, front-loaded.

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

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

Given the simple tool (one optional param, no output schema) and complete annotations, the description covers purpose, usage, and return fields adequately.

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

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

Schema coverage is 100%; the description reinforces that inactive subscriptions are excluded by default (implied by 'active') and that include_inactive overrides this, adding context beyond the schema.

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

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

The description clearly states the verb (list) and resource (the caller's active subscriptions), distinguishing it from sibling tools like subscribe/unsubscribe.

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

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

Explicitly advises using this tool to review current subscriptions before adding more or to find an ID for cancellation, providing clear context and alternatives.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds that it lists venue groups and their ids are used for submissions, which is consistent but does not significantly enhance behavioral transparency beyond 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 two sentences long, front-loaded with the purpose, and contains zero wasted words. Every sentence adds value.

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

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

Given the tool's simplicity (3 optional params, no nested objects, and an output schema exists), the description is complete. It explains the resource type and the link to submissions, which suffices for an agent to understand and use the tool.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description does not add parameter-specific details beyond what is in the schema; it only provides context that the returned id is used for submissions.

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 verb 'List' and the resource 'venue groups (conferences, workshops)', which clearly distinguishes it from sibling tools like get_venue (singular) and list_submissions. It also explains the purpose of the returned id for querying submissions.

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 by mentioning the returned group id for submissions, but it does not explicitly state when to use this tool versus alternatives such as get_venue or list_submissions. It provides a workflow hint but lacks clear when-to-use or when-not-to-use guidance.

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

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

The description goes well beyond the annotations by disclosing rate limiting ('5 per identifier per day'), that it's free and doesn't count against tool-call quota, that filing without an account returns a claim_token, that the team reads digests daily, and that feedback affects roadmap. The annotations only say non-readonly and non-destructive; the description adds rich operational context with no contradictions.

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

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

The description is long but information-dense, with a logical flow: purpose → usage categories → exclusions → token mechanics → rate limits. Every sentence adds value, though some phrases (e.g., 'or when something worked surprisingly well (praise)') could be tightened. The front-loaded purpose and clear structure keep it highly usable.

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

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

For a tool with 4 params, no output schema, and nested objects, the description covers all essential contexts: what triggers each feedback type, the claim_token retrieval flow, rate limiting, and server boundaries. It leaves no major ambiguity about how to invoke the tool or what to expect.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds important semantic details beyond the schema: claim_token must be used with no other arguments, the message should avoid pasting the end-user's prompt and instead be framed in terms of Pipeworx tools/packs, and the type enum is essentially restated but with a 'praise' clarification. This extra guidance justifies a 4.

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

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

The description opens with a clear verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly names the categories (bug, feature/data_gap, praise) and distinguishes this tool from the many sibling tools by limiting it to feedback about Pipeworx's own tools/packs.

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 when-to-use guidance: use for bugs, missing features, data gaps, or praise. It also provides a clear exclusion—do not file feedback for tools from other MCP servers—and states to file with that server instead. The claim_token workflow (file now, check status later) is also clearly explained.

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, etc. The description adds valuable behavioral context: no PII, caching window (5min-1h), self-aggregating from CF analytics-engine. 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 key outcome. Three paragraphs, but each sentence adds value. Could be slightly more compact, but no redundancy.

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

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

Fully explains what the tool returns, its caching behavior, privacy aspect, and how it fits into the ecosystem. No output schema, but return values are clearly described. Complete for a read-only trending tool.

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

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

Schema covers 100% of parameters with descriptions and enum. The description adds extra semantic guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This helps agent choose the right window.

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

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

Description starts with a clear verb 'Returns' and specifies the resource: 'top tools, top packs, and total call volume over a recent window'. It distinguishes itself from sibling tools by focusing on trending data, not general discovery.

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

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

Provides three concrete use cases (discovering hot data, confirming canonical tools, checking alignment). While it doesn't explicitly list when not to use or alternative tools, 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 read-only, open-world, idempotent, non-destructive. Description adds extensive context: walks child markets, checks ordering, partition_sum ≈1, semantic anchor with Jaccard similarity, partition filter, fill check against live CLOB depth. Discloses that deviations >3pp emit signals and realizable_edge_pp ≤ 0 means no book edge. 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?

Front-loaded with core purpose. Contains detailed sections on modes, semantic anchor, partition filter, fill check, and cross-references. Every sentence adds value, though length is considerable. Could be slightly trimmed without losing substance, but overall well-structured.

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

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

Given complexity (multiple modes, checks, return fields), description is thorough. Explains return structure: opportunities[] with gap_pp, suggested_trade, reasoning, monotonicity context; partition_check details; fill check output fields. Cross-references polymarket_fill_risk for custom sizing. No output schema needed as description covers it.

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

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

Schema description coverage is 100%. Description enriches parameter meaning: event slug format examples, topic as seed question, use cases for each. Provides examples like 'fed-decision-may-2026' and 'Fed rate decision'. Adds context on how parameters affect behavior (single vs cross-event).

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes three modes: no args for trending scan, event for specific market, topic for cross-event scanning. This specificity differentiates it from siblings like polymarket_edges and polymarket_fill_risk.

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

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

Explicit guidance: 'Call with NO args for a trending_scan... pass event for ... or topic for ...'. Recommends event mode for specific markets, explains when cross-event is beneficial, and warns when not to trade (realizable_edge_pp ≤ 0). Also mentions custom sizing via polymarket_fill_risk.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds extensive detail: explains edge calculations (e.g., partition_overround with per-sport α), response structure (by_segment, diagnostics), caching (1h KV), and behavior like Fed exclusion. 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 dense but necessary for a complex tool. It front-loads the main purpose and then details segments, parameters, and response. Every sentence adds information, but a slight reduction in model-specific formula details could improve conciseness.

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

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

Given high parameter count (9), no output schema, and complex outputs, the description is remarkably complete. It explains the three response segments, diagnostics, filter knobs, caching, and even caveats about Fed data. All edge cases (empty segments, thin partitions) are addressed.

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 description still adds significant value beyond schema descriptions. For example, min_partition_leg_kelly is explained in depth, including why min_kelly doesn't filter partitions. Slippage_pp gets context on Polymarket fees and depth. Each parameter's description is enriched with usage advice.

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 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price' with a specific verb and resource. It distinguishes itself from siblings like polymarket_arbitrage by detailing its unique segmentation and model families.

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 frames the tool for 'what should I bet on today' and explains how to use knobs like min_liquidity and max_spread_pp. It provides guidance on why segments may be empty and how to adjust filters, though it does not explicitly contrast with sibling 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 a safe, read-only, idempotent operation. The description adds valuable behavioral context beyond annotations: history depth bounded by 60-day snapshot TTL, snapshots written on cache-miss, and decay computed from daily closes. No contradictions are present.

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 efficiently packed with information. It front-loads the purpose and key concept, then details response fields and limitations. Every sentence contributes value, though minor redundancy exists (e.g., repeated mention of default values).

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

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

There is no output schema, so the description fully covers the return values: tracked[], expired[], snapshot_dates[] with field explanations. It also includes limitations like snapshot TTL and cache-miss behavior. Given the tool's complexity, the description is remarkably complete.

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

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

Schema coverage is 100%, so parameters are well-documented. The description adds meaning by specifying default values, clamp ranges (days: 2-30, max 30), and window family options. It also explains the response structure, which adds significant value beyond the schema alone.

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

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

The description clearly states the tool provides edge persistence and decay telemetry from daily snapshots, answering specific questions about duration and trend. It distinguishes itself from siblings like polymarket_edges by focusing on historical time-series analysis.

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 check edge persistence and decay) and contrasts fresh vs. old edges, providing context. It does not explicitly state when not to use or list alternatives, but the context is clear enough for an agent to infer appropriate 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 indicate read-only, idempotent, open-world, non-destructive. The description adds essential behavioral details: walks the order book ladder, returns verdicts (clean|degraded|cannot_fill), and explains risks like forced directional risk from thin legs. 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 fairly long but well-structured with clear sections for single-market and basket modes. Every sentence adds value. Could be slightly more terse, but given complexity, it's appropriate.

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 lists return fields (top_of_book, vwap_fill_price, slippage_pp, etc.) and explains risks. It covers all necessary context for an agent to invoke the tool correctly.

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

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

Schema coverage is 100%, but the description adds significant meaning: explains default size_usd interpretation for buys vs. sells, basket mode settlement notional, and side auto-selection logic. This goes well beyond the schema descriptions.

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

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

The description clearly states it is an edge check against live CLOB order-book depth, and distinguishes between single-market and basket modes. It also specifies when it must be used (before arb signals or trades above ~$500), making its 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?

Explicitly states 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also warns about the risks of partial basket fills, giving clear when-to-use and when-not-to-use guidance.

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

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

The description goes beyond annotations by detailing response fields (compatibility_warning with two cases, temporal_alignment, skipped counters) and explaining edge cases, providing rich behavioral context.

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 and front-loaded, but somewhat long. Every sentence adds value, so it 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 and lack of output schema, the description thoroughly covers purpose, modes, response, and safety fields, leaving no major gaps.

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

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

Schema coverage is 100%, but the description adds value by explaining the two modes, listing the topic shortcuts, and clarifying how explicit parameters override topic mappings.

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 that the tool computes the cross-venue spread between Kalshi and Polymarket, describes two modes (topic and explicit), and distinguishes it from sibling tools like polymarket_arbitrage.

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

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

The description explains both modes and when to use each, including warnings that most pre-mapped topics return compatibility_warning, but it does not explicitly list alternatives or when not to use the tool.

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

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

Annotations declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds behavioral context: scoped to identifier, pairing with remember/forget, and the ability to list all keys by omitting argument. 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: first states main action, second gives examples and usage context, third explains scope and pairing. Front-loaded, 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?

Given only one optional parameter, rich annotations, and no output schema, the description fully covers purpose, usage, and behavioral constraints. 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?

Input schema has 100% coverage with one optional 'key' parameter. Description adds 'omit to list all keys', reinforcing schema description. Baseline of 3 is appropriate since schema already fully documents 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?

Description clearly states it retrieves a saved value or lists all keys. Uses specific verb ('retrieve', 'list') and resource ('value saved via remember', 'all saved keys'). Distinguishes from siblings like remember and forget by explicitly pairing with 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?

Explicitly states when to use: to look up context stored earlier without re-deriving. Provides examples and notes scoping. Does not explicitly state when not to use, but context is clear enough.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds behavior details: setting mark_read:true flags events as read, affecting future calls, and that polling works fine. This provides additional context beyond 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 concise, with the main purpose front-loaded. The second sentence about the alternative GET endpoint is informative but slightly tangential. Overall, every sentence adds value and there is no redundancy.

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

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

Without an output schema, the description sufficiently covers return values (source, citation_uri, raw payload). All parameters are addressed, and the behavior is explained. The tool is read-only with no destructive actions, so the description is complete for effective use.

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

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

Schema coverage is 100% with descriptions for each parameter. The description enriches these by providing examples (e.g., type: 'sec_8k'), clarifying formats (ISO timestamp for since), and explaining the effect of mark_read on future calls. This adds significant meaning beyond the schema alone.

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

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

The description clearly states the tool pulls fired events from the subscription feed and returns recent alerts. It specifies the verb 'pull' and resource 'fired events'. Although it doesn't explicitly differentiate from sibling tools like list_subscriptions or subscribe, the unique resource and filtering options make the purpose clear.

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

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

The description mentions polling works fine and provides an alternative URL for scripts/dashboards, implying when to use the tool vs other methods. However, it lacks explicit guidance on when not to use this tool or when to prefer alternatives among sibling tools.

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

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

Annotations already indicate read-only and idempotent behavior. The description adds behavioral details: fans out to multiple sources, fallback logic, soft-fail for USPTO, and return structure including changes[], total_changes, and citation URIs. No contradiction.

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

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

The description is well-structured with example queries upfront, followed by source details, parameter explanation, and return format. Every sentence adds value without redundancy, and it is appropriately sized for the tool's complexity.

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

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

Despite no output schema, the description explains the return structure and fallback mechanisms. It addresses edge cases (USPTO sunset) and provides a clear alternative tool (entity_profile). The description is complete for the tool's functionality.

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 parameters. The description enriches these by giving examples of valid 'since' formats (ISO dates and relative shorthand) and typical usage ('30d' or '1m'). It also clarifies that 'value' can be ticker or CIK.

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

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

The description clearly states the tool is a change feed for a company, using specific verb phrases like 'What's new with X' and explains it fans out to multiple sources. It distinguishes from entity_profile by specifying that entity_profile is for static profiles.

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

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

The description provides explicit when-to-use (e.g., 'latest on Y') and when-not-to-use ('Use entity_profile instead when you want the static profile'). It also explains fallback behavior between GDELT and GNews.

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?

Goes beyond annotations by detailing scoping by identifier, persistence duration (authenticated vs anonymous), and idempotent behavior. No contradiction with annotations (idempotentHint=true, destructiveHint=false).

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, then usage, then behavioral details. Every sentence earns its place without redundancy.

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

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

Given two parameters, no output schema, and high schema coverage, the description fully covers what the tool does, when to use it, and key behavioral traits (persistence, scoping). No missing 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%, but description adds examples of key formats (e.g., 'subject_property', 'target_ticker') and value types, enriching the semantic 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 states the tool saves data for reuse later, with specific examples (resolved ticker, target address, user preference). It distinguishes from sibling tools recall and forget by mentioning them explicitly.

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

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

Explicitly says when to use ('when you discover something worth carrying forward') and pairs with recall and forget, guiding the agent on alternatives. Provides clear context for 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 indicate read-only, idempotent, and non-destructive behavior. The description adds substantial context beyond this: it explains graceful degradation when GLEIF/OpenFIGI are unavailable, notes that unresolved identifiers are explicitly listed under 'unresolved', and mentions internal cascading lookups. This gives the agent a clear picture of failure modes and return 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 dense but well-structured. It opens with concrete user queries and a clear purpose, then breaks down supported types and enrichment behavior. Every sentence contributes unique information, and the length is justified by the tool's complexity.

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

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

Given the tool's complexity (two modes, multiple identifiers, potential partial failures), the description covers all critical aspects: what identifiers are returned, their source, unresolved handling, graceful degradation, and input conventions. There are no significant gaps that would hinder correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. However, the description adds significant meaning by explaining the two entity types in detail (company returns CIK, LEI, FIGI with source labels; drug returns RxCUI, ingredient, brand) and clarifying acceptable input formats (ticker, CIK, name for company; brand/generic for drug). This goes beyond the schema's simple definition.

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

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

The description clearly states the tool resolves a user-spoken name to canonical/official identifiers, with specific examples like 'find the CIK for...'. It distinguishes itself from siblings by emphasizing it provides identifiers that other tools require, and explicitly says 'Use FIRST whenever you have a name but need an ID'.

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

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

The description gives explicit guidance on when to use the tool: 'Use FIRST whenever you have a name but need an ID.' It also details supported entity types and input formats, but does not explicitly name alternative tools or exclusion criteria, so it falls short of a 5.

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

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

Annotations indicate safe, read-only, idempotent behavior. The description adds that it probes each entity with 'ai_visibility_check' and returns a ranked list with score, confidence, and signal density, providing useful behavioral insight 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 concise at 4 sentences, front-loaded with the main action. Each sentence adds value: purpose, method, use case, and output. No redundant or missing 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 the tool's complexity (comparing entities, calling another tool, ranking), the description covers main aspects: input, internal process, output. It lacks details on error handling or behavior for unsupported models, but is generally complete with good annotations.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context: first entity treated as 'subject', entities are brands/businesses/product names. This adds meaning beyond the schema, justifying a 4.

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

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

The description clearly states the tool's purpose: compare AI visibility across multiple entities side-by-side. It uses specific verbs ('Compare', 'Probes', 'ranks') and distinguishes from siblings like 'ai_visibility_check' (single entity) and 'compare_entities' (general comparison).

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

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

The description provides clear context for use: 'competitive AI-marketing audits'. It implicitly distinguishes from the sibling 'ai_visibility_check' by focusing on multiple entities. However, it lacks explicit exclusions or alternatives for similar tools like 'compare_entities'.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds rich behavioral context: it fans out across two external services, mentions partial failure (sources_failed list), and notes that bundlephobia's first measurement can take 5-30 seconds. 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 well-structured, starting with a concise summary, then usage guidance, return format, ecosystem note, and timing details. It is informative without being verbose, though slightly longer 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?

Despite no output schema, the description fully covers return values (summary block, per-advisory details, links, alternative versions) and edge cases (partial failures, timing for new versions). It is complete for a composite tool of this complexity.

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

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

Schema description coverage is 100% with clear descriptions of both parameters. The description indirectly adds context about default version behavior but does not provide additional meaning beyond the schema. Baseline of 3 is appropriate when schema is already comprehensive.

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

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

The description clearly states the tool performs a composite check for evaluating npm packages by querying deps.dev and bundlephobia. It explicitly distinguishes itself from siblings by focusing on package quality assessment, which none of the listed sibling tools address.

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 an agent asks "is X safe / popular / small" or "what does adding lodash cost me"' and also specifies the ecosystem limitation: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds that it returns note ids, titles, and venues, but does not cover pagination behavior or error cases. With informative annotations, a score of 3 is appropriate.

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

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

The description is a single, well-structured sentence that front-loads the core purpose. Every phrase is informative, with no wasted words. It is highly concise.

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

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

Given the presence of an output schema and full parameter descriptions, the description covers the essential behavioral details. It mentions return fields and optional filters. Minor omissions like pagination behavior do not significantly impair completeness.

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

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

Schema coverage is 100% with parameter descriptions. The description adds semantic value by explaining how to restrict to content fields (e.g., title, abstract) and filter by author signature, providing examples. This goes beyond the schema definitions.

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

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

The description clearly states the tool performs full-text search across OpenReview notes (papers, reviews, decisions) with optional restrictions. It specifies the return values (note ids, titles, venues), distinguishing it from sibling tools like get_note or search_within.

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 for when to use the tool (full-text search across notes) but does not explicitly state when not to use it or mention alternative tools. The sibling list provides context, but the description itself lacks exclusions.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description adds rich behavioral context: it uses BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, a 200K char cap with truncation flagging, and returns offsets. 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 yet comprehensive. Front-loaded with the core function ('Semantic search INSIDE a fetched record'), followed by usage context and technical details. Every sentence is essential and efficient, with no wasted words.

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

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

Given no output schema, the description fully explains what is returned (passages with offsets and similarity scores), plus implementation details (embedding model, window size, character cap, truncation). It leaves no critical gaps for an AI agent to understand the tool's behavior and limitations.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds some value for 'query' with examples and mentions the character cap for 'text', but the schema already provides clear descriptions (defaults, ranges, and constraints). The description does not significantly enhance parameter 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 states the tool's purpose: 'Semantic search INSIDE a fetched record.' It provides specific examples (SEC 10-K, article, long tool result) and contrasts with sibling tool ask_pipeworx_grounded, making the resource and verb highly specific and distinguishable.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt — search_within saves context.' It also provides alternatives: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This offers clear usage guidance and differentiation.

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 beyond annotations by detailing constraints (e.g., 10 SMS/day cap, webhook auto-disabled after 10 failures), authentication requirements, and type-specific behaviors. It adds significant context beyond the structured annotations.

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

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

The description is dense but well-structured, starting with the core purpose and then detailing types and delivery options. Every sentence adds value, though it could be slightly more concise.

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

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

Given the complexity of the tool (multiple types, delivery channels, constraints) and lack of output schema, the description provides a comprehensive picture covering all critical aspects.

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

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

Schema coverage is 100%, and the description adds substantial meaning for each parameter (e.g., type-specific params structure, delivery constraints). It enhances understanding beyond the schema alone.

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

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

The description clearly states the verb ('Create') and resource ('proactive monitoring subscription to a live-data event stream'), and specifies the return value ('Returns the new subscription id'). It distinguishes from sibling tools like 'unsubscribe' and 'list_subscriptions'.

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

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

The description specifies requirements ('Requires a Pipeworx OAuth account') and provides context on when to use (proactive monitoring) and what types are supported. It does not explicitly mention when not to use or compare with alternatives, but the context is clear.

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

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

Annotations already indicate non-destructive, read-only, idempotent behavior. The description adds context: returns sample questions, drawn from live catalog, with tool-argument shapes, 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?

Well-structured with trigger phrases first, then explanation of output, then usage. Somewhat lengthy but justified by the need to convey comprehensive onboarding 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 value structure (category-bucketed examples with tool shapes). Parameter count is low, and annotations cover safety. All necessary context is provided.

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

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

Schema coverage is 100% with one optional parameter. The description adds value by listing example values (finance, pharma, etc.) and explaining behavior when omitted, going beyond the schema's basic description.

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

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

The description clearly states it is the onboarding entry point returning category-bucketed example questions. It lists specific trigger phrases like 'What can I ask Pipeworx?' and distinguishes itself from siblings by being the first tool to use when unfamiliar with Pipeworx.

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

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

Explicitly says 'Use this FIRST' and provides clear guidance on when to omit topic for full spread or pass a specific topic. It also mentions alternatives for learning meta-tools.

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

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

The description adds behavioral details beyond annotations: ownership enforcement, deactivation (not deletion), and availability of historical events via recent_alerts. Annotations already indicate non-destructive, idempotent write, and description aligns with them.

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

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

Two concise sentences cover purpose, ownership, effect, and impact on historical data. Every sentence adds value without redundancy.

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

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

For a simple single-parameter tool, the description covers purpose, usage constraints, and side effects. It could mention idempotency explicitly, but annotations cover that. No output schema means no need to describe returns.

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 covers 100% of the single parameter with a description. The tool description adds context that the id comes from subscribe, providing useful provenance beyond what the schema offers.

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

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

The description clearly states the action 'Cancel a subscription by id' and immediately distinguishes itself from sibling operations like subscribe and recent_alerts by noting ownership enforcement and deactivation vs. deletion.

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 who can use the tool ('you can only cancel your own subscriptions') and explains what happens to historical data. It does not mention alternative tools like list_subscriptions for finding the id, but provides sufficient context.

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

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

Annotations already declare read-only, idempotent, and non-destructive, but the description adds crucial behavioral details beyond that: dual routing logic, specific verdict labels, the pipeworx:// citation, and a critical clarification that 'could_not_verify' means the check did not happen and must not be treated as evidence. It also clarifies the meaning of 'unsupported', giving callers a full understanding of what the tool returns and what each outcome implies.

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 but every sentence earns its place. It opens with concrete query examples, defines the tool's purpose, explains the two processing paths, lists return values, and warns about the 'could_not_verify' trap. Despite length, it is well-organized and front-loaded, with no redundant filler or repetition of schema details.

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

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

Given the absence of an output schema, the description fully covers return values (verdicts, actual value, citation, reasoning) and error semantics (could_not_verify with verification_error, unsupported). It also handles context by describing the automatic routing and the fact that this replaces multiple sequential calls, leaving no significant gaps for an agent to operate correctly.

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

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

Schema coverage is 100% with clear descriptions for both 'claim' and 'tolerance_pct'. The description adds extra value by explaining how tolerance_pct overrides the claim's implied tolerance, provides a suggested range for hallucination detection, and states the default cap at 5. This goes beyond the schema and helps agents set the parameter appropriately.

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 natural-language claim verification against authoritative sources, with specific examples of user phrasing. It further distinguishes two distinct paths (SEC EDGAR/XBRL for company-financial claims vs. grounded pipeline for all else), making it unambiguous what the tool does and how it differs from general research or lookup tools.

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

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

The description states explicitly when to use: 'whenever the agent needs to check whether something a user said is factually correct.' It also notes the tool replaces 4–6 sequential calls, implying it should be preferred over multi-step alternatives. However, it does not explicitly name sibling tools to avoid or provide exclusion criteria beyond the coverage of claim types, so it lacks explicit when-not guidance.

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