Anapioficeandfire

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

The description adds valuable context beyond the readOnlyHint/openWorldHint/idempotentHint annotations by specifying the default model (Workers AI Llama-3.3-70b, free), the BYO-key cost implication for Anthropic, and the return structure (per-model {score, confidence, signals, raw_response} + combined view). This helps the agent anticipate cost and output shape. It doesn't discuss rate limits or error cases, so it's strong but not maximal.

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, tightly packed with the essential API behavior: what it does, default vs. optional model, return shape, and typical use cases. There is no filler or redundant repetition of schema details, making it easy to scan and immediately act on.

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 moderate complexity (4 params, no output schema), the description provides a complete mental model: one required entity param, optional models/key/context, and a clear return shape. It also states the practical purpose, covering both invocation and interpretation. Missing details like enum values or error handling are not necessary because the schema already covers constraints.

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

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

The schema already documents all 4 parameters with clear descriptions, achieving 100% coverage, so the description doesn't need to repeat them. The description adds a small hint about _apiKey ('BYO key') and the default model, but the schema already captures the key semantics (e.g., _apiKey 'only needed if anthropic is in models'). Thus, the description contributes marginal additional meaning beyond the schema, which is the baseline for full 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 uses a specific verb+resource: 'Probe one or more LLMs for what they know' and explicitly defines the output as a visibility score (0-100). This clearly distinguishes it from sibling tools like ask_pipeworx (likely conversational Q&A) and deep_research by focusing on scoring business/brand visibility rather than general Q&A 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?

The description provides explicit use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains when to use the default Workers AI model versus passing `_apiKey` to probe Anthropic, giving clear context on model selection. However, it does not explicitly name alternative tools or state when NOT to use this tool, so it lacks direct 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?

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses routing behavior, argument-filling, citation URIs, per-tier availability, and fast single-call execution. It also explains that it routes to live news. All of this adds valuable context without contradicting 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 each sentence earns its place: preference directive, routing mechanism, trigger phrases, examples, step-up alternatives, and news coverage. It is well-structured and front-loaded, though slightly wordier than strictly necessary.

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

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

Despite no output schema, the description explains return values ('structured answer with stable pipeworx:// citation URIs') and covers a wide range of use cases, examples, and precise fallback routes. The tool's complexity (routing to thousands of sources) is handled comprehensively 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 baseline is 3. The description includes several example questions and trigger phrases, but does not add new parameter-level semantics beyond the schema's 'Alias for question' definitions. It confirms the natural-language nature of the parameter but doesn't need to compensate for 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 states the tool's core action: 'Routes the question to the right one of 5,462 tools across 1419 verified sources, fills arguments, returns the structured answer with stable pipeworx:// citation URIs.' It also explicitly positions it as the default entry point for factual queries, distinguishing it from siblings like ask_pipeworx_grounded and deep_research.

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

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

The description provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH' and 'START HERE for most questions.' It also names specific alternatives with their use cases: ask_pipeworx_grounded for hallucination-resistant answers and deep_research for broad/multi-part questions, plus examples of suitable queries.

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

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

While annotations already declare read-only, idempotent, and non-destructive, the description adds significant context: the beta status, the current inactive candidate state, the identical behavior to ask_pipeworx at present, and the fact that responses are compared against the stable router. It also explicitly says 'Falls back to nothing — this IS a full working router,' preventing confusion about availability. This goes beyond annotations to explain the experimental nature.

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

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

The description is a single coherent paragraph that front-loads the core identity and then explains the experimental state and usage. It is a bit long but each clause adds value: the tool count, the current status, and the fallback assurance. It could be tightened slightly, but it remains efficient for the complexity involved.

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 provides key context about being a beta universal router, the current matching behavior, and the comparison against the stable router. It does not explain the return shape, but it explicitly says 'same response shape' as ask_pipeworx, which is sufficient given the tool's nature. With rich annotations and no output schema, this is reasonably 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 covers all parameters with 100% coverage, including the main 'question' field and five aliases. The description adds no extra parameter-level detail beyond saying 'same arguments as ask_pipeworx,' which is useful but not necessary given the schema's thoroughness. Baseline of 3 is appropriate because the schema does the heavy lifting.

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

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

The description clearly identifies this as a beta version of ask_pipeworx, a universal router that handles natural-language questions by routing to 5,462 tools. It distinguishes itself from the stable ask_pipeworx by being the experimental edge with candidate routing improvements. The verb 'ask' and resource 'pipeworx' are clear.

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

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

Explicitly states to use this tool 'exactly like ask_pipeworx when you want the newest routing,' and notes that results are compared against the stable router to decide merges. It also clarifies that when no candidate is active, it matches ask_pipeworx exactly, giving the agent a clear decision framework. Does not need to mention alternatives beyond ask_pipeworx because that is the direct counterpart.

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 readOnlyHint and idempotentHint annotations, the description discloses critical behaviors: it routes through the same mechanism as ask_pipeworx, extracts only from tool results, returns a structured response with evidence and refusal reasons, and explicitly lists possible refusal_reason values. It also mentions the extra LLM call cost. No annotation contradictions.

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

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

The description is dense but well-structured, front-loading the core purpose and then logically covering routing, return format, usage guidance, and cost. Each sentence delivers essential information without redundancy, making it appropriately sized for a tool with this complexity.

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

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

Despite having no output schema, the description fully specifies the return shape on both success and refusal, lists refusal reasons, explains the routing behavior, and gives usage context. Combined with the exhaustive schema and annotations, the agent has all necessary information to select and invoke the tool correctly.

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

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

The input schema has 100% coverage, documenting the 'question' parameter and its aliases (q, text, input, query, prompt) with descriptions. The description adds general context about filling arguments but does not provide any parameter-specific meaning beyond what the schema already states. The baseline of 3 is appropriate given the fully described schema.

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

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

The description clearly states the tool's purpose: a hallucination-resistant answer mode that extracts answers using ONLY the tool result content. It distinguishes from the sibling ask_pipeworx by emphasizing grounded extraction and explicit refusal behavior, making its unique value proposition evident.

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 guidance ('whenever an answer will be quoted, cited, or acted on...') and when to avoid it ('prefer ask_pipeworx for casual lookups'). It directly names the alternative and explains the cost trade-off (one extra LLM call), giving clear decision criteria.

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

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

The description extensively discloses behavior beyond annotations: it explains low-confidence short-circuiting, closed-market handling, wide-spread tradeability flags, news fallback mechanisms, cancellation-rule risk, and resolver match confidence. These are non-obvious behaviors that significantly affect how an agent should interpret results and size bets. 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 extremely well-structured with clear section labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY, etc.). The core purpose and usage are front-loaded in the first two sentences. While dense, each section adds necessary detail for a complex tool; only minimal redundancy exists.

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

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

Given the tool's complexity (multiple classifiers, fan-out behaviors, response shapes, safety mechanisms) and the absence of an output schema, the description is remarkably complete. It covers return values, edge cases, safety guards, and even resolution-rule risk. An agent could invoke this tool confidently with no additional documentation.

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

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

Despite full schema coverage, the description adds substantial semantic value for each parameter: market acceptance of slug/URL/question text, depth behavior (quick vs thorough fan-out), and include_raw size trade-offs. It also provides concrete fan-out examples that clarify what each parameter controls. This goes far beyond the schema's descriptions.

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

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

The description states a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes from siblings like polymarket_edges or polymarket_arbitrage by focusing on per-market data fan-out and evidence collection. The one-line purpose is immediately clear and actionable.

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 for' scenarios ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and includes usage-critical warnings (e.g., inspect resolver contract before trusting analysis). However, it does not explicitly name alternative tools or provide 'when-not-to-use' exclusions, so it falls just short of a full 5.

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

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

Annotations already disclose read-only, idempotent, and non-destructive behavior. The description adds no extra behavioral context such as what happens if the book is not found or whether related data is included. It is consistent with annotations but does not enrich 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 a single, concise phrase that directly states the tool's function. Every word earns its place, and the structure is 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?

Given the simple one-parameter design, safety annotations, and presence of an output schema, the description is sufficient. However, it does not explicitly contrast with the sibling 'books' tool or mention behavior for invalid ids, so it is slightly under-specified.

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 only parameter 'id' is referenced in the description and the schema includes an example. However, with 0% schema description coverage, the description could have been more explicit about the id's origin or constraints. The meaning is inferable from 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 'Single book by id' clearly states the tool fetches one book by its identifier. This distinguishes it from the sibling 'books' tool, which likely handles multiple books.

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

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

The description implies usage for fetching a single book by id but does not explicitly state when to prefer this over the 'books' tool or mention alternatives. It lacks clear when-to-use or when-not-to-use guidance.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds value by clarifying the return fields (ISBN, authors, publisher, pages, character lists) and the filtering capabilities, which are not explicitly covered by 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?

The description is a single, information-dense sentence that front-loads the purpose, lists all key parameters and return fields, and avoids waste. It is appropriately sized for the tool's complexity.

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

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

Given the presence of an output schema and comprehensive annotations, the description covers the core functionality, filters, pagination, and return values. It does not mention defaults or ordering, but these are minor given the output schema provides structural details.

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

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

With 0% schema description coverage, the description fully compensates by explaining each parameter's role: name for filtering by book name, fromReleaseDate/toReleaseDate for date range, and page/pageSize for pagination. It adds meaning to all 5 parameters, though it could specify formats or combination semantics.

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

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

The description clearly states the tool's purpose: to search and list A Song of Ice and Fire books. It distinguishes the multi-result listing tool from the singular 'book' sibling by emphasizing filtering and pagination, making the scope specific.

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

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

The description implies usage through its search/list phrasing but provides no explicit guidance on when to use this tool versus alternatives like the singular 'book' tool. It lacks exclusions or direct references to sibling tools, leaving usage inference to the agent.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds no additional behavioral context such as not-found behavior or response format, which is acceptable for a simple read operation but does not elevate beyond the 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?

'Single character by id' is exceptionally concise, using only seven words with no filler or redundancy. It is front-loaded, immediately conveying 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?

The tool is a simple single-parameter lookup with a full output schema and strong annotations. The minimal description is sufficient for an agent to understand the core function. It does not address not-found behavior or selection guidance versus 'characters', but these are not critical given the output schema and sibling context.

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

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

Schema description coverage is 0%, so the description must compensate. It does mention 'by id', tying the sole parameter to its purpose, but adds no detail beyond the parameter name and type already present in the schema. For a single obvious 'id' parameter, this meets the minimum but does not enrich understanding.

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

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

The description 'Single character by id' clearly indicates a lookup of a single entity by identifier, and the contrast with the sibling 'characters' (plural) helps distinguish it as a singular resource accessor. However, it lacks an explicit verb like 'get' or 'fetch', so it is not maximally explicit.

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

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

No explicit when-to-use or alternative guidance is provided. The phrase 'by id' implies use when a specific character ID is known, and the sibling 'characters' suggests the plural alternative, but this is implicit rather than directly stated.

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 openWorldHint=true, and the description does not contradict them. It adds value by mentioning return fields (aliases, titles, house affiliations, appearances) but does not disclose other behavioral aspects like pagination limits, default ordering, or filtering nuances (e.g., exact vs partial matches).

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 sentence, front-loaded with the action and resource, and every part contributes meaning. It is concise without wasting words on irrelevant details.

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

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

Given the tool has 8 parameters, 0 required, and an output schema, the description covers the core purpose and main filters. However, it leaves out essential context like pagination (page/pageSize), which is critical for a list endpoint, and the ambiguous 'birth/death descriptor' could mislead users. The output schema likely covers return values, but the input semantics remain incomplete.

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 0%, so the description must compensate. It lists filterable attributes (name, culture, birth/death descriptor, gender, alive status) but does not explain parameter formats (e.g., what 'birth/death descriptor' means, whether 'gender' requires exact casing), nor does it mention pagination parameters (page, pageSize). This gives a general sense but leaves ambiguity.

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

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

The description clearly states the tool's purpose with a specific verb ('Search and list') and resource ('ASOIAF characters'), and distinguishes it from sibling tools like 'character', 'house', and 'book' by indicating it handles character lists and 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 implies when to use the tool (searching/filtering characters) but does not explicitly mention alternatives or exclusions. It provides clear context but lacks guidance such as 'use character for single entity details' or 'use book for book-specific queries'.

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

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

The description goes well beyond the annotations (readOnly, idempotent, openWorld) by disclosing data provenance (SEC EDGAR/XBRL, FAERS, FDA), handling of off-calendar fiscal years (AAPL Sep, NVDA Jan), sorting by primary metric, and return format (paired data + pipeworx:// citation URIs). It also highlights parallel execution ('ONE parallel call'), providing useful behavioral context without contradicting any 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?

Although longer than minimal, every sentence earns its place: trigger examples, core function, preference instruction, type-specific data, sorting behavior, and return format. It is front-loaded with user intents (quotes/patterns) and structured logically, avoiding filler. The density is high yet clear, making it an appropriate and well-organized description.

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

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

Given there is no output schema, the description sufficiently explains return values ('paired data + pipeworx:// citation URIs') and output ordering ('sorted by primary metric'). It covers both entity types with their respective metrics, addresses an edge case (off-calendar fiscal years), and even notes efficiency gains. For a tool with two parameters and no nested objects, this level of completeness is more than adequate.

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

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

The schema already covers 100% of parameters with descriptions and examples, setting a baseline of 3. The description adds significant meaning by explaining how the 'type' parameter determines the data pulled (10-K metrics vs adverse-event/trial counts) and clarifies that 'values' are tickers/CIKs for companies or drug names. This supplementary context enhances the agent's understanding of what the parameter values represent and how they affect the output.

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 precisely states the tool performs side-by-side comparisons of 2–5 companies or drugs in ONE parallel call, with specific trigger phrases like 'Compare X and Y' and 'heads to head.' It clearly distinguishes this from sibling tools by emphasizing parallel execution and specific data sources (SEC EDGAR for companies, FAERS/FDA for drugs). The verb 'compare' is explicit and the resource scope is fully defined.

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 commands: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing a clear directive on when to use this tool. It also enumerates trigger examples ('which is bigger', 'rank these companies') and states it replaces 8–15 sequential lookups, which informs selection. Although it doesn't name a specific alternative for single entities, the condition 'when comparing entities' inherently covers the exclusion.

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

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

The description adds substantial behavioral context beyond the readOnly/idempotent annotations: account requirements, parallel decomposition into facets, return packet structure (verbatim evidence, confidence, source, fetched_at, citation), gaps[] for unanswered facets, contradictions[] scan, semantic excerpting rather than head-truncation, and expected latency. 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 long but every sentence earns its place for a complex tool with no output schema. It is front-loaded with the most critical info (account requirement, alternative if not signed in, and the 'NOT open-web search' clarification), then flows logically through use cases, limitations, depth semantics, and return details. The density is justified by the tool's complexity.

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

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

With no output schema, the description fully explains the return value: findings packet with verbatim evidence, confidence, source, fetched_at, stable pipeworx:// citation, gaps[], contradictions[], hop field, and citation_uri. It also covers performance expectations, access tiers, and edge cases like breaking news returning empty gaps, making the description complete for an agent to 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?

Although schema coverage is 100%, the description adds meaningful semantics to both params: 'question' is explained as accepting broad/multi-part natural language with decomposition as the point, and 'depth' is elaborated with the exact facet counts, hop behavior, gap recovery, contradictions scan, and the paid-plan restriction for 'thorough'. This goes well 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 states a specific verb+resource+scope: 'Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources... in ONE call'. It clearly distinguishes from siblings by noting it is NOT open-web search and explicitly contrasts with ask_pipeworx for single lookups, making its purpose unmistakable.

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

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

Provides explicit when-to-use and when-not-to-use guidance: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also gives access prerequisites (sign in, paid plan for thorough) and an alternative fallback (use ask_pipeworx if not signed in), offering comprehensive usage context.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds useful behavioral context about the return format: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and 'no second schema lookup needed.' This goes beyond the annotations and helps the agent know what to expect.

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 slightly long due to the domain list, but the first sentence is a clear front-loaded purpose. Each sentence adds unique value: usage context, return details, and a prioritization cue. The structure is logical, and the length is justified by the need to enumerate supported areas.

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

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

Despite no output schema, the description explains what the tool returns (names, descriptions, schemas, examples) and when to use it. It covers the core usage scenario ('Call this FIRST...') and the input requirement ('describing the data or task'). It does not mention the limit parameter's default or max, but that is minor.

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 provides 100% coverage with descriptions for all parameters, including aliases for 'query.' The description does not add additional meaning beyond what the schema already offers, though it does mention 'top-N' which indirectly relates to the 'limit' parameter. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It identifies a specific verb (find) and resource (tools), and differentiates itself from siblings by focusing on discovery rather than direct execution. The scope is further clarified with a list of domains, making it 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 when to use: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' While it doesn't list explicit alternative tools, the 'not just one answer' phrase implies you should use it for exploration rather than direct single-answer tasks.

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 valuable behavioral context beyond this: it fans out across multiple sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), returns a specific list of fields, soft-fails on patents due to API sunset, and uses a GDELT→GNews fallback. It also notes the 'parallel call' execution model and the 'zero-padded CIK' requirement, which are not inferable from 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 densely packed with useful information: usage examples, execution model, data sources, return fields, fallback behavior, and input constraints. It is front-loaded with examples and then systematically catalogs outputs. While the multiple example queries are somewhat redundant, they collectively help pattern-matching. It earns a 4 rather than 5 mainly due to the verbosity that 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?

There is no output schema, so the description must explain return values. It does this thoroughly: lists cik, company_name, recent_filings (with URI format), fundamentals (specific metrics and sort order), patents (with sunset warning), news (with fallback), and LEI. It also addresses the key limitation (names not supported) and directs to resolve_entity. Given the tool's complexity, the description is fully sufficient for an agent to select and invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful extra semantics: it provides concrete examples ('AAPL', '0000320193'), clarifies the zero-padded CIK format, and explicitly excludes natural-language names. It also gives context that only 'company' is supported today, which matches the schema enum but is reinforced with 'person/place coming soon.'

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 ('profile') and resource ('US public company'), with clear examples ('Tell me about X', 'research Acme'). It distinguishes from siblings by specifying it returns a full cross-source profile in one call and explicitly states preference over chaining single-pack lookups. The scope (US public companies) and key output fields are clearly enumerated.

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

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

The description explicitly states when to use: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also provides an alternative: 'names not supported (use resolve_entity first if you only have a name).' This gives clear when/when-not guidance with an alternative tool.

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

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

Annotations already disclose destructive and idempotent behavior, and the description reinforces this by saying 'delete'. It adds context about when deletion is appropriate (clear sensitive data) and implies it only affects previously stored memories. It doesn't mention error behavior for nonexistent keys, but given annotation coverage, the added context is sufficient.

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, action-oriented, and front-loaded with the core purpose. Every word adds value, with no redundancy or fluff.

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

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

For a simple one-parameter tool, the description covers purpose, usage, and complementary tools. The schema fully documents the parameter, annotations provide safety and idempotency information, and an output schema is not necessary. The description is 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 describes the 'key' parameter as 'Memory key to delete', achieving 100% coverage. The description does not add further detail about key format or constraints, so it provides no additional 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's function: 'Delete a previously stored memory by key.' It uses a specific verb and resource, and distinguishes itself from sibling memory tools like 'remember' (store) and 'recall' (retrieve).

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 provides usage conditions: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also suggests pairing with 'remember' and 'recall', giving clear guidance on when to use this tool versus alternatives.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive. The description adds behavioral context beyond that: the steps of fetching the page, extracting fields, and producing a single text blob. It doesn't mention edge cases or rate limits, but given annotations, the added context is sufficient.

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

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

The description is compact and well-structured: first sentence states the core function, second explains the process and output, third lists use cases. No unnecessary words, and critical information is front-loaded.

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

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

With only 2 parameters and no output schema, the description covers everything needed: what it does, how it works, what the output looks like ('single text blob'), and typical use cases. The tool is simple, and the description is fully adequate.

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

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

Schema description coverage is 100%—both 'url' and 'max_links' have clear descriptions. The tool description does not add additional meaning beyond the schema, but with full schema coverage, 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 verb 'Generate' and the resource 'llms.txt file for any URL', then details what it does: fetches page, extracts title/description/key links, and emits standard markdown. This distinguishes it from siblings like scan_competitor_ai_presence by focusing on producing a file rather than just analyzing presence.

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

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

Provides concrete use cases: getting a client's site indexed, drafting your own llms.txt, and auditing a competitor's AI visibility. These imply when to use, though it doesn't explicitly name alternative tools or state when not to use, which would make it 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, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. However, the description adds no extra behavioral context such as what happens for a missing ID or how the response is structured. The description provides no value 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 extremely concise, consisting of a single short phrase with no filler. It is front-loaded and to the point, though it borders on under-specification for a novice agent.

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 single-parameter read tool with an output schema and rich annotations, this description is adequate but minimal. It doesn't explain the domain meaning of 'house' or edge cases like non-existent IDs, but the output schema covers the return 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?

With 0% schema_description_coverage, the description must compensate. 'by id' clarifies that the 'id' parameter is the lookup key, adding semantic meaning beyond the schema's bare type definition. However, it doesn't explain constraints, format, or domain meaning beyond that.

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?

Despite lacking an explicit verb, 'Single house by id' clearly identifies the resource (house) and the selection criterion (id), distinguishing it from the sibling 'houses' which likely lists all houses. It could be improved with a verb like 'get' or 'retrieve'.

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 no guidance on when to use this tool versus alternatives such as 'houses' or other entity tools. There are no mentions of context, alternatives, or exclusions.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior, so safety is covered. However, the description itself adds no behavioral context beyond saying 'Search/list houses'—no mention of pagination, result shape, or filtering behavior, which is a gap.

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

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

The description is extremely short, but it is under-specified for a tool with 9 parameters and no parameter documentation. It is not appropriately sized because it omits essential detail, making it concise at the expense of usefulness.

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

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

Given the tool's complexity (9 optional parameters, existing output schema, and sibling tools), the description is wholly inadequate. It does not explain search criteria, pagination, default behavior, or how this tool relates to singular 'house' or other entity tools, so the agent cannot 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?

With 9 parameters and 0% schema description coverage, the description should explain what each parameter means and how they combine, but it provides nothing. The schema only lists types, so the agent has no semantic understanding of 'name', 'words', 'region', or the boolean flags.

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

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

The description clearly states the action (search/list) and resource (houses). It is understandable but does not differentiate this tool from the singular 'house' sibling tool or other list tools, so it lacks sibling differentiation.

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

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

No guidance is provided on when to use this tool versus the singular 'house' tool or other entity list tools. It does not mention any use cases, filters, or exclusions, leaving the agent without decision context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable context beyond annotations by enumerating returned fields (id, type, params, created_at, last_fired_at, fire_count) and clarifying that only active subscriptions are returned by default. This exceeds the baseline expected given 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?

Two sentences, front-loaded with the action, and every sentence earns its place. The first states purpose and output, the second states when to use it. No fluff.

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

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

Despite no output schema, the description lists all return fields and the optional parameter. Complexity is low (one optional param), and the usage guidance covers when to use it. The tool is simple enough that this description is complete without additional details.

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

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

Schema coverage is 100% for the single optional parameter include_inactive, so the baseline is 3. The description does not add extra meaning beyond the schema; it only implies the default behavior ('active') which is already in the schema description. No additional semantic value is provided.

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, using a specific verb and resource. It distinguishes from sibling tools like subscribe and unsubscribe by focusing on listing existing subscriptions, and the phrase 'before adding more' explicitly ties it to the subscription lifecycle.

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 to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent exactly when to use this tool and implies alternatives (subscribe/unsubscribe).

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 sparse annotations, the description discloses the claim_token workflow, daily digest review, roadmap impact, per-identifier rate limit, and that it is free/non-quota. These are non-obvious behavioral traits an agent needs to know, and nothing contradicts the annotations.

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

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

The description is front-loaded with the core purpose and uses subsequent sentences for critical usage constraints and token mechanics. It is long (~160 words) but dense; every sentence earns its place for a tool with an unusual claim-token follow-up flow.

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 compensates by explaining what the tool returns (claim_token), how to read the resolution later, rate limits, and scope restrictions. It is complete enough for an agent to decide when and how to invoke it correctly.

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

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

Schema coverage is 100%, but the description adds genuine value by mapping type values to use cases, explaining the claim_token round-trip with an example call, and advising on message content (don't paste the end-user's prompt). It stops short of clarifying whether type/message are semantically required despite the schema listing no required 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 clearly states the resource ('Pipeworx team') and the action ('Tell ... something is broken, missing, or needs to exist'), followed by concrete categories (bug, feature, data_gap, praise). This distinguishes it from sibling Q&A, discovery, and data 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?

It gives explicit when-to-use conditions for each feedback type, names the exclusion ('ONLY for tools served by this Pipeworx connection'), and instructs filing with an alternative server for non-Pipeworx tools. It even offers a disambiguation rule: 'Pipeworx tool names are the ones this connection lists.'

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 data provenance ('derived from CF analytics-engine'), privacy specifics ('no PII'), caching behavior ('Cached 5min-1h'), and aggregate output ('just (pack, tool, count)'). These go beyond the annotations, which only state read-only/idempotent/non-destructive.

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 structured with a strong opening sentence, followed by specifics and a compact bulleted use-case list. It is moderately sized but every sentence carries information; no filler. Slightly verbose with the use-case enumeration, but acceptable.

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 single-parameter read-only tool with no output schema, the description covers the return payload, caching, data source, and privacy, plus usage guidance. This is sufficient for an agent to select and call the tool correctly.

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

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

The schema already documents the window parameter with full coverage, including default and temporal semantics. The description merely repeats the window options without adding new parameter-specific meaning, so it does not significantly augment the schema.

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

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

The description clearly states the tool's function with a specific verb ('Returns') and resource ('top tools, top packs, and total call volume'), and distinguishes it from sibling tools by focusing on what other AI agents are calling. It answers the 'what' and 'scope' effectively.

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 ('Useful for: discovering... confirming... seeing...'), which gives clear context for when to use the tool. It does not explicitly name alternatives or exclusion conditions, but the scenarios are actionable.

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

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

Beyond the readOnly/idempotent annotations, the description discloses critical behavioral traits: fill-check pricing against live CLOB depth, realizable vs theoretical edge, thin_legs reporting, placeholder filtering, Jaccard similarity threshold, and the explicit warning 'do not trade it' when realizable_edge_pp ≤ 0. This is rich context that annotations alone would not provide, with no contradiction.

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

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

The description is long but every sentence earns its place. It is front-loaded with a clear summary, then uses labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) to organize complex behaviors. No redundant filler; the structure aids navigation.

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 details the response structure (opportunities[] with fields, partition_check fields), explains edge cases like skipped_low_similarity and placeholder fractions, and provides operational guardrails. It is fully complete given the tool's complexity and lack of a structured output definition.

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 event and topic, the description adds substantial meaning: concrete slug examples ('fed-decision-may-2026'), the behavior of walking child markets, the partition_check computation, and how topic mode searches related events. It also clarifies that passing no arguments triggers trending_scan, which the schema doesn't convey.

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+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes from sibling tools by detailing three modes (trending_scan, event, topic) and explicitly references polymarket_fill_risk for custom sizing, leaving no ambiguity about what this tool does.

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 guidance for each invocation pattern: no args for a trending scan, event mode for a specific market (recommended), and topic mode for cross-event scanning. It even states when cross-event mode is superior and instructs users to use polymarket_fill_risk for custom sizing, making alternatives 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 goes far beyond the annotations, disclosing caching behavior ('Cached 1h at the KV level'), the 24h-move warning ('your edge may already be in the price'), why Fed bets are excluded, the rarity of concentrated longshots, and the presence of diagnostics for empty segments. No contradiction with annotations exists; instead, it enriches the read-only, open-world, idempotent, non-destructive profile with actionable details.

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

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

The description is extremely long and dense, delving into model-specific details (e.g., FRED log-returns, GDELT ratios, per-sport α values) that are likely unnecessary for tool selection. While it is structured with clear all-caps sections, it reads like full documentation rather than a concise tool descriptor, making it less efficient for an agent to quickly parse.

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 carries the full burden of explaining return values. It thoroughly details the top-level response structure (by_segment, fed_candidates, _diagnostics), the fields in each opportunity (edge_pp_net, kelly_fraction, market.liquidity, etc.), and the logic for why segments might be empty (funnel counters). This is comprehensive enough for an agent to understand the tool's behavior.

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

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

Although schema coverage is 100%, the description adds significant meaning beyond the schema by explaining the rationale behind knobs like min_partition_leg_kelly (why it exists because partition arbs return kelly_fraction_half=0) and min_liquidity/max_spread_pp as 'tradeable-edge filters'. It also gives concrete examples ('Set to 2...') that help an agent understand the practical impact of each parameter.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This is a specific verb+resource combination, and the 'Built for what should I bet on today' phrase establishes a distinct use case, differentiating it from siblings like polymarket_arbitrage or polymarket_edge_tracker.

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

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

The description provides clear context for when to use the tool ('what should I bet on today') and gives practical guidance for parameter knobs (e.g., 'Set to 2 to require tight books', 'Set to 5000 to drop thin-book opportunities'). However, it does not explicitly mention alternative tools or when not to use this tool, 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 readOnly, idempotent, and non-destructive behavior. The description adds substantial behavioral detail: how snapshots are generated (cache-miss), response structure (tracked[], expired[], snapshot_dates[]), computation specifics (decay on |edge_pp_net|, signed values), and limitations (60-day TTL, daily closes not intraday). This goes far 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?

Despite being long, every sentence earns its place: purpose, args, response format, and limits are all essential. The structure is logical and front-loaded with the core concept. It's dense but not wasteful.

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

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

There is no output schema, so the description compensates by thoroughly explaining the return structure (tracked, expired, snapshot_dates) and their meanings. It also covers edge cases (snapshot gaps, TTL, decay computation). For a tool with 2 simple params, this is complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds minimal extra meaning: it restates days as lookback and window as snapshot family, but the schema already provides these details. It does note default/max values, but the schema's 'clamp 2-30' is even more precise. No significant value beyond schema.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question ('how long has this edge existed and is it shrinking?') and distinguishes itself from siblings like polymarket_edges by focusing on persistence/decay rather than current edges.

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

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

The description provides clear context on when to use the tool (when edge age and decay matter, as opposed to fresh edges) and explains the significance ('a fresh wide edge and a 3-week-old wide edge are different trades'). It doesn't explicitly name alternatives or exclusions, so it falls short of a 5, but the implied usage is strong.

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, but the description goes far beyond. It discloses that the tool 'walks the ladder,' returns detailed fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd), and exposes risks like 'forced_directional_risk naming the legs most likely to strand you unhedged.' No contradiction with annotations.

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

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

Though lengthy, the description is well-structured with capitalized markers (SINGLE-MARKET, BASKET) and every sentence adds value. It front-loads the core purpose, then details modes, return fields, and usage rules. No fluff or redundancy.

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

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

For a complex tool with two modes and no output schema, the description is exceptionally complete. It explains both modes, listed return values, edge cases (thin_legs, partial fills), risk disclosure, and explicit usage context relative to sibling tools. The agent is fully equipped to decide when and how to invoke this tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds valuable context beyond the schema: it clarifies the 'REQUIRES one of market or event' constraint (not in schema's required list), explains the default auto side behavior in basket mode, and gives practical meaning to size_usd ('max spend on buys, target proceeds on sells' and 'settlement notional' in basket). This extra orientation earns a 4, though the schema already carries most detail.

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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes from siblings by focusing on fill risk, explicitly naming polymarket_arbitrage and polymarket_edges as related tools, and details two distinct modes (single-market and basket/partition).

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

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

Usage guidance is explicit and actionable: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why (theoretical overround on thin books is not capturable, partial basket fills create unhedged directional risk) and contrasts the two modes with clear conditions for each.

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 (readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false) already establish safety. The description adds substantial behavioral context: compatibility_warning conditions, temporal_alignment semantics, skipped_cross_type/subtype counters, and the note that the tool explicitly signals when bet shapes are non-equivalent. This goes far beyond the annotations and addresses edge cases that an agent must know.

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 labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS). It front-loads the core purpose. Each sentence adds value, though some could be trimmed (e.g., the final caveat could be shorter) without losing essential information. The density is acceptable given 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 explains return values: leg-by-leg prices, spread[].top_spreads_pp, compatibility_warning, temporal_alignment, and skipped counters. It also covers edge cases like non-equivalent bet shapes and temporal misalignment, ensuring an agent understands what results to expect and how to interpret them. Nothing critical is missing.

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

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

While schema coverage is 100% with parameter descriptions, the description enriches each parameter: it explains that 'topic' is a shortcut auto-fetching events, and that kalshi_event_ticker and polymarket_event_slug override the topic-mapped sides. It gives examples ('fed', 'KXFED-26OCT') and clarifies the relationship between parameters, adding meaning well beyond the schema.

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

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

The description clearly states the tool computes a 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It uses specific verbs ('spread', 'auto-fetch', 'compare') and scope, distinguishing it from siblings like polymarket_arbitrage which likely target intra-venue opportunities. The two modes also clarify the exact resources involved.

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 explains when to use each mode: 'topic' for pre-mapped macro shortcuts and explicit ticker/slug for custom pairings. It also warns that most pre-mapped topics return compatibility_warning today and that 'pre-mapped ≠ tradeable,' guiding appropriate use. It does not explicitly name alternative sibling tools but provides clear context for when this tool is relevant.

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, such as scoping to the user's identifier and the ability to list all keys by omitting the argument, which is not evident from annotations alone.

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

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

The description is concise and well-structured, with three sentences each earning their place: clear action, usage context, and scoping/pairing information. It is front-loaded and avoids redundancy with the schema.

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, a single optional parameter, full schema coverage, and strong annotations, the description is complete. It explains both retrieval and listing modes, usage context, and scope, leaving no critical gaps for an agent to select and invoke the tool correctly.

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

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

The schema already covers the parameter ('key') with 100% coverage. The description adds meaning by providing concrete examples of stored context (ticker, address, research notes) and explaining scoping to the agent's identifier, enriching the semantics beyond 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's purpose: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It uses specific verbs and resources, and distinguishes itself from siblings by explicitly referencing '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?

Provides explicit guidance on when to use the tool: 'Use to look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch.' It also mentions pairing with 'remember' to save and 'forget' to delete, implicitly noting 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 description says 'Set mark_read:true to flag returned events read so the next call only shows newer ones,' which describes a state-changing side effect. This directly contradicts the readOnlyHint: true annotation, which implies no writes. The contradiction is severe, requiring a score of 1.

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

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

The description is compact yet comprehensive, covering purpose, return fields, filtering, the mark_read side effect, and an alternative access method in five sentences. Each sentence earns its place, with the core purpose front-loaded.

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

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

With no output schema, the description usefully lists the return fields (source, citation_uri, raw payload) and explains pagination-like behavior via mark_read. It also mentions the HTTP fallback. It could mention unread_only and limit defaults, but the schema covers those, making this quite 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?

Although the schema already covers 100% of parameters, the description adds meaningful context by giving a concrete type example ('sec_8k') and explaining the behavioral effect of mark_read. This goes beyond simple schema descriptions and helps the agent use parameters correctly.

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

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

The description opens with 'Pull fired events from your subscription feed' and clarifies it returns the most recent alerts with source, citation_uri, and raw payload. This clearly distinguishes it from siblings like list_subscriptions and recent_changes by focusing on alerts from the evaluator's feed.

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

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

The description explains filtering by type and since, mentions that polling works fine, and provides an alternative endpoint for scripts/dashboards. It lacks explicit 'when not to use' compared to siblings, but the polling and alternative URL provide practical 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?

Despite annotations already indicating read-only, open-world, and idempotent behavior, the description adds substantial non-obvious details: parallel fan-out across sources, GDELT-to-GNews fallback on rate limits/5xx, USPTO PatentsView sunset soft-failure, and the exact return shape (changes[], total_changes, pipeworx:// URIs). This goes well beyond annotation-only transparency.

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

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

The description is long but every clause earns its place: it front-loads user intent examples, explains the fan-out architecture, documents fallback behavior and failure modes, and ends with a clear alternative. The dense but structured flow keeps it scannable despite its length.

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

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

Even without an output schema, the description fully specifies return contents (structured changes[] grouped by source, total_changes count, citation URIs), input formats, and edge-case behavior (USPTO soft-fail). It covers all necessary operational context for an agent to invoke and interpret results correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description largely repeats what the schema already says for each parameter, but adds a minor usage recommendation ('Use "30d" or "1m" for typical monitoring') that slightly enhances the `since` semantics without introducing new meaning for `type` or `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 opens with concrete user phrasings and defines the tool as a change feed for companies over a date window, clearly distinct from sibling tools. It names the exact data sources (SEC EDGAR, GDELT/GNews, USPTO) and explicitly contrasts with entity_profile, making the purpose unmistakable.

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

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

The description gives explicit usage context: when users ask for "what's new" or "latest updates" in a time window, this tool is appropriate. It also provides a direct alternative: "Use entity_profile instead when you want the static profile... regardless of window," and recommends typical monitoring windows like '30d' or '1m'.

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 (which already indicate a write operation that is idempotent and non-destructive), the description adds critical behavioral context: storage as a key-value pair scoped by the agent's identifier, and the distinction between authenticated users (persistent memory) and anonymous sessions (24-hour retention). This is substantial behavior that annotations do not convey.

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 core purpose, followed by usage scenarios and key storage behavior. Every sentence contributes distinct value: what it does, when to use it, and how persistence works. No filler or redundancy.

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

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

Given the tool's simplicity (2 required parameters, no output schema, no nested objects), the description covers all essential aspects: purpose, usage cues, storage format, scoping, persistence rules, and integration with recall/forget. The absence of output details is acceptable because no output schema exists, and for a save operation, the behavioral context is sufficient.

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

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

Schema coverage is 100%, so the baseline is 3. The description mentions 'key-value pair' which aligns with the two parameters, but it adds no additional semantic details beyond the schema's own property descriptions. The examples in the schema ('subject_property', 'target_ticker', 'user_preference') already provide meaningful context, so the description does not need to compensate.

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 and resource: 'Save data the agent will need to reuse later,' clearly identifying the tool's function. It distinguishes from siblings by contrasting with recall (retrieve) and forget (delete), which are listed as companions. The purpose is unambiguous and well-scoped.

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

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

The description states exactly when to use the tool: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It also provides complementary guidance by mentioning pairing with recall to retrieve and forget to delete, effectively covering both usage and alternatives within the same tool family.

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, but the description adds significant behavioral context: internal cascading of multiple lookups, auto-disambiguation, and specific output components like citation URIs. This goes well beyond what annotations convey, and there is no contradiction.

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

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

The description is somewhat long but well-structured, with example queries up front and bullet-like separators for supported types. Every section adds useful detail (input formats, return values, internal behavior) without redundancy. It earns its length, though it could be trimmed slightly without losing value.

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

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

Since there is no output schema, the description fully covers return values for both entity types, including fields like ticker, CIK, company_name, RxCUI, ingredient, and brand. It also explains input formats and the fact that it cascades through multiple endpoints. For a tool with two simple parameters, this is comprehensive.

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 both parameters are already described. The description adds concrete examples (AAPL, 0000320193, ozempic), clarifies the difference between company and drug types, and mentions auto-disambiguation. This enriches meaning beyond the schema, though schema already does heavy lifting.

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

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

The description clearly states the tool's purpose: resolving a user-spoken name to the canonical/official identifier. Examples like 'ticker', 'CIK', and 'RxCUI' anchor the verb 'resolve' to a concrete resource. It also distinguishes itself from sibling tools by positioning it as the first step when an ID is needed.

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

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

The description gives explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It also mentions that it replaces multiple manual lookups, implying use when efficiency matters. However, it does not explicitly state when not to use it or name alternative tools, so it lacks a complete exclusionary set.

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

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

Annotations already declare readOnly, idempotent, openWorld, non-destructive. The description adds behavioral specifics: it probes each entity via ai_visibility_check (multiple calls), ranks by score, and returns a ranked list with score/confidence/signal density. This goes beyond annotations by explaining the aggregation behavior and output structure, though it doesn't discuss rate limits or costs.

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 core purpose, and every sentence adds value (purpose, mechanics, use case, output). No fluff or repetition of schema details. It's appropriately sized for the tool's complexity.

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

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

For a multi-entity read-only tool with no output schema, the description is quite complete: it describes inputs, behavior, return value shape, and use case. It doesn't mention edge cases like minimum entity count (though schema says 2-8) or error conditions, but annotations cover safety and schema covers parameter constraints, so the description fills the main gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by specifying that the first entity in 'entities' is treated as the 'subject' for narrative, and the rest are competitors—a nuance not present in the schema. It also ties the models parameter to the probing behavior, slightly enriching parameter understanding.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, with specific verbs like 'Compare', 'Probes', 'ranks', and 'surfaces'. It distinguishes itself from sibling tool ai_visibility_check by explicitly mentioning it as the probing mechanism, and from generic compare_entities by focusing on AI presence.

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

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

Provides clear context for when to use: 'competitive AI-marketing audits' with an example question. It implies you use this when comparing multiple entities rather than a single one, but does not explicitly state 'use ai_visibility_check for single entity' or provide exclusion criteria. Still, the context is strong.

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

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

Annotations already indicate read-only and idempotent behavior, but the description adds valuable context about partial failure degradation, a 5-30s first-measurement delay, and the sources_failed field. This goes well beyond the structured hints and provides actionable 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 every sentence earns its place: purpose, use cases, ecosystem scope, output summary, and failure behavior are all covered without fluff. It is front-loaded with the core purpose and organizes details logically.

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

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

Despite lacking an output schema, the description enumerates the return fields in the summary block and lists additional outputs (per-advisory detail, links, recent alternatives). It also covers failure modes, making it complete for an agent to invoke and interpret results.

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

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

Schema description coverage is 100% for both package and version, including scoped package acceptance and version defaulting. The description adds no new parameter-specific semantics beyond what the schema already states, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's composite purpose: a one-call check for npm package adoption covering license, advisories, bundle size, and tree-shaking. It distinguishes itself from siblings by naming the specific external sources (deps.dev and bundlephobia) and explicitly scoping to NPM, which separates it from other research 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?

It gives explicit usage triggers ('is X safe / popular / small' or 'what does adding lodash cost me') and an exclusion: non-NPM ecosystems should use deps.dev:version directly. This provides clear when-to-use and alternative 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 readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds rich behavioral context: returns passages with offsets and similarity scores, uses BGE-base-en embeddings + cosine over 500-char overlapping windows, and has a 200K char cap with truncation flagged. It confirms read-only nature and adds algorithmic details not present in annotations.

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

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

The description is four sentences long, front-loaded with the core purpose, and every sentence adds value: what it does, when to use it, relationship to a sibling tool, and technical implementation details. No fluff or redundancy.

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

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

The tool has no output schema, so the description compensates by explaining the return structure (passages with offsets and similarity scores). It also covers edge cases like truncation, algorithm details, and pairing with ask_pipeworx_grounded. Combined with sibling context, this is a complete and self-sufficient description.

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

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

Schema description coverage is 100% with descriptive text for all parameters (text, query, limit). The description adds context like 'text you already pulled' and 'top-N passages' but does not add significant new meaning beyond the schema. The baseline 3 is appropriate as the schema carries the parameter semantics.

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

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

The description states a specific verb+resource: 'Semantic search INSIDE a fetched record.' It clarifies the scope (inside a fetched record), the input (text you already pulled), and the output (top-N passages with character offsets and similarity scores). It also distinguishes from siblings by emphasizing the 'inside a fetched record' context and pairing with ask_pipeworx_grounded.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt — search_within saves context.' It also names an alternative and relationship: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This gives clear when-to-use and workflow 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 only provide readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral detail: OAuth account requirement, anonymous/BYO cannot persist, SMS phone verification and 10/day cap, webhook signing secret returned only once, and auto-disable after 10 consecutive failures. No contradiction with annotations.

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

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

The description is front-loaded with the core purpose and return value, then covers requirements, types, and delivery in a dense but organized paragraph. Every sentence carries useful information, though the single-paragraph format could benefit from bullet points for scannability.

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 create-type tool with no output schema, the description is remarkably complete: it covers purpose, auth prerequisite, type-specific parameters, delivery channels, return value (subscription id and webhook secret), and failure behavior. The absence of an output schema is compensated by explicitly stating what is returned.

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 input schema covers 100% of parameters, the description adds meaningful semantic depth: concrete examples per type (e.g., items:["5.02"] = officer change), clarifies that the feed is always on, and adds operational constraints like SMS cap and webhook auto-disable that go beyond the schema descriptions.

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

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

The description opens with a specific verb and object: 'Create a proactive monitoring subscription to a live-data event stream' and states the return value ('Returns the new subscription id'). It clearly distinguishes this from siblings like list_subscriptions, unsubscribe, and recent_alerts.

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

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

The description gives clear usage context: requires a Pipeworx OAuth account, lists supported subscription types, and explains delivery channels including 'feed (always on — pull via recent_alerts or GET registry.pipeworx.io/alerts.json)'. It does not explicitly contrast with sibling tools for creating vs listing/unsubscribing, so it stops short of a 5.

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

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

Annotations already cover read-only, open-world, idempotent, and non-destructive behavior. The description adds context about the live catalog source, category-bucketed output, and the optional topic focus, which enhances transparency without contradicting annotations.

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

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

Though lengthy, the description is information-dense with every sentence contributing value. It front-loads with example queries, then explains purpose, output, and usage in a logical sequence, avoiding redundancy.

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

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

For a read-only, single-optional-parameter onboarding tool, the description fully covers purpose, output, parameter semantics, and usage context. The absence of an output schema is mitigated by the clear description of what is returned.

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 describes the 'topic' parameter with 100% coverage. The description adds concrete examples (finance, pharma, betting) and explains the omit-for-full-spread behavior, providing meaning beyond the schema.

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

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

The description precisely states the tool's function: an onboarding entry point that returns category-bucketed example questions with corresponding tool and argument shapes. It is clearly distinguished from sibling tools by emphasizing suggestion rather than execution or 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?

Explicitly instructs to use this tool FIRST when unsure what Pipeworx can do, and mentions learning to call meta-tools. This gives clear when-to-use guidance and indirectly points to alternative tools for deeper tasks.

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

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

The description goes beyond the annotations by disclosing that the operation is a deactivation, not a hard delete, and that ownership is enforced. This adds meaningful behavioral context about side effects and constraints, though annotations already cover idempotency and non-destructiveness.

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 and front-loads the core action. Every sentence provides distinct valuable information: the operation, the ownership restriction, and the deactivation behavior with a pointer to recent_alerts. 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 single-parameter tool with no output schema, the description fully covers what the tool does, its constraints, and its effect on related data (preserving history for recent_alerts). It also provides enough context for an agent to correctly invoke it without additional documentation.

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

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

The schema already provides 100% coverage for the single 'id' parameter, including its type and description ('Subscription id (uuid) returned by subscribe'). The tool description only says 'by id' and adds no additional semantic detail beyond the schema, so a baseline score is appropriate.

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

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

The description clearly states the tool's function: 'Cancel a subscription by id.' It also differentiates from siblings by noting ownership enforcement and deactivation rather than deletion, making it distinct from subscribe, list_subscriptions, and recent_alerts.

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

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

The description conveys when to use the tool: when canceling a subscription you own. It implicitly contrasts with recent_alerts by explaining that historical events remain available, but it does not explicitly name alternative tools or specify when not to use it, so it stops short of full 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=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: it explains the two routing paths (structured XBRL math vs. grounded pipeline), states that evidence is verbatim, and lists the verdict types returned. This goes well beyond the annotation hints and gives a clear picture of what the tool does at runtime.

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

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

The description is longer than average but every section serves a purpose: trigger phrases, usage directives, path differentiation, and return values. It is front-loaded with the most critical information (what the tool does) and structured with a dash-off clause for the financial case. Slight verbosity around the grounded pipeline explanation prevents a 5, but it remains efficiently organized.

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

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

Despite having no output schema, the description enumerates the return fields (verdict, value with citation, reasoning). It covers both claim categories, the tolerance behavior, and the note about replacing sequential calls. Given the tool's complexity and the absence of an output schema, the description is exceptionally complete and leaves no major operational 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%, so the baseline is 3. The description significantly enhances both parameters: it gives a concrete example for 'claim' ("Apple's FY2024 revenue was $400 billion") and explains 'tolerance_pct' beyond the schema by noting it overrides the implied tolerance and recommending 1–2 for hallucination detection. This adds meaningful guidance for agent usage.

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

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

The description opens with multiple natural-language triggers ("Is it true that…"/"fact check"/"verify the claim that…") and clearly states the tool's function: natural-language claim verification against authoritative sources. It distinguishes this tool from siblings by focusing on fact-checking and mentions it replaces a multi-call sequential pipeline, making its purpose unambiguous.

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

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

The description explicitly says "Use whenever the agent needs to check whether something a user said is factually correct." It also provides differentiated guidance: company-financial claims use the SEC EDGAR + XBRL fast path, while any other factual claim falls through to the grounded pipeline. This gives the agent clear decision criteria and context for when to invoke this tool.

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