Bcb Br

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

Annotations already signal read-only, idempotent, non-destructive behavior. The description adds valuable context: default model is free Workers AI Llama-3.3-70b, and using Anthropic requires a BYO key with direct costs. This goes beyond annotation data, though it omits details like rate limits or error handling.

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 the core purpose, then model/cost details, then output structure and use cases. No wasted words; every sentence contributes essential 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?

With no output schema, the description compensates by specifying the return shape: per-model {score, confidence, signals, raw_response} + a combined view. It also covers default behavior and use cases. Minor omissions (e.g., meaning of 'signals' or confidence) keep it from a 5.

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

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

Schema coverage is 100% with detailed parameter descriptions. The description adds non-obvious context: the default model name ('Llama-3.3-70b') and the cost implication of using _apiKey. This exceeds the baseline for high schema coverage.

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

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

The description clearly states the tool probes LLMs for knowledge about a business/brand/product/topic and produces a 0-100 visibility score per model. The verb 'probe' and resource 'LLMs' are specific, and the scoring output distinguishes this tool from sibling tools like ask_pipeworx or deep_research.

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

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

Provides explicit use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It implies when to use the tool but does not name alternatives or exclusions relative to siblings, 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 already declare read-only, idempotent, and non-destructive behavior. The description adds meaningful behavioral context: it routes to 5,354 tools, fills arguments, returns stable citation URIs, and claims one-fast-call performance. This goes beyond the annotation baseline, though it omits failure modes or rate limits.

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

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

The description is longer than a typical tool description but every sentence carries strategic value: positioning, scope, examples, and alternatives. It is front-loaded with 'PREFER OVER WEB SEARCH' and uses structured guidance, though slightly repetitive near the end regarding news handling.

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

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

For a high-complexity routing tool with no output schema, the description covers its purpose, domain breadth, examples, tier compatibility, performance expectations, and when to escalate to siblings. It provides a complete picture for an agent to select and invoke this 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 is fully self-descriptive with 100% coverage, listing the question parameter and all aliases with descriptions. The description adds no parameter-specific semantics beyond the schema, so the baseline score of 3 applies.

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

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

The description clearly identifies the tool as a routing/answering engine for authoritative structured data with citations, listing concrete domains and example questions. It distinguishes itself from siblings by positioning as the default entry point and explicitly naming alternative tools for different use cases.

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

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

It explicitly says to prefer this over web search, provides trigger phrases, and gives step-up guidance for grounded research and deep research. Also clarifies that breaking-news queries are already handled by this tool, preventing misrouting.

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 about its experimental status: candidate improvements are tested live, currently no candidate is active, and it is a full working router that falls back to nothing. This clarifies behavior beyond the annotations without contradicting them.

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

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

The description is well-structured and front-loaded with the key fact that it is a beta version. Each sentence serves a purpose, though there is some redundancy in stating 'identical universal router' and listing the same tool count. It is concise enough for an agent to parse quickly.

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 a router with thousands of tools, the description adequately covers the essential context: it's a working beta, currently identical to the stable version, and usage guidance is clear. It references the same response shape as ask_pipeworx, though without an output schema, it could be more explicit about return structure. Overall, it is sufficiently complete for safe invocation.

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

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

The schema covers all parameters (100%) with descriptions for the question field and its aliases. The description only references 'same arguments' without adding any new parameter semantics, so it meets the baseline but adds no extra value.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx and a universal router with the same tool set, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by being the experimental edge with candidate routing improvements.

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 instructs to use it exactly like ask_pipeworx when wanting the newest routing, and mentions that results are compared against the stable router. This provides clear when-to-use guidance and implicitly contrasts with the stable alternative.

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

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

The description discloses behavioral details beyond the annotations: it explains that the tool 'EXTRACTS the answer using ONLY what the tool result contains', provides the exact success return object with evidence as a verbatim quote, and enumerates five explicit refusal_reason values. This gives the agent a clear model of the tool's refusal behavior. No contradiction with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) is 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 five sentences long, each earning its place: purpose, mechanics, return object, usage context, and cost tradeoff. It is front-loaded with the most important title-like phrase ('Hallucination-resistant answer mode') and structured logically, making it easy to scan and understand.

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 though there is no output schema, the description fully specifies the success and refusal return structures, including the refusal_reason enum values. It includes routing behavior, the scope of source tools, use cases, and the alternative sibling. For a tool with this 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?

The input schema already provides 100% coverage for all 6 parameters, with each alias described as equivalent to 'question'. The description adds no additional parameter-level semantics, but because schema coverage is high, the baseline of 3 is appropriate. It does not need to compensate for schema gaps.

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

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

The description clearly identifies the tool as a 'Hallucination-resistant answer mode for high-stakes reads' and explicitly distinguishes it from sibling tool ask_pipeworx by noting 'Same routing as ask_pipeworx' but with the critical difference of extracting answers only from tool results and providing explicit refusals. This goes beyond a generic verb+resource to fully differentiate the 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?

Usage guidance is explicit: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and 'prefer ask_pipeworx for casual lookups.' It also mentions the cost tradeoff ('Costs one extra LLM call') which helps the agent decide between alternatives. This is a textbook example of when/when-not guidance.

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

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

The description goes far beyond annotations, detailing the fan-out mechanism, response shapes, resolver confidence contract, safety short-circuits, wide-spread tradeability, and cancellation-rule parsing. This is especially valuable since annotations only state read-only and open-world hints; the description adds critical context about low-confidence matches and illiquid markets. No contradiction with annotations.

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

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

The description is front-loaded with a clear purpose and uses headers for organization, which helps navigate the density. It is long, but the tool's complexity justifies the length, though some tangential asides (e.g., 'audited arb-bot ledgers') could be trimmed.

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

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

With no output schema, the description fully explains the return structure: result.market, result.analysis, result.evidence, resolver contract, parent_event, news fallbacks, and safety statuses. It covers all critical edge cases an agent must handle, making it self-sufficient.

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

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

Schema coverage is 100%, so the baseline is 3. The description reinforces the market parameter's accepted formats but adds no new information beyond the schema. It does not mention depth or include_raw, though the detailed fan-out examples indirectly illustrate what 'thorough' does.

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

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

The description opens with a specific verb+resource ('Research a Polymarket bet') and clearly distinguishes itself from sibling market-scanning tools by focusing on a single bet. The classifier list and fan-out examples further reinforce its specific role of pulling relevant Pipeworx data for one market.

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

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

Explicit use cases are provided ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'), giving clear context on when to invoke. It does not mention alternatives or exclusions, but the single-bet focus implies when it is appropriate relative to broader siblings like polymarket_edges.

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

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

Despite annotations already declaring readOnly, idempotent, and non-destructive, the description adds substantial behavioral context: parallel execution, SEC EDGAR/XBRL data sourcing, off-calendar fiscal year handling, sorting by primary metric, and citation URI returns. 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?

Description is dense but well-structured: trigger phrases lead, followed by usage rule, type-specific data details, and return info. Minor redundancy in repeating the benefit over sequential lookups, but every sentence earns its place.

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

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

Covers both entity types, sorting behavior, return format (paired data + citation URIs), and performance benefit. Without an output schema, it could be more explicit about exact return fields for each type, but it is complete enough for a complex tool with two modes.

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 type and values. The description enriches semantics by specifying what type='company' pulls (revenue, net income, cash, long-term debt) and type='drug' pulls (FAERS, FDA approvals, trials), adding value beyond the schema.

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

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

Description explicitly states side-by-side comparison of 2–5 companies or drugs in ONE parallel call, with trigger phrases like 'X vs Y' and 'rank these companies.' It clearly distinguishes itself from sequential lookups and sibling tools by emphasizing entity comparison versus single-entity lookups.

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

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

Provides explicit when-to-use rule: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Also lists natural-language triggers and differentiates behavior by type ('company' vs 'drug'), giving concrete guidance for selecting 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?

Goes far beyond annotations by disclosing account requirements, paid tier for 'thorough', return structure with gaps[] and contradictions[], grounding behavior ('never invented'), semantic excerpting, and latency expectations (15-90s). No contradiction with readOnlyHint, idempotentHint, or openWorldHint; it clarifies that it is not open-web search despite being open-world.

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

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

The description is long and information-dense, but front-loaded with the account requirement and core use case. Every sentence earns its place for a complex tool, though it could be slightly tightened without losing critical guidance.

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

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

With no output schema, the description fully compensates by explaining the findings packet (verbatim evidence, confidence, source, fetched_at, citation_uri, hop field, gaps[], contradictions[]), latency, and limitations. It leaves no major question about expectations or return semantics.

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?

Even though the schema covers 100% of parameters, the description adds deep semantic value: explains what each depth level actually does (hop counts, gap recovery, contradiction scan, paid restriction) and clarifies that questions can be broad/multi-part. This meaningfully surpasses the baseline 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 uses specific action language: 'Grounded multi-source research across Pipeworx's 1395 STRUCTURED data sources' in one call, and clearly distinguishes itself from open-web search and siblings like ask_pipeworx. It states the intended use case: broad/multi-part questions over structured data.

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, and explicitly names alternatives for single lookups (ask_pipeworx), breaking/current-news topics (ask_pipeworx), and when not signed in (ask_pipeworx). This is exemplary usage 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 declare readOnlyHint=true and idempotentHint=true, covering the safety profile. The description adds valuable behavioral context by describing the return format: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' No rate limits or auth needed are mentioned, but this is acceptable for a read-only discovery tool.

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

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

Four sentences, each serving a distinct purpose: purpose statement, usage scope with domain list, return format, and call-precedence advice. No fillers or redundant repetition; the domain list is informative rather than superfluous.

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 read-only discovery tool with no output schema, the description fully covers what the tool does, when to use it, and what it returns (names, descriptions, full schemas). It even notes that results are directly callable, eliminating any guesswork about follow-up steps.

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 all six parameters documented, including aliases and the limit's max value. The description only indirectly references the query concept ('describing the data or task') and does not add new parameter semantics beyond the schema, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb+resource: 'Find tools by describing the data or task.' It clearly distinguishes this tool from siblings by framing it as a discovery/meta-tool that searches for other tools, and it lists supported domains to clarify scope.

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 usage guidance is provided: 'Use when you need to browse, search, look up, or discover what tools exist...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This implies the alternative of calling a specific tool directly for a single known answer, meeting the when/alternatives criterion.

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

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

Annotations already mark it readOnly, idempotent, openWorld, and non-destructive. The description adds behavioral details such as fanning out across SEC EDGAR, XBRL, USPTO, news, GLEIF; specifies the exact fields returned; and notes the USPTO API sunset May 2025 with soft-fail behavior and GDELT→GNews fallback. This goes well beyond the annotations' safety profile.

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

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

The description is a single dense paragraph with many clauses, but it is front-loaded with user-phrase examples and bulk details. It's longer than ideal but every sentence contributes operational or contextual value. Slight verbosity (e.g., ALL CAPS emphasis) prevents a 5.

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

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

The tool has no output schema and moderate complexity, so the description carries the burden of explaining return values. It does so by listing cik, company_name, recent_filings with URIs, fundamentals, patents, news, and LEI, plus fallbacks and limitations. This is sufficient for an agent to set 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?

Input schema covers both parameters with descriptions including enum values and ticker/CIK format. The description repeats the zero-padded CIK requirement and the unsupported-names constraint, adding little new information beyond what the schema already documents. Since schema coverage is 100%, it meets the baseline but doesn't elevate.

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 it creates 'full cross-source profile of a US public company in ONE parallel call', with examples like 'Tell me about X' and a clear scope. It clearly distinguishes itself from sibling tools by saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and references resolve_entity for name-only inputs.

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

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

It provides explicit when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also gives a when-not: names are not supported, use resolve_entity first, which names an alternative.

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

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

Annotations already declare read-only and idempotent behavior. The description adds valuable context about the return fields and the nature of the data (annual median/mean forecasts), which goes beyond annotations. No contradictions found.

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 convey the tool's purpose, filter options, and return fields without redundancy. The description is front-loaded with the main function and examples, making it efficient.

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

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

Even without an output schema, the description lists the return columns, providing a clear expectation of the data. Combined with the schema and annotations, the information is sufficient for this tool's complexity. A small gap is the lack of mention of the 'top' parameter, but it is documented in the 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 each parameter has a description. The description adds marginal extra parameter context (e.g., an additional indicator example 'IGP-M'), but does not significantly enrich beyond what the schema already provides.

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

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

The description clearly states the tool accesses the Focus market expectations survey, with specific details on the data source (~150 economists) and return fields (Media, Mediana, etc.). It distinguishes itself from sibling tools by focusing on this specific survey and indicator filtering.

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: filter by indicator and optionally reference year. It doesn't explicitly mention alternatives or exclusions, but the context is specific enough for an agent to infer when to invoke it.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true, covering the safety profile. The description reinforces the destructive nature with 'Delete' and adds the context of clearing sensitive data, but does not disclose additional behavioral details beyond what annotations provide, so a baseline 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 two sentences, front-loaded with the main action, and every clause adds value: the operation, the use cases, and the complementary tools. 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?

For a simple, single-parameter tool with rich annotations and no output schema, the description is complete. It covers what the tool does, when to use it, and the deletion target, making it self-sufficient for agent invocation.

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

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

The schema provides 100% coverage for the 'key' parameter with a clear description ('Memory key to delete') and an example. The tool description adds no new parameter semantics beyond restating that it operates 'by key,' so the baseline 3 applies per the schema-heavy calibration.

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: 'Delete a previously stored memory by key.' It uses a specific verb (Delete) and resource (memory by key), and differentiates from sibling tools like remember and recall by explicitly framing the operation as 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 gives explicit use cases: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also mentions pairing with remember and recall, but lacks a direct 'when not to use' statement or alternative tool comparison, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds valuable context about the internal process (fetches page, extracts title/description/links) and the output format (single text blob). It does not mention potential failures or rate limits, but the annotations lower the bar, and the added context justifies a 4.

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 plus a 'Useful for' list. It front-loads the core functionality, then provides use cases. Every sentence contributes value, with no filler or redundancy. This is exceptionally concise and well-structured.

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

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

For a simple read-only tool with two parameters, the description is complete: it explains inputs, process, output, and a few use cases. There is no output schema, but the description explicitly states the output is a text blob ready for site-root deployment. It lacks details on error handling or edge cases, but that is a minor gap for this tool's simplicity.

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 both 'url' and 'max_links' fully described. The description reinforces the purpose of the 'url' parameter but does not add significant new semantics beyond what the schema already provides. Since the schema covers everything, a baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: generating a production-ready llms.txt file for any URL. It names the specific resource (llms.txt), the verb (Generate), and describes the process (fetches page, extracts metadata, emits markdown). It also distinguishes itself from siblings like scan_competitor_ai_presence by focusing on file generation rather than presence scanning.

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

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

The description provides explicit use cases in the 'Useful for' section: indexing a client's site, drafting llms.txt, and auditing competitor visibility. This gives clear context on when to use the tool, though it does not explicitly mention alternatives or when not to use it, which would earn a 5.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds behavioral detail by stating it 'Returns the latest N observations with the series label and unit', which informs the agent about the output shape without contradicting the annotations. It doesn't cover edge cases like rate limits, but the added output context goes 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 two sentences, front-loaded with the tool's purpose and supported names, followed by the return behavior. Every sentence earns its place, and there is no redundant or filler 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 tool's simplicity (2 params, read-only, idempotent), the description covers all essential aspects: what it does, supported names, the 'last' parameter behavior, and the return content. Annotations cover safety, and the schema covers parameter details. No output schema exists, but the description sufficiently explains the return shape, making the tool fully understandable for an agent.

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

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

Schema coverage is 100% with both parameters having descriptions. The description adds semantic meaning to the 'name' parameter by explaining these are friendly names and no SGS code is needed, which is not fully conveyed by the schema's simple enum list. For 'last', it essentially restates the schema's 'latest N observations' but doesn't introduce new meaning. Overall, it adds value beyond the schema.

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

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

The description clearly states the tool is a 'Convenience lookup for common Brazilian macro indicators by friendly name (no SGS code needed)', which specifies both the action (lookup) and the resource (Brazilian macro indicators). It also lists the exact supported names and distinguishes it from sibling tools like 'sgs_series' by explicitly noting that no SGS code is required.

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: this tool is for looking up common indicators by friendly name, avoiding the need for SGS codes. This strongly implies it should be used over 'sgs_series' when a friendly name is available, though it doesn't explicitly name the alternative or state when not to use it. Thus it is clear but lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds that it returns friendly names with codes and units, which is useful but does not disclose additional behavioral traits (e.g., dynamic output). 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?

A single, front-loaded sentence that conveys the core purpose and output fields without any wasted words. Highly concise and well-structured.

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

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

For a zero-parameter, no-output-schema tool, the description adequately covers what the tool returns (friendly names, SGS codes, units) and its relationship to the indicator tool. The annotations handle safety and idempotency, making this complete.

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

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

The tool has zero parameters, so parameter semantics are inherently satisfied. The description correctly implies no input is needed. Baseline 4 is appropriate.

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

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

The description uses a specific verb 'List' and identifies the resource as 'friendly indicator names available to the indicator tool', including SGS codes and units. This clearly distinguishes it from sibling tools like 'indicator' 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 phrase 'available to the indicator tool' provides clear context that this tool is for discovering indicators before using the indicator tool. It does not explicitly list exclusions or alternatives, but the context is strong 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 declare readOnlyHint, idempotentHint, and destructiveHint. The description adds that it is scoped to the caller's subscriptions and lists the return fields, which is useful behavioral context beyond what annotations provide. 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 two sentences, front-loaded with the verb, and every sentence serves a purpose: stating what it does, what it returns, and when to use it. 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?

For a simple list tool with one optional parameter and no output schema, this description is complete. It names the return fields, clarifies the default active-only behavior, and provides use cases.

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

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

Schema description coverage is 100% since include_inactive has a description. The tool description adds no additional parameter semantics, so the baseline of 3 applies.

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

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

The description clearly states the tool lists the caller's active subscriptions, with a specific verb and resource. It distinguishes itself from sibling tools like subscribe/unsubscribe by being the read operation, and it enumerates the exact returned fields.

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 scenarios: 'review what you're monitoring before adding more' and 'find an id to cancel.' It lacks explicit when-not-to-use or named alternatives, but the use cases are clear enough for an agent to select this tool.

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

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

The description adds meaningful behavioral context beyond the annotations: rate-limited to 5 per identifier per day, free (doesn't count against quota), and that the team reads digests daily. It also advises describing issues in terms of Pipeworx tools/packs, which is a behavioral constraint. 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 and efficient: it opens with a clear purpose, then lists usage scenarios, and finishes with operational constraints. Every sentence contributes value, and there is no redundant repetition of schema 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?

For a feedback tool with 3 parameters and no output schema, the combination of description and schema fully covers the tool's purpose, triggers, message composition, and constraints. It lacks only an explicit note about what happens after submission, but the description already indicates the team reads digests daily, which is sufficient.

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

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

The schema already provides detailed descriptions for all parameters (100% coverage), so the baseline is 3. The description adds extra guidance on how to compose the message (describe in terms of tools/packs, don't paste prompts), which aids parameter selection 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's purpose: to tell the Pipeworx team about something broken, missing, or working well. It specifies the resource (Pipeworx team) and the action (send feedback), and distinguishes itself from sibling research/ask tools by focusing on feedback rather than data retrieval.

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

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

Provides explicit use cases: when a tool returns wrong/stale data (bug), when a desired tool is missing (feature/data_gap), or when something works well (praise). It also gives clear exclusions (don't paste end-user prompt) and context on rate limits, making it easy to decide when to use this tool.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description adds valuable behavioral details: it is self-aggregating from the CF analytics-engine, contains no PII, and is cached for 5min-1h depending on window. This transparently discloses data source, privacy, and freshness characteristics.

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, front-loaded with the core purpose, then organized into a 'Useful for' list and technical details. Every sentence earns its place, with no redundant or filler 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 low complexity (single optional parameter, no output schema), the description fully covers what is needed: it states the return content (top tools, packs, volume), explains the data source, caching, and provides practical use cases. It is complete for an agent to decide when and how 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?

The schema descriptions already cover the window parameter fully (enum values, default, semantics). The tool description reinforces this by mentioning window options and adds a useful note about caching being dependent on the window, providing extra meaning beyond the schema. Baseline 3 raised due to this added context.

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

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

The description clearly states what the tool does: returns top tools, top packs, and total call volume for AI agent calls on Pipeworx over a recent window. It uses a specific verb ('Returns') and resource ('top tools, top packs, call volume'), and the 'trending' concept distinguishes it from sibling tools like discover_tools.

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

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

The description provides three explicit use cases: discovering hot data sources, confirming a canonical tool choice, and checking alignment with agent needs. This gives clear context for when to use the tool, though it does not explicitly mention alternative sibling tools for contrast.

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

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

Annotations already declare readOnly/openWorld/idempotent, and the description adds rich behavioral context: monotonicity checks, partition-sum with >3pp threshold, semantic anchor Jaccard ≥0.30, placeholder fraction >20% null signal, and fill check pricing against live CLOB depth. No contradiction with annotations.

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

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

The description is long but well-structured with bolded labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded purpose. Every sentence contributes, though the partition_check concept is repeated a few times; still 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?

With no output schema, the description fully describes return values (opportunities[], partition_check), edge cases (thin_legs, placeholders_filtered, skipped_low_similarity), and failure conditions (realizable_edge_pp ≤ 0). It is self-sufficient for an agent to invoke 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 description elevates semantics significantly: explains event slug examples and URL acceptance, topic seed question examples, and mode-specific processing (walks child markets, computes partition_check, flattens markets). This goes beyond the schema's property 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?

Description opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes two modes (event, topic) and a default trending_scan, and explicitly references sibling polymarket_fill_risk for custom sizing, avoiding confusion with related 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?

Provides explicit when-to-use guidance: 'Call with NO args for a trending_scan', 'pass event for the strongest per-event partition_check', 'topic for a themed cross-event scan.' Also warns against trading when realizable_edge_pp ≤ 0 and directs to polymarket_fill_risk for custom sizing, fulfilling the when/when-not/alternatives requirement.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive, and the description adds substantial behavioral detail beyond that: the output is grouped by segment, every opportunity includes edge_pp_net after slippage and a 24h-move warning, results are cached for 1 hour keyed on knobs, and diagnostics expose why segments may be empty. This level of disclosure goes far beyond the annotations and helps the agent interpret unexpected results.

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

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

The description is a dense wall of text, but it is structured with uppercase section labels (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL) and front-loads the core purpose in the first sentence. Every sentence carries decision-relevant detail, though the sheer length and parenthetical density make it harder to scan quickly than a tighter description would be.

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

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

With no output schema, the description compensates thoroughly by enumerating the top-level response fields (by_segment, fed_candidates/fed_note, _diagnostics), the per-opportunity fields each edge carries, the three model families and their internal logic, and the filtering knobs. It also explains caching behavior and diagnostic counters, giving an agent enough context to understand the full output shape and debug empty results.

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

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

Although the schema already describes all 9 parameters at 100% coverage, the description adds meaningful context: it groups min_liquidity and max_spread_pp as 'tradeable-edge knobs', explains that min_partition_leg_kelly operates on per-leg Kelly because parent-level basket Kelly is zero by design, and ties slippage_pp to real-world Polymarket execution. This enriches the raw schema with usage intent and relationships between parameters.

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

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

The description opens with a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It further defines the tool's purpose as 'what should I bet on today' and names the three model families that make up the output, clearly distinguishing this from generic arbitrage or market-scanning 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 gives clear usage context: it is built for discovering bet opportunities without paging hundreds of markets, and explains how the tradeable-edge knobs and segment filters shape results. It explains why Fed candidates are excluded from ranking, but it never explicitly names alternative tools or states when not to use this tool, so it stops short of full exclusion 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 declare read-only/idempotent, and the description adds significant behavioral context: snapshots are written on cache-miss (gaps mean no scan), history bounded by 60-day TTL, and decay computed from daily closes, not intraday. This goes well 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 dense but well-structured using RESPONSE and LIMITS headers. Every sentence contributes useful info, though it could be slightly more scannable with bullet lists. It remains front-loaded with the core purpose.

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

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

Despite no output schema, the description fully explains the response structure (tracked[], expired[], snapshot_dates[]) with field meanings, and covers limitations (TTL, snapshot gaps, decay basis). This is thorough for a telemetry 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?

Schema coverage is 100% with clear descriptions for both params (days default/clamp, window family). The description repeats defaults and adds no new parameter-level semantics beyond what schema already provides, 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 a specific verb-resource pair: tracks edge persistence and decay over time from polymarket_edges snapshots. It distinguishes itself from siblings like polymarket_edges by focusing on 'how long has this edge existed and is it shrinking?'

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

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

It provides clear context on when to use: when you need edge history/longevity, and highlights the trade distinction between fresh and old edges. It does not explicitly name alternative tools, but the purpose statement implies comparison with current-edge tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds rich behavioral context without contradicting them. It details internal behavior (walks the ladder, computes top_of_book, vwap_fill_price, slippage_pp), return fields, limitations (thin legs, forced directional risk), and clamping behavior (size clamp 10–1,000,000).

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 (~250 words) but well-structured with clear sections (SINGLE-MARKET, BASKET, USE THIS before) and no redundant fluff. It earns its length given the tool's two-mode complexity and numerous output fields, though it could be slightly more scannable.

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

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

With no output schema, the description fully compensates by enumerating all key return values per mode (top_of_book, vwap_fill_price, slippage_pp, capture_ratio, thin_legs, etc.) and covering edge cases like partial basket fills and forced directional risk. It also tells the agent exactly when to invoke this tool relative to sibling tools.

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

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

Schema coverage is 100% (each parameter has a description), but the tool description adds substantial meaning beyond the schema. It clarifies how side and size_usd behave differently in single-market vs basket mode, explains the auto default for side in basket mode, and defines size_usd as settlement notional for baskets (shares per leg, each paying $1).

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

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

The description opens with a specific verb+resource phrase 'Realizable-vs-theoretical edge check against live CLOB order-book depth', clearly stating the tool's purpose. It distinguishes from siblings by naming related tools (polymarket_arbitrage, polymarket_edges) and positioning itself as the pre-trade risk validation step.

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 usage guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains the two modes (single-market vs basket) and when each is appropriate, plus why the tool matters (theoretical overround on thin books is not capturable).

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

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

The description richly discloses behavior beyond the annotations: it explains compatibility_warning conditions, temporal_alignment, skipped_cross_type counters, and return format (raw probabilities, top_spreads_pp). This goes far beyond the readOnly/idempotent hints, giving a full picture of what to expect and its limitations.

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

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

The description is long but every sentence provides substantive information. It is structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loads the core purpose. No redundant filler.

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

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

Given the tool's complexity (two modes, multiple safety fields, temporal alignment, no output schema), the description covers all essential aspects: inputs, response structure, edge cases, and caveats. It gives a comprehensive picture in one place.

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

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

Although the schema already describes each parameter (100% coverage), the description adds mode-level semantics: topic auto-fetches matching events, while explicit parameters override the mapped side. This clarifies how parameters interact, which is not fully captured by individual field descriptions.

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

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

The description opens with a precise statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It then details two modes, response contents, and safety fields, making it unambiguous what the tool does and how it differs from related 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?

It gives clear context on when to use each mode: topic shortcuts for quick macro checks, explicit ticker/slug for custom pairings. It also warns that 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable,' which is important usage guidance. However, it does not explicitly name alternative tools for comparison.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral context by noting that quotes are not published on weekends/holidays, implying the tool may return no data or an error on those days. It also discloses the exact return structure, going beyond what annotations provide.

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

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

The description is two sentences, front-loaded with the core purpose, and includes output structure and a key constraint without any fluff. Every word earns its place.

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

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

For a simple one-parameter read-only tool with full schema coverage and no output schema required, the description is complete. It explains what is returned, the format, and a critical availability caveat, covering all necessary information for an agent to use it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description reinforces the date parameter requirement ('specific business day') and the weekend/holiday caveat, but does not add additional syntax or formatting details beyond what the schema already provides. The parameter meaning is fully captured by the schema description.

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

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

The description clearly states the tool returns the official PTAX USD/BRL quote for a specific business day, including buy/sell rates and timestamp. It also specifies the exact return fields ({cotacaoCompra, cotacaoVenda, dataHoraCotacao}), making the tool's purpose unambiguous and distinct from any 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 implies the tool should be used for specific business days and warns that quotes are not published on weekends/holidays, which gives clear timing context. It does not explicitly name alternative tools, but given the niche nature of PTAX quotes, that is not necessary for effective guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds valuable context: the tool is scoped to an identifier (anonymous IP, BYO key hash, or account ID), which explains data isolation, and that omitting the key lists all saved keys. This goes beyond the annotations without contradicting them.

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

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

The description is three sentences, front-loaded with the primary action, and every sentence adds value: what it does, when to use it, and how it relates to siblings. No redundancy or filler.

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

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

Given the simple one-parameter schema, strong annotations, and no output schema, the description is fully complete. It covers the main use case, scope, and pairing with sibling tools, making it easy for an agent to select and invoke 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 the key parameter fully described. The description adds additional meaning by explaining that omitting the key triggers list-all behavior, and clarifies the semantic relationship to remember and forget. This exceeds the bare schema description.

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

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

The description clearly states the tool retrieves a previously saved value via remember or lists all saved keys when the key argument is omitted. It names the resource (saved memory) and the verb (retrieve/list), and distinguishes itself from sibling tools remember and forget.

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

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

It explicitly explains when to use: 'to look up context the agent stored earlier... without re-deriving it from scratch.' It also pairs with remember and forget, providing clear context on how it fits into the workflow, and implicitly when not to use (when you want to save or delete, use those alternatives).

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

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

The annotation readOnlyHint=true conflicts with the mark_read:true parameter which mutates read state. The description discloses this mutation but contradicts the annotation's claim of read-only behavior. This is an annotation contradiction, so a score of 1 is required.

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 5 sentences, front-loaded with the primary purpose. Each sentence adds value (return payload, filtering, mark_read, polling/alternative), but it is 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?

Given no output schema, the description partially describes return fields (source, citation_uri, raw payload) and explains mark_read's effect on subsequent calls. It also provides an external endpoint. It is fairly complete for a simple read tool, though without full output structure.

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

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

All 5 parameters have descriptions in the schema (100% coverage), so the description adds little beyond an example type ('sec_8k') and prose explanation of mark_read. The schema already covers semantics, so the baseline 3 applies.

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

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

The description uses a specific verb ('Pull') and resource ('subscription feed'), clearly stating it returns recent alerts with source, citation_uri, and raw payload. This distinguishes it from sibling tools like list_subscriptions and recent_changes.

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

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

The description notes that polling works fine and that the same feed is also available at a GET endpoint for scripts/dashboards, providing an alternative. However, it does not explicitly state when this tool should be used over sibling tools like recent_changes or ask_pipeworx, so it is clear but lacks explicit exclusions.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description reveals multi-source fan-out, a soft-fail behavior for the patent API, and date parsing rules. This adds substantial operational context not visible in annotations.

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

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

The description is dense but every sentence carries semantic weight: common queries, source behavior, parameter formats, return shape, and an alternative tool. It is front-loaded with the most useful usage hints and avoids filler.

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

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

With no output schema, the description adequately explains the return structure (changes[] grouped by source, total_changes, pipeworx:// URIs). It covers multi-source aggregation, fallbacks, date handling, and provides an explicit alternative, making it complete for a 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 coverage is 100%, so the baseline is 3. The description adds practical examples and recommendations: 'since' accepts ISO or relative shorthand and '30d'/'1m' is suggested for monitoring; 'value' shows ticker/CIK examples; 'type' clarifies only 'company' is supported. This goes beyond the schema's basic 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 specific action verbs ('Fans out to', 'Returns') and clearly defines the resource as a change feed for a company, with concrete sources (SEC EDGAR, GDELT/GNews, USPTO). It also distinguishes itself from the sibling tool entity_profile by name and use case.

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 opens with natural-language triggers ('What's new with X', 'latest on Y') and explicitly states when to use entity_profile instead for a static profile. It also communicates fallback behavior (GDELT preferred, GNews on rate limits) that informs usage decisions.

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

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

Annotations already indicate idempotent and non-destructive, but the description adds meaningful context: key-value scoping by identifier, persistence differences between authenticated and anonymous sessions (24-hour retention), and the storage model. These details go beyond annotations and help the agent anticipate behavior accurately.

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

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

The description is four sentences long, front-loaded with the core purpose, and every sentence provides value: when to use, storage details, and pairing. No filler or repetition.

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

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

For a simple two-parameter tool with no output schema, the description covers purpose, usage, behavior, and pairing. It is complete and self-contained, giving the agent everything needed to decide when and how to use 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% with clear parameter descriptions and examples. The description reinforces the key-value relationship and adds scoping context, which slightly exceeds the baseline. It doesn't add syntax details beyond the schema, but the key-value framing is helpful.

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: saving data for later reuse across conversations or sessions. It uses the specific verb 'save' and names the resource (data/notes), and it distinguishes itself from sibling tools by explicitly mentioning recall and forget as complementary actions.

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 ('when you discover something worth carrying forward') and names the alternatives ('Pair with recall to retrieve later, forget to delete'). This clearly separates it from reading or deletion tools and gives the agent a decision rule.

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 valuable context beyond that: auto-disambiguation for company names, internal cascading through multiple lookup endpoints, and specific citation URI formats. No contradictions with annotations.

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

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

The description is well-structured and front-loaded with user-like queries, making the purpose immediately obvious. It then clearly breaks down supported types (company, drug) with return details, all without unnecessary filler. Every sentence contributes.

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 covers what is returned for each entity type, accepted input forms, and citation URIs. It also mentions the auto-disambiguation behavior and the tool's place in the workflow, making it self-contained for an agent.

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

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

Schema description coverage is 100%, so the baseline is 3. The description repeats the input forms (ticker, CIK, name) already in the schema and adds example values, but does not introduce significant new parameter insights beyond the auto-disambiguation note.

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

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

The description clearly states the tool resolves user-spoken names to canonical identifiers, with specific examples ('ticker for', 'CIK for', 'RxCUI for'). It distinguishes itself from siblings by being the dedicated identifier-lookup tool, not just a search or 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?

Explicitly says 'Use FIRST whenever you have a name but need an ID,' providing a clear when-to-use directive. It also notes that it replaces 2-3 manual lookups, signaling it's the preferred method. Although it doesn't list when-not cases, the guidance is strong and unambiguous.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds behavioral context beyond annotations: it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. 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 three sentences, each carrying meaningful information: main purpose, how it works, and what it returns. It is front-loaded with the primary function and contains no filler or redundant wording.

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 4-parameter tool with no output schema, the description adequately explains the return format (ranked list with score, confidence, signal density) and the use context. It could additionally mention entity count constraints (2-8) but those are already in the schema, and the description sufficiently covers behavior and output.

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 reinforces the 'subject vs competitor' distinction for the entities parameter (first entry treated as subject) and mentions the shared context concept, but the schema already documents all parameter details thoroughly. The description adds minimal new semantic value beyond the schema.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, explicitly names the underlying probe tool (ai_visibility_check), and distinguishes itself by ranking and identifying most/least recognized entities. This differentiates it from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison).

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

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

The description gives a concrete use case (competitive AI-marketing audits) with an example query and clearly implies when to use it: when you want to compare multiple entities' AI visibility. It does not explicitly state when not to use it, but the context is clear enough for an AI agent to make a reasonable decision.

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 existing annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses important behavioral details: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts while the rest still returns. This adds significant context for managing expectations.

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 each sentence earns its place: purpose, use case, return structure, ecosystem limitation, and failure behavior. It is well-structured with em dashes and semicolons, front-loading the core purpose.

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 (composite of two external services) and no output schema, the description thoroughly covers return fields (summary block, per-advisory detail, links, recent versions), ecosystem scope, and potential delays. This is sufficient for an agent to understand what the tool does and what to expect.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-specific semantics beyond what the schema already provides (package name, version optional with default). It mentions version history and alternative versions, but these are about behavior, not parameter syntax.

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: it is a composite check for 'should I add this npm package to my project', fanning out across deps.dev and bundlephobia. It names specific data sources and categories (license, advisories, bundle size, tree-shake support), distinguishing it from other 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?

Provides explicit when-to-use guidance: 'Use whenever an agent asks is X safe / popular / small or what does adding lodash cost me'. It also contrasts with deps.dev:version for other ecosystems, giving an alternative.

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

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

Adds non-obvious implementation details: BGE-base-en embeddings, 500-char overlapping windows, 200K char cap with truncation flag. These complement the readOnlyHint since the operation is non-destructive and idempotent, but the description goes beyond annotations by explaining the mechanics and edge case.

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?

Multiple sentences but each carries distinct information: purpose, input/output, use case, pairing, and technical constraints. Front-loaded with the core function, no filler.

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

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

For a tool with no output schema, the description clearly states the return type: top-N passages with offsets and similarity scores. It also covers the truncation behavior and the rationale for using it. This is sufficient for an agent to invoke 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 already provides full coverage of all three parameters. The description adds useful contextual examples (e.g., 'supply-chain risk') and clarifies that text is the fetched record, but doesn't introduce new parameter meaning beyond the schema; still earns a 4 for enhancing usability.

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

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

The description clearly states it performs semantic search inside a fetched record, using examples like SEC 10-K and articles. It differentiates from sibling search tools by emphasizing it searches within a provided text rather than external sources.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and frames it as a context-saving measure. Names the complementary tool ask_pipeworx_grounded, showing when to pair with it.

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

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

Annotations already establish a read-only, idempotent, non-destructive profile. The description additionally reveals the return shape ('[{data:"dd/MM/yyyy", valor:"..."}]') and date formatting, which is critical behavior not captured in annotations or schema. 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: one main action, one common-code lookup, one return/usage note. Every sentence carries useful information; the code list is dense but directly helps invocation, and there is no filler or repetition.

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

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

For a simple fetch tool, the description covers purpose, common inputs, usage modes, and output format. It could be slightly more explicit about whether 'last' and start/end are mutually exclusive, and error behavior, but overall it provides a complete mental model given the rich schema and annotations.

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

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

Schema covers all 4 parameters, so baseline is 3. Description adds meaningful enrichment by mapping common numeric codes (432, 11, 433, etc.) to human-readable series, and clarifies that 'last' vs date range are two usage modes. This goes beyond the schema's examples.

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

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

Description begins with a precise verb and resource: 'Fetch any Banco Central do Brasil SGS time series by numeric code.' This clearly distinguishes it from siblings by naming the SGS source and numeric code access. The inclusion of common code mappings reinforces the tool's specific data domain.

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

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

The description gives explicit usage instructions: use 'last' for recent observations or a date range via start/end. It does not mention alternative sibling tools or exclusions, but the domain specificity ('any SGS time series') makes the intended use clear.

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

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

The description states 'Create a proactive monitoring subscription' and 'Returns the new subscription id,' implying each call creates a new subscription with a unique ID. This directly contradicts the idempotentHint:true annotation, which suggests repeated calls would not have additional effects. This is a significant annotation contradiction, and the description's claim of always creating a new subscription is misleading given the annotation.

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

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

The description is a single dense paragraph that front-loads the purpose, then covers requirements, types, and delivery options. It's well-structured but somewhat long and repeats delivery details that also appear in the schema (e.g., webhook signing, auto-disabled). Every sentence adds value, but the redundancy with schema descriptions prevents a perfect score.

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

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

The description is remarkably complete for a complex subscription-creation tool. It explains prerequisites (OAuth account, phone verification), return value (subscription id), all supported types with examples, delivery channels (feed, email, SMS, webhook), and important constraints (SMS cap, webhook signing secret, auto-disabled after failures). No output schema exists, but the description adequately covers what the agent needs to know to use the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds practical value by providing concrete examples for each type (e.g., sec_8k with items:['5.02'], polymarket_edge with topic:'fed', fred_series with series_id:'UNRATE') and elaborates on delivery constraints like phone verification, 10/day SMS cap, and webhook signing secret. These details go beyond the schema's brief descriptions, making parameters easier to use correctly.

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

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

The description clearly states the tool's function: 'Create a proactive monitoring subscription to a live-data event stream.' It identifies the specific resource (subscriptions), the action (create), and the nature (proactive monitoring). It also distinguishes from siblings like list_subscriptions and unsubscribe by focusing on creation.

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

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

The description provides clear context on when to use the tool, including supported subscription types and delivery channels. It mentions pulling from the feed via recent_alerts or a URL, which hints at complementary tools. However, it doesn't explicitly mention alternatives like unsubscribe when subscriptions are no longer needed, so it falls short of a perfect 5.

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

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

Annotations already establish read-only, non-destructive behavior. The description adds valuable behavioral context: it returns category-bucketed examples drawn from the live catalog, and explains the no-arg vs topic behavior. This goes beyond the structured annotations and fully 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?

The description is verbose but densely packed with useful information; it front-loads example queries and then explains behavior. Every sentence serves a purpose, though it is not as tight as a two-sentence description. Still, the length is justified for an onboarding tool.

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 one-optional-parameter tool with no output schema, the description covers purpose, usage, and response content (category-bucketed examples). It does not specify the exact response structure, but for an onboarding tool that's acceptable and not a significant gap.

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

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

Schema coverage is 100% for the single optional `topic` parameter, listing all valid values. The description restates examples but does not add new syntax or meaning beyond what the schema already provides. Baseline 3 is appropriate because the schema already handles parameter semantics well.

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 the onboarding entry point that returns category-bucketed example questions with exact tool + argument shapes. It distinguishes from siblings by saying 'Use this FIRST' and listing specific categories, making the purpose 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?

It explicitly says to use this FIRST when you don't know what Pipeworx can do, and to learn meta-tools. It gives clear context on when to use (no-arg vs topic), but does not formally contrast with discover_tools or other similar exploration tools or state when not to use it.

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

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

Annotations declare it as a mutation, idempotent, and non-destructive. The description adds critical context about ownership (only your own subscriptions) and deactivation vs deletion, plus historical data availability via recent_alerts. This exceeds what annotations provide.

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

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

Three sentences, front-loaded with the action, and each sentence provides distinct information: what it does, the ownership constraint, and the side effect. 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?

For a simple one-parameter mutation tool with no output schema, the description is thorough. It covers the action, ownership, deactivation behavior, and historical data availability, making it sufficient for an agent to use correctly.

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

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

The single parameter id is fully documented in the schema with 'Subscription id (uuid) returned by subscribe.' The description only references 'by id' and adds no new meaning beyond the schema, so the baseline 3 for high schema coverage applies.

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

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

The description clearly states 'Cancel a subscription by id' – a specific verb and resource. It distinguishes from sibling tools like subscribe (create) and list_subscriptions (list) by the cancel action.

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 when to use it (when you want to stop an alert subscription). It adds ownership enforcement and deactivation behavior, which helps differentiate from a permanent delete. However, it does not explicitly name alternative tools or provide 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 the annotations (readOnly, openWorld, idempotent), the description discloses significant behavioral detail: the structured SEC EDGAR + XBRL path for financial claims, the grounded pipeline for other claims, the exact percent-delta math, the verdict set, and the inclusion of citations and reasoning. This far exceeds the annotation baseline.

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 not unnecessarily verbose for the tool's complexity. It opens with trigger phrases, then delivers a clear purpose, examples, and routing details. While slightly long, each sentence provides useful information, though it could be more front-loaded with a direct statement of purpose.

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

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

The description is highly complete given no output schema: it explains the purpose, usage, behavior, return values (verdict types, citation, reasoning), and performance benefit. It covers both routing paths and edge cases like 'unsupported' verdicts, making the tool well-understood.

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 thorough descriptions for both 'claim' and 'tolerance_pct'. The description adds no extra parameter semantics beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function with specific verbs like 'fact check', 'verify', and 'confirm or refute'. It distinctly identifies the resource as natural-language factual claims and differentiates from siblings by noting it replaces 4-6 sequential calls, making its consolidated purpose obvious.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' providing a clear usage context. It also differentiates between company-financial claims and other claims internally but does not name alternative tools or give explicit when-not scenarios, 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.