Mygene Info

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds meaningful behavioral context: the default Workers AI model is free, Anthropic requires a user-supplied key with direct payment, and the per-model return structure is detailed. It goes beyond the annotation hints, though it could mention response variability or rate limits.

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

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

The description is four sentences, front-loaded with the central purpose and followed by model defaults, return format, and use cases. Every sentence contributes value with no redundancy or filler.

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

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

For a tool with no output schema, the description thoroughly covers the return shape ({score, confidence, signals, raw_response} + combined view), model configuration, API key requirements, and target scenarios. It is sufficiently complete 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?

Schema coverage is 100%, so the baseline is 3. The description adds practical meaning by clarifying the default model behavior and explaining that _apiKey is only needed when Anthropic is requested, and that the key is passed straight through to Anthropic. This supplements the schema definitions with usage-oriented 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 begins with the specific verb 'Probe' and clearly defines the resource (one or more LLMs) and the output (visibility score 0-100 per model). It distinguishes itself from sibling tools like ask_pipeworx by focusing on scoring AI knowledge of a brand rather than general Q&A, and it lists concrete use cases.

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

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

The description provides clear context for when to use the tool, such as AI-marketing audits, pre-launch brand checks, and competitive monitoring. It also explains the default model versus the optional Anthropic probe with a BYO key. However, it does not explicitly name alternative tools or state when not to use this tool, stopping short of the highest standard.

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, and destructiveHint. The description adds significant behavioral context beyond this: it routes to many tools, fills arguments, returns stable pipeworx:// citation URIs, works on every tier, and includes live news routing. This gives the agent a clear mental model of the tool's execution without contradicting any 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 (~200 words) but every section earns its place: purpose, domain list, trigger phrases, examples, and sibling differentiation. It is front-loaded with the critical 'PREFER OVER WEB SEARCH' guidance. Slight redundancy (e.g., 'PREFER' and 'even if web search could also answer it') prevents a perfect score, but the structure is logical and scannable.

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

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

Given the tool's high complexity (aggregator of 5,358 tools), no output schema, and rich annotations, the description covers all necessary context: what it does, when to use it, why it exists, how it compares to siblings, and what output format to expect (structured answer with citations). It is fully complete for an agent to decide and invoke appropriately.

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

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

Schema coverage is 100% and the schema already documents the 'question' parameter plus five aliases. The description enriches semantic understanding by providing diverse, real-world example queries (e.g., 'current US unemployment rate', 'Apple's latest 10-K') that illustrate scope and expected input style. This goes beyond the baseline of a plain 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 what the tool does: routes questions to 5,358 tools across 1,395 verified sources, fills arguments, and returns structured answers with citations. It distinguishes itself from web search and sibling tools like ask_pipeworx_grounded and deep_research, 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?

Provides explicit when-to-use and when-not-to-use guidance. It says 'PREFER OVER WEB SEARCH', lists trigger phrases, names alternatives with specific use cases (ask_pipeworx_grounded for verbatim evidence, deep_research for broad multi-part questions), and positions itself as the default start point. This is exemplary usage guidance.

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

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

Annotations already provide read-only/idempotent safety; description adds valuable experimental context including live candidate testing, current absence of an active candidate, and confirmation that this is a fully functional router. 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?

Three sentences that front-load the essential relationship to ask_pipeworx and current state. Slight redundancy in 'Falls back to nothing' / 'full working router' but overall efficient and well-structured.

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

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

For a complex router with no output schema, the description references ask_pipeworx for response shape and explains current behavior, experimental nature, and failure mode. Sufficient for selection, though the response format is not independently 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?

All six parameters are aliases for 'question' and are fully documented in the schema with 100% coverage. The description adds no parameter-level detail beyond referencing same arguments as ask_pipeworx, so the schema carries the load.

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

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

Description clearly identifies this as the beta variant of ask_pipeworx, an identical universal router over 5,358 tools. It distinguishes itself from the stable ask_pipeworx by noting candidate routing improvements and current exact equivalence.

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?

States to use exactly like ask_pipeworx when wanting the newest routing, and mentions results are compared against the stable router to decide merges. It lacks an explicit when-not statement, but the alternative is clearly inferred.

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, but the description adds significant context: explicit refusal reasons, cost trade-off, return format with evidence, and the routing behavior. No contradictions with annotations.

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

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

The description is dense but every sentence contributes: behavior, return format, refusal reasons, usage guidance, and cost trade-off. It is well-structured and front-loaded with the key differentiator.

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

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

No output schema exists, so the description fully explains the return payload including success and refusal cases. It also covers routing, cost, and usage context, making it complete for an agent to invoke correctly.

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

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

Schema coverage is 100% with all parameters described (question and aliases). The description adds no extra parameter-level detail beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states this is a hallucination-resistant answer mode for high-stakes reads, with specific verbs like 'extracts' and 'returns'. It distinguishes itself from sibling ask_pipeworx by emphasizing grounded extraction and explicit refusals.

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 ('whenever an answer will be quoted, cited, or acted on') and provides examples. It also gives an alternative, 'prefer ask_pipeworx for casual lookups', and notes the extra LLM call cost.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints, but the description goes far beyond them by disclosing fan-out mechanics, response shapes, resolver contract, safety short-circuits, market-closed handling, liquidity warnings, and resolution-rule risk. It reveals how low-confidence matches suppress analysis fields and how closed markets may surface via the low_confidence_match path. This is exceptional behavioral disclosure.

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

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

The description is very long but meticulously structured with capitalized section markers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loaded with the core purpose. Each sentence carries unique operational detail, but the sheer volume may overwhelm an agent looking for quick understanding, so not a 5.

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

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

For a tool with no output schema, the description compensates by thoroughly explaining response shapes, resolver contract fields, parent_event extractor, news fallback flags, safety statuses, and cancellation-rule risks. It covers inputs, behaviors, edge cases, and interpretation guidance comprehensively, making it self-sufficient for an agent.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds significant value by explaining input format flexibility (slug, URL, question text), enumerating classifier categories that affect fan-out, and clarifying the behavior of depth and include_raw with size implications. This pushes it above baseline but does not fully replace the structured schema, hence a 4.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes the tool's scope (Polymarket bet research with category-specific data packs) from siblings like compare_entities or deep_research, and names concrete use cases such as 'should I bet on X'.

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 the tool with three example queries ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'). It provides rich context for when the tool is appropriate and describes blocking behavior for low-confidence or closed markets, but it does not explicitly name alternative tools for when not to use it, which would push it to 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/openWorld/idempotent/destructive hints, and the description adds substantial behavior beyond that: data sources (SEC EDGAR/XBRL, FAERS/FDA), handling of off-calendar fiscal years, sorting by primary metric, and return of paired data + citation URIs. This enriches agent understanding 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 information-dense but slightly overstuffed with examples and redundant emphasis on parallelism ('ONE parallel call' vs 'Replaces 8–15 sequential lookups'). It is well-front-loaded and each part adds value, but it could be trimmed without losing essential guidance.

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

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

Despite having no output schema, the description explains return format (paired data + citation URIs) and covers both entity types with distinct data sources. It also addresses edge cases like fiscal-year offsets, making it complete for the tool's complexity. No gaps were identified for an agent 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 crucial meaning: it explains what type='company' actually retrieves (specific 10-K financials) and what type='drug' retrieves (FAERS counts, approvals, trials). It also clarifies that results are sorted by the primary metric, giving agents insight into how the 'values' parameter affects output ordering.

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

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

The description explicitly states the tool performs side-by-side comparison of 2–5 companies or drugs, with a specific verb ('compare') and resource type. It includes numerous natural-language triggers ('which is bigger', 'rank these companies') and clearly distinguishes itself from single-entity lookups by emphasizing it does comparisons in one parallel call.

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

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

The description gives explicit guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also explains data sources and behaviors for company vs drug types, making it clear when to use this tool versus doing multiple lookups. This effectively communicates the intended use case and exclusions.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses extensive behavioral traits: 'depth:"thorough" needs a paid plan', 'returns explicit gaps[] for facets the data couldn't answer (never invented)', 'Large records are semantically excerpted to the passages relevant to each facet', 'Expect 15-60s', and details on contradiction scanning and second-hop iteration. 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 every sentence adds essential information: account requirements, tool behavior, alternatives, caveats, timing, and edge cases. It is front-loaded with the most critical caveat (account/payment) and organized logically from core purpose to usage guidance to implementation details. Minor redundancy exists between the depth explanation in the schema and the description, but the description adds new details like 'hop field' and 'citation_uri.'

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 research tool with no output schema, the description is remarkably complete. It explains the return format (findings packet with evidence, confidence, source, fetched_at, citation), gaps handling, contradiction detection, excerpting behavior, latency expectations, and account prerequisites. This fully equips an agent to invoke the tool correctly 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 coverage is 100% for both parameters, so baseline is 3. The description adds extra semantics for the depth parameter by explaining behavioral consequences ('standard re-angles unanswered gaps... thorough additionally chases the best leads'), going beyond the schema's enum wording. The question parameter is adequately described in schema and implied by the description's research focus.

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 combination: 'Grounded multi-source research across Pipeworx's 1395 STRUCTURED data sources... Decomposes your question into focused facets, routes each to the right one of 5,358 tools IN PARALLEL, and returns a findings packet.' It clearly distinguishes from siblings by explicitly contrasting with ask_pipeworx for single lookups and breaking news, and by stating 'this is NOT open-web search.'

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: 'Best for broad/multi-part questions over structured data... For a single lookup use ask_pipeworx... For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' It also specifies account requirements and depth alternatives, making when-to-use vs alternatives unmistakable.

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 valuable context beyond annotations: it returns top-N tools with names, descriptions, and full input schemas, and notes results are ready to call directly without a second schema lookup. This discloses return format and convenience behavior not visible in annotations.

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

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

The description is four sentences, each serving a purpose: definition, usage context, return details, and strategic directive ('Call this FIRST'). It is well-structured and front-loaded with the core function, with no redundant or filler content.

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

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

Given the tool's discovery function, the description fully covers its purpose, usage, return format, and recommended invocation order. It includes a comprehensive domain list and clarifies the output readiness. No additional context is needed for an agent to use this tool effectively.

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 'describing the data or task' which aligns with the 'query' parameter, but does not add detailed semantics for 'limit' or the aliases beyond what the schema already provides. It doesn't improve on the structured schema definitions.

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

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

The description clearly states the verb 'Find' and resource 'tools', with an explicit list of domains (SEC filings, financials, FDA drugs, etc.) to clarify scope. It distinguishes itself from sibling tools like query or deep_research by positioning as a tool-discovery mechanism rather than a data-querying tool.

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

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

Provides explicit guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set.' This gives a clear when-to-use directive, though it doesn't explicitly name alternatives, the 'FIRST' call order implies a comparison against other tools.

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

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

The description reveals behavioral details beyond annotations: it fans out across multiple data sources, returns specific fields (recent_filings up to 5 with URIs, fundamentals sorted period_end DESC), includes a soft-fail note for patents due to API sunset, and uses GDELT→GNews fallback. Annotations already mark it read-only, idempotent, non-destructive, and open-world; the description enriches this with concrete behavior.

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

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

Although the description is lengthy, it is dense and structured: examples first, then purpose, then data sources, then limitations. Every sentence carries information, with no filler.

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

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

With no output schema, the description carries the burden of explaining return values, and it does so comprehensively—listing return fields, limits (up to 5 filings), ordering, and fallback behavior. It also clarifies input constraints and the need for resolve_entity. This is complete for an agent to invoke correctly.

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

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

Schema description coverage is 100% with detailed descriptions for both 'type' and 'value', so the baseline is 3. The description provides examples and reinforces the resolve_entity fallback, but does not add materially new parameter semantics beyond the schema.

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

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

The description uses specific verbs like 'Tell me about', 'research', 'brief me on', and defines a clear scope: full cross-source profile of a US public company in one parallel call. It distinguishes from sibling tools by explicitly preferring this over chaining single-pack lookups and referencing resolve_entity for names.

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

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

It gives explicit guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and 'names not supported (use resolve_entity first if you only have a name)'. This tells the agent exactly when to use this tool and what to do for alternative input types.

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

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

Annotations already declare destructiveHint and idempotentHint, so the bar is lower. The description adds context about what gets deleted (previously stored memory, sensitive data) and when it is appropriate, but doesn't describe edge cases like missing keys. 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?

Three sentences each serve a distinct purpose: action, usage timing, and related tools. No wasted words.

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

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

The tool is simple (one required parameter) with annotations covering its safety profile. Description covers purpose, when to use, and relationships to siblings, which is sufficient without an output schema.

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

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

Schema coverage is 100% with 'Memory key to delete'. The description only repeats 'by key' without adding new semantic details, so baseline 3 is appropriate.

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

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

The description clearly states 'Delete a previously stored memory by key' – a specific verb, resource, and method. It also distinguishes itself from siblings by pairing with remember and recall, indicating its role in the memory 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?

Explicitly provides when to use: 'Use when context is stale, the task is done, or you want to clear sensitive data...' and pairs with alternatives 'remember and recall', giving clear context and 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 the tool as read-only, idempotent, and non-destructive. The description adds only 'single gene id', which is also visible in the schema, and provides no additional behavioral context about what annotations entail or how results are structured.

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 one short sentence with no wasteful words. It is appropriately concise, though it borders on under-specification, but this is a matter of completeness rather than conciseness.

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

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

Output schema exists, so return values are covered. However, the description is too sparse to compensate for the low schema coverage of fields and species. An agent would need to rely heavily on examples, making the tool harder to invoke correctly without additional 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 only 33% (only gene_id is described). The tool description does not clarify the meaning of 'fields' or 'species', and the schema examples only hint at usage. The description adds no semantic value to the 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 indicates the tool provides annotations for a single gene ID, which distinguishes it from generic entity tools like entity_profile or metadata. However, it lacks an explicit verb such as 'retrieves' or 'returns', but the noun phrase is still specific enough.

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 given on when to use this tool versus alternatives. It does not mention any prerequisites, recommended contexts, or exclusions, leaving the agent to infer usage from the name and schema.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds process details: fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. It also clarifies the output is a single text blob ready to drop at site-root/llms.txt, providing useful context beyond annotations.

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

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

The description is well-structured and efficient: first sentence states the action and purpose, second explains the process, third describes output, and final sentence offers practical use cases. Every sentence adds information without 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?

With only 2 parameters, no output schema, and strong annotations, the description fully explains what the tool does, how it works, what it produces, and when to use it. It is complete for the tool's complexity level.

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

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

Schema description coverage is 100%, so the schema already documents both parameters (url and max_links). The description does not add deeper meaning about parameter use beyond what is in the schema, 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 uses a specific verb ('Generate') and resource ('a production-ready llms.txt file for any URL'), clearly identifying the tool's function. It also states the target audience (AI crawlers) and differentiates from siblings by focusing on llms.txt generation, which none of the sibling tools appear to do.

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

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

The description provides clear usage context with concrete use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'). It does not explicitly exclude when not to use it or name alternatives, but it effectively communicates the intended scenarios.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful context beyond these by specifying that it lists active subscriptions and enumerates returned fields (id, type, params, created_at, last_fired_at, fire_count). It does not contradict annotations.

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

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

Two sentences, front-loaded with the main purpose, followed by a concise list of return fields and a practical use-case. Every word earns its place; no fluff or repetition of schema details.

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

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

Given the tool's low complexity (one optional parameter, no output schema) and strong annotations, the description is fully complete. It states what is returned, from whom (the caller), and when to use it, 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?

Schema description coverage is 100% for the single parameter (include_inactive with a clear description). The tool description does not add further semantics about the parameter; it simply mentions 'active subscriptions' which implies the default. Thus the description adds no value beyond the schema, matching the baseline score of 3.

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

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

The description explicitly states the action ('List') and the resource ('the caller's active subscriptions'), and it distinguishes itself from sibling tools like subscribe and unsubscribe by focusing on review and retrieval. It also names the return fields, making the tool's 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 provides explicit usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This directly advises when to use the tool versus alternatives, giving clear practical scenarios.

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

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

Annotations already establish that the tool is read-only, open-world, idempotent, and non-destructive. The description adds only that it involves 'release / source metadata,' leaving ambiguous what action is performed or what output is expected. This is minimal additional behavioral context.

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

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

The description is extremely short, but this comes across as under-specification rather than effective conciseness. It fails to provide even a verb or a complete sentence to explain the tool's 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?

With zero parameters and an output schema present, the tool is not complex, but the description still needs to state what the tool actually does. 'Release / source metadata' is too vague to be considered a complete explanation.

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

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

The tool has zero parameters, so the schema is trivially complete and there is nothing to document. Per rubric, 0 params sets a baseline of 4, even though the description itself adds no parameter-related 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 reads as a fragment, merely stating 'Release / source metadata' without a verb or clear action. It essentially restates the title 'Metadata' and does not distinguish the tool from siblings like 'discover_tools' or 'taxonomy.'

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 any of its many siblings. The description gives no context about appropriate scenarios or alternatives, offering no help with tool selection.

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

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

Annotations provide no safety hints (all false), so the description carries the burden. It discloses rate limits ('Rate-limited to 5 per identifier per day'), cost/quota impact ('Free; doesn't count against your tool-call quota'), and real-world consequences ('The team reads digests daily and signal directly affects roadmap'). This goes well beyond what annotations offer.

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

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

The description is four sentences, each earning its place: purpose, usage triggers, content guidelines, and operational constraints. It is front-loaded with the core purpose and highly readable with no fluff.

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

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

For a tool with 3 parameters (one nested object) and no output schema, the description fully covers what an agent needs to know: purpose, when to use, how to structure feedback, rate limits, and cost. It is complete for both selection and correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra value by instructing how to frame the message content (in terms of Pipeworx tools/packs, not user prompts) and clarifies the 'type' semantics indirectly through usage scenarios. This enriches parameter understanding beyond the schema alone, though the schema already handles 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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly defines the tool's purpose and distinguishes it from all sibling tools, which are research/query/subscription tools. The explicit enumeration of feedback types (bug, feature/data_gap, praise) further clarifies scope.

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

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

The description provides explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives clear content framing instructions (describe in terms of Pipeworx tools/packs, don't paste end-user prompt), making it easy for an agent to decide 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.

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

Annotations already convey read-only, open-world, idempotent, non-destructive behavior. The description adds valuable context: self-aggregating signal, derivation from CF analytics-engine, no PII, and caching behavior (5min-1h). This goes beyond the annotations and helps set expectations about freshness and privacy.

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

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

The description is well-structured and front-loaded: the first sentence states purpose, followed by return values, a numbered list of use cases, and then technical details. Every sentence adds value, and the numbered list improves 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?

Despite having no output schema, the description explicitly mentions the returned data shape: '(pack, tool, count)'. It also covers caching and PII, which gives the agent a full picture. For a simple single-parameter read-only tool, 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?

The single parameter `window` is fully described in the schema itself, including the enum values and the meaning of shorter vs longer windows. The description does not add additional parameter-level detail, so baseline 3 is appropriate since schema coverage is 100%.

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: 'What other AI agents are calling on Pipeworx right now' and specifies the output: 'top tools, top packs, and total call volume'. It distinguishes itself from siblings by focusing on aggregate trending rather than individual lookups or discovery.

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

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

It provides three explicit use cases: discovering hot data sources, confirming canonical tool choice, and checking alignment with agent needs. These give clear context for when to use this tool, though it does not explicitly name alternative tools or exclusion criteria.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description goes far beyond by explaining the monotonicity/partition logic, the placeholder filter, semantic anchor, and the fill check with realizable vs theoretical edge. It even warns 'do not trade it' when realizable_edge_pp ≤ 0, providing actionable behavioral context.

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

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

Despite its length, the description is highly structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and every sentence carries critical information. It front-loads the core purpose in the first sentence and uses capitalization to emphasize key concepts, making it scannable despite the density.

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

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

The tool is complex with multiple modes, edge cases, and a fill-check component. The description covers return values (opportunities[], partition_check{}), failure modes (skipped_low_similarity, placeholder fractions), and the distinction between theoretical and realizable edge. With no output schema, this description fully compensates 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 description coverage is 100%, but the description adds substantial semantic depth: it explains what each mode does, provides concrete examples ('fed-decision-may-2026', 'Strait of Hormuz traffic returns to normal'), and details the behavior of each parameter (e.g., event mode walks child markets, topic mode flattens markets). This goes well beyond the schema's one-liners.

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: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes modes (no args, event, topic) and differentiates from siblings like polymarket_edges and polymarket_fill_risk.

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

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

Provides explicit when-to-use guidance: 'Call with NO args for a trending_scan', 'pass event for the strongest per-event partition_check', 'topic for a themed cross-event scan'. It also names the alternative for custom sizing: 'For custom sizing use polymarket_fill_risk.' Thus it covers both usage and 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?

The description goes far beyond the readOnlyHint by detailing internal calculations (lognormal barrier from FRED, GDELT ratios, overround partitioning, Kelly caps), response segments, diagnostics, caching, and limitations (e.g., Fed signal unreliability, placeholder-slug filters). It also discloses when opportunities are 'rare-by-design' and warns about 24h market moves consuming edge.

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 lengthy but extremely well-structured with explicit section labels (FIVE MODEL FAMILIES, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL) and a clear hierarchy. It is front-loaded with the core purpose, and every clause adds necessary detail given the tool's complexity. No wasted words.

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

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

With no output schema, the description thoroughly explains the response structure (by_segment, fed_candidates, _diagnostics) and why segments may be empty, covering return semantics fully. It also documents caching behavior, model families, and edge definitions, making the tool self-sufficient for correct invocation and interpretation.

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 has 100% parameter coverage, the description adds crucial behavior context, especially for knobs like min_partition_leg_kelly (explaining why parent-level kelly is zero and how per-leg applies) and max_spread_pp/min_liquidity ('Tradeable-edge filter... drop opportunities where edge isn't realizable'). This enriches the schema's bare 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+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly distinguishes this tool from siblings focusing on arbitrage, fill risk, or spread tracking by emphasizing Pipeworx-signal-driven edge discovery.

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

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

The description says it is 'Built for "what should I bet on today"' and notes that agents 'discover opportunities without paging hundreds of markets,' giving a clear use context. It also explains when to adjust tradeable-edge knobs (e.g., 'Set to 2 to require tight books'). However, it does not explicitly name alternative tools for exclusion, such as polymarket_arbitrage.

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 important behavioral traits: snapshots are written on cache-miss so gaps mean no scan, history is bounded by a 60-day TTL, and decay numbers come from daily closes not intraday. It also explains the meaning of trend and decay_pp_per_day, including the signed nature of edge_pp_net.

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

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

The description is dense and structured with clear sections (Args, RESPONSE, LIMITS). Every sentence adds value—purpose, parameter defaults, return field semantics, and caveats about data availability. It is long but appropriately so for the complexity of the telemetry data it returns.

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 specifies the response shape: tracked[], expired[], and snapshot_dates[] with their fields and semantics. It also covers limitations and data caveats, making the tool's behavior understandable and usable without additional context.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by explaining that 'days' is a lookback with default 14 and 'window' selects a snapshot family (24hr/1wk/1mo), and it ties these to the telemetry context. This goes slightly beyond the raw schema descriptions but is not exhaustive.

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

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

The description states a specific purpose: edge persistence and decay telemetry, and clarifies it answers 'how long has this edge existed and is it shrinking?' It distinguishes itself from sibling tools like polymarket_edges by focusing on historical snapshots and persistence analysis rather than current edge data.

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

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

The description implies when to use this tool: when you need historical persistence/decay rather than just current edges. It references being built from polymarket_edges snapshots, which differentiates it from that sibling. Limits on history depth and snapshot gaps provide clear context for interpreting results, though it stops short of explicitly saying 'do not use for current edges.'

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds rich behavioral context beyond that: it walks the order-book ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), identifies thin_legs and forced_directional_risk, and warns about the danger of partial basket fills. It fully discloses behavior 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 meticulously structured: purpose first, then mode-specific instructions in labeled sections, then a clear usage trigger with risk rationale. Every sentence adds necessary information—mode behavior, outputs, defaults, and warnings. No fluff or redundancy.

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

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

Given the tool's complexity (two modes, many output fields) and the absence of an output schema, the description is remarkably complete. It covers all parameters (including defaults and range clamp), specifies return values per mode, and addresses risk scenarios. An agent would have everything needed 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 coverage is 100% with basic descriptions, but the tool description significantly augments meaning: it explains that `market` and `event` are mutually exclusive modes, how `side` defaults differ per mode, and how `size_usd` is interpreted differently (max spend on buys, target proceeds on sells, settlement notional in basket mode). This goes well beyond the schema's generic field labels.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes itself from sibling tools by naming polymarket_arbitrage and polymarket_edges and explaining when this tool is needed. The two modes (SINGLE-MARKET and BASKET) are explicitly 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 gives explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the rationale (theoretical overround on thin books is not capturable, partial fills create unhedged directional risk), making the decision criteria 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?

Annotations already mark the tool readOnly, idempotent, and non-destructive; the description adds substantial behavioral detail: compatibility_warning trigger conditions, temporal_alignment semantics, skipped_cross_type/subtype counters, and the caveat that pre-mapped topics are not necessarily tradeable. This goes far beyond what annotations alone convey and does not contradict 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 long but well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and each sentence adds functional knowledge. Some density could be reduced, but the complexity of the tool justifies the length.

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

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

With no output schema and no enums, the description carries the full burden of explaining return values and edge cases. It covers leg prices, spread units, compatibility_warning cases, temporal alignment, and skip counters—leaving no major gap for an agent to select or 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 provides 100% parameter coverage with examples. The description complements this by explaining mode-level behavior: how topic auto-fetches, how explicit tickers override the topic mapping, and how the response and safety fields interrelate—adding value beyond the schema.

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

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

The description opens by defining the tool as 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' naming the specific computation and target venues. It distinguishes itself from sibling Polymarket-only tools by emphasizing the cross-venue scope and explicitly describing two input modes.

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

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

The description clearly delineates when to use the topic shortcut versus explicit ticker/slug pairing, and warns that pre-mapped topics often return compatibility_warning. However, it does not name alternative sibling tools or explicitly state when not to use this tool in favor of another, so exclusions remain implicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. However, the description adds no additional behavioral context such as query syntax limitations, result paging, or scoping, failing to leverage the opportunity to inform beyond annotations.

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

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

The description is a single short sentence, which is concise, but it is under-specified rather than efficiently informative. It lacks structure or front-loaded key details, sacrificing clarity for brevity.

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 5 parameters, an output schema, and a complex query language, a one-line description is incomplete. It does not explain return values, query behavior, or use context, leaving significant gaps for an agent to invoke correctly.

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

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

Schema description coverage is 80%, which is above the high threshold, so the baseline is 3. The description itself adds no extra meaning to the parameters beyond what the schema already provides, and the 'sort' parameter lacks 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 'Full-text gene query' indicates the tool searches genes via full-text, but it is ambiguous about the specific gene database, return behavior, and how it differs from sibling tools like 'gene' or 'query_many'. This is a clear verb+resource but lacks the specificity needed to fully distinguish it.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention use cases, prerequisites, or situations where a sibling tool would be more appropriate, leaving the agent without direction.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds useful behavioral context beyond annotations, including the HTTP method (POST), the batch limit (1000), default scope, and that it returns annotations, 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?

The description is a single dense sentence that efficiently conveys the core purpose, method, limits, default, and return value. It contains no fluff, though it could be split into two sentences for readability without losing information.

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

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

The description covers the core functionality and batch aspect, but it misses parameter semantics for fields and species, and offers minimal guidance on when to use the tool versus siblings. The presence of an output schema reduces the need to describe return values, but the gaps in parameter explanation and usage guidance make it only partially 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 only 25% (only scopes has a description). The description clarifies that ids accepts gene symbols, Entrez IDs, or Ensembl IDs, and that scopes defaults to 'symbol', but it does not explain 'fields' or 'species', which are important for customizing queries. The schema examples partially fill this gap.

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 (Batch-resolve), the resource (list of gene symbols, Entrez IDs, or Ensembl IDs), the method (single POST to mygene.info), and the output (annotations). This distinguishes it from sibling tools like 'query' or 'gene' which likely handle single queries.

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 batch lookups with a limit of 1000, but it does not explicitly state when to choose this over alternatives such as 'query' or 'gene', nor does it mention exclusions or prerequisites. Usage context is implied rather than clearly defined.

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

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

The description adds meaningful behavioral context beyond the annotations: scoping ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the listing behavior when the key is omitted. While annotations already indicate read-only and idempotent, the scoping and listing details are valuable and not present in structured metadata.

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

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

Three sentences, each earning its place: action, usage context, scoping and pairing. The description is front-loaded and free of filler, making it both concise and well-structured.

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

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

For a tool with one optional parameter and no output schema, the description is complete. It covers the tool's purpose, usage scenarios, scoping, and relationships to sibling tools, leaving no critical gaps for an agent to invoke it correctly.

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

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

The schema already fully covers the single parameter with a description ('Memory key to retrieve (omit to list all keys)'), achieving 100% coverage. The description reinforces this but does not add new parameter syntax or format details beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' This is specific and distinctive, and it differentiates from sibling tools by explicitly pairing with remember and forget.

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

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

It provides both a clear when-to-use context ('Use to look up context the agent stored earlier... without re-deriving it from scratch') and explicit alternative tools ('Pair with remember to save, forget to delete'). This fully meets the rubric's requirement for explicit when/when-not/alternatives.

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

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

The annotation readOnlyHint: true claims the operation is read-only, but the description explicitly states 'Set mark_read:true to flag returned events read so the next call only shows newer ones', which is a state-modifying side effect. This directly contradicts the read-only hint, making the annotation misleading.

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, then expands with key details. Every sentence adds useful information and there is no fluff 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?

Even without an output schema, the description explains the return payload (source, citation_uri, raw event payload), filtering options, the mark_read side-effect, polling suitability, and an alternative access method. It fully covers what an agent needs to use the tool effectively.

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 all parameters with descriptions (100% coverage). The description adds value by providing a concrete type example ('sec_8k'), clarifying the since parameter as an ISO timestamp, and explaining the cross-call impact of mark_read. This goes beyond the schema's baseline 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 'Pull fired events from your subscription feed', which uses a specific verb and resource. It clearly identifies the tool's scope and distinguishes it from sibling tools like list_subscriptions (which lists subscriptions) and recent_changes (which tracks changes).

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

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

The description provides clear usage context: it mentions polling suitability and offers an alternative HTTP endpoint for scripts/dashboards. However, it does not explicitly contrast this tool with sibling tools like list_subscriptions or recent_changes, so it stops short of full 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?

Beyond the readOnly/openWorld/idempotent annotations, the description discloses multi-source fanout, GDELT→GNews fallback conditions, USPTO soft-fail due to API sunset, and the exact return shape. This gives the agent a realistic model of side effects and failure modes 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 dense but every element earns its place — purpose, source details, fallback logic, parameter formats, return summary, and alternative tool. It front-loads with natural-language query examples that make the intent immediately clear.

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 covers the return contract (changes[], total_changes, citation URIs). It also addresses nuances like source priority, rate-limit fallback, and the historical API sunset, which is more than enough given the tool's moderate complexity.

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

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

Despite 100% schema coverage, the description adds significant meaning: accepted since formats ('2026-04-01', '7d', '30d', '3m', '1y') with a recommended default, allowed value forms (ticker or zero-padded CIK), and single company type. These enrich the schema descriptions with practical examples.

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

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

The description identifies the tool as a change feed for a company over a recent window, with concrete example phrasings ('What's new with X', 'updates on Acme'). It explicitly differentiates from the sibling entity_profile by noting that tool is for static profiles.

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

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

It gives clear guidance on when to use the tool (recent changes, news, filings) and explicitly directs users to entity_profile for static profiles regardless of window. Also explains the parallel-call behavior and fallback sources, making selection and invocation unambiguous.

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

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

Annotations already cover idempotency and non-destructiveness. The description adds valuable context: key-value pairs are 'scoped by your identifier,' authenticated users get persistent memory, and anonymous sessions retain memory for 24 hours. It also explains the relationship to recall and forget, which is beyond annotation 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 four sentences long, front-loaded with the core purpose, and every sentence adds value: purpose, usage scenario, storage behavior, and related tools. There is no redundancy or filler.

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

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

For a tool with only two parameters, no output schema, and strong annotations, the description covers all essential aspects: what it does, when to use it, how data is scoped and persisted, and how it relates to sibling tools. It is complete without needing to explain return values.

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

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

Schema coverage is 100%, and both parameters are well-documented with examples ('subject_property', 'target_ticker', etc.). The description reinforces parameter usage through examples but does not add significant new syntax or format details beyond the schema. Baseline of 3 is appropriate when 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 states a clear verb+resource: 'Save data the agent will need to reuse later.' It goes beyond a simple definition by specifying the resource (key-value store) and the purpose (reuse across sessions), and it explicitly differentiates from sibling tools by mentioning 'recall' and 'forget.'

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

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

Provides explicit guidance: 'Use when you discover something worth carrying forward (a resolved ticker, a target address, a user preference, a research subject) so you don't have to look it up again.' It also names alternative tools ('Pair with recall to retrieve later, forget to delete'), giving clear when-to-use and alternative 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, idempotentHint, and destructiveHint, providing a safe profile. The description adds valuable behavioral context by stating 'Each call cascades through several lookup endpoints internally' and describing the exact return format for each entity type, including citation URIs. This goes beyond annotations and helps set expectations for call behavior and output.

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 every sentence serves a purpose: examples, usage rule, type-specific details, and internal behavior note. It is front-loaded with the core purpose and examples, then structured by entity type. Slightly verbose but not wasteful.

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

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

With no output schema, the description fully explains return values for both company and drug types, including data sources and citation URIs. It covers input formats, disambiguation ('auto-disambiguated'), and internal cascading. For a tool with two entity types and no output schema, this is complete enough for an agent to invoke it correctly 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%, but the description significantly enriches both parameters. For 'type', it lists supported enums with detailed output descriptions (e.g., 'company' returns ticker + 10-digit CIK + company_name from SEC EDGAR). For 'value', it provides concrete examples and input formats (ticker, CIK, name, brand/generic). This adds meaning 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 uses the specific verb 'resolve' and clearly states the resource: 'user-spoken NAME to the canonical/official identifier other tools require as input.' It provides concrete example queries ('What's the ticker for…' / 'find the CIK for…') and distinguishes itself by saying 'Use FIRST whenever you have a name but need an ID.' This clearly separates it from siblings like entity_profile or compare_entities.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' providing a direct usage guideline. It also explains the tool replaces 2-3 manual lookups, implying when it is advantageous. It doesn't need to list exclusions; the instruction is clear and actionable.

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

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

Annotations already declare read-only and idempotent behavior, but the description adds valuable behavioral details: it probes each entity via ai_visibility_check, ranks by score, and surfaces most/least recognized. It also discloses the return format. It does not contradict annotations, and goes beyond what annotations provide.

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

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

The description is appropriately sized: four sentences, front-loaded with the core purpose, followed by use case and return format. Every sentence earns its place, with no fluff or redundancy.

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

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

Given the tool's complexity (multiple entities, optional models, API key) and the lack of an output schema, the description covers the necessary context: what it does, how it operates, when to use it, and what it returns. It omits minor details like cost or failure modes but these are not critical for a read-only comparison tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces that entities refers to 'your brand + N competitors' but adds no syntax or format details beyond what the schema already documents. It does not meaningfully clarify models, _apiKey, or context beyond their existing 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 starts with a specific verb-resource pair: 'Compare AI visibility across multiple entities side-by-side.' It clearly distinguishes this from the sibling ai_visibility_check (singular probe) and compare_entities (more general) by emphasizing side-by-side comparison of multiple entities and AI visibility specifically.

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: 'Useful for competitive AI-marketing audits' with a concrete example. It implies this is for multi-entity comparison, contrasting with ai_visibility_check's single-entity scope. However, it does not explicitly state when not to use it or name alternatives, 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 indicate a safe, non-destructive, idempotent read operation. The description adds valuable behavioral context beyond annotations: it mentions partial failure handling, the 5-30s latency for bundlephobia's first measurement on a new version, and the sources_failed field. This exceeds the lower bar set by 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 relatively long but every sentence contributes meaningful information. It front-loads the core purpose and then adds details on usage, ecosystem limitation, and return fields. It is slightly dense but remains focused and structured, earning a 4 rather than a 5.

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

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

There is no output schema, so the description compensates by enumerating the return fields (summary block contents, per-advisory detail, links, recent versions) and explaining failure behavior. For a composite tool with dependencies on external APIs, this level of detail is complete enough for an AI agent to know what to expect.

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

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

Schema description coverage is 100% — both 'package' and 'version' have clear descriptions. The description adds no new semantics beyond the schema, but it does reinforce the default version behavior. Baseline 3 is appropriate since the schema already carries the parameter meaning.

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

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

The description clearly states the tool's purpose: a composite check for whether to add an npm package, covering license, advisories, version history, and bundle size. It uses a specific verb ('scan') and resource ('dependency'), and distinguishes itself by mentioning the fan-out to deps.dev and bundlephobia, which also differentiates it from sibling tools.

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

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

Explicitly states when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also provides an exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', directing users to an alternative for other ecosystems.

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

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

Goes well beyond the readOnly/idempotent annotations by disclosing the exact return format (top-N passages, character offsets, similarity scores), the technical implementation (BGE-base-en embeddings, cosine, 500-char overlapping windows), and the critical truncation behavior at 200K chars (with a flag). This gives the agent full awareness of what to expect and potential limitations.

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

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

The description is concise and well-structured, leading with purpose, then use cases, then technical details. No sentence is wasted, though it is slightly longer than the minimal two-sentence ideal—all content earns its place.

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

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

Given there is no output schema, the description explains the return values (passages, offsets, similarity scores) and covers limitations (character cap, truncation flag). It also situates the tool within the broader workflow (pairing with ask_pipeworx_grounded), making it fully self-contained for an agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful extra context: the 'text' parameter's size cap (200K, truncation), query examples in the 'query' description, and the 'limit' range is already in schema. This adds value beyond the schema, hence a 4.

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

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

The description uses a specific verb ('semantic search INSIDE a fetched record') and clearly identifies the resource (the text passed in). It distinguishes from siblings by emphasizing this works inside a caller-provided record, not the knowledge base, and names ask_pipeworx_grounded as a complementary tool, making the purpose unambiguous.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt' and explains the benefit of context savings and verifiable offsets. It also provides an explicit alternative/complement: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This is clear usage guidance with a named sibling.

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 many behavioral traits beyond the annotations: the always-on feed, optional email/sms/webhook channels, SMS verification and 10/day cap, webhook HMAC secret returned once, and auto-disabling after 10 consecutive failing runs. These details give the agent a rich understanding of side effects and limitations that annotations alone (readOnlyHint false, idempotentHint true) do not provide.

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

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

The description is long but information-dense, with each sentence adding meaningful details about types and delivery channels. It is logically structured, but the heavy use of colon lists and embedded examples makes it somewhat harder to scan. It earns a 4 because every part contributes utility, though better formatting could improve readability.

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 (five types, nested objects, multiple delivery channels) and the absence of an output schema, the description is remarkably thorough. It covers the return value, type-specific parameters, authentication requirements, and delivery channels with edge cases like auto-disable. It does not cover error handling or invalid input responses, but this is not necessary for correct selection and invocation.

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

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

Although the schema covers 100% of the parameters, the description adds valuable concrete examples and constraints (e.g., items:['5.02'] for sec_8k, topic:'fed' for polymarket_edge, series_id:'UNRATE' for fred_series). It also enriches the delivery parameter with specifics like the webhook signature format and auto-disable behavior, going beyond the schema descriptors.

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 'Create a proactive monitoring subscription to a live-data event stream' and specifies 'Returns the new subscription id,' clearly distinguishing it from sibling tools like list_subscriptions and unsubscribe by focusing on creation. It also enumerates concrete subscription types and delivery channels, making its scope 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?

The description explicitly states the prerequisite: 'Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions),' providing clear context for who can use it. It also explains delivery options and feed behavior, but does not directly contrast with alternative tools like recent_alerts for one-off polling. It lacks explicit when-not-to-use guidance beyond the auth requirement.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds behavioral context beyond these: it returns category-bucketed example questions drawn from a live catalog, includes the exact tool and argument shape, and explains the behavior with and without the topic parameter. There is 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 somewhat long but well-structured: it opens with the purpose, lists example query phrases, describes the output, explains parameter usage, and gives explicit usage guidance. Every sentence contributes value, though it could be tightened for conciseness. It earns a 4 for front-loading the key purpose and maintaining relevance throughout.

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

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

For a tool with one optional parameter and no output schema, the description is fully complete. It explains what the tool returns (category-bucketed example questions with tool and argument shapes), how to call it, and when to use it. There are no significant gaps in understanding the tool's behavior or expected output.

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

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

The schema already describes the 'topic' parameter with possible values and the effect of omitting it. The description repeats this information (e.g., examples like 'finance', 'pharma', 'betting') without adding meaning beyond the schema. Since schema coverage is 100%, a baseline of 3 is appropriate; the description does not compensate with additional parameter-level 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 clearly states the tool's purpose: it is the onboarding entry point that returns category-bucketed example questions with the exact tool and argument shape that answers them. It distinguishes itself from siblings by explicitly instructing to use it first when unsure what Pipeworx can do, and it explains the distinction between this tool and the meta-tools it teaches.

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: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also names the meta-tools (ask_pipeworx, entity_profile, compare_entities, etc.) as related alternatives and explains the optional parameter usage (no args for full spread, topic to focus). This clearly signals when to choose this tool over others.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, which convey a safe, read-only, idempotent operation. However, the description adds no additional behavioral context (e.g., what data is returned, whether external APIs are queried, or any limitations). It does not contradict the annotations but also doesn't enhance 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 concise at four words, but it is under-specified rather than appropriately scoped. It lacks a verb and fails to convey essential purpose information. While not verbose, it sacrifices clarity for brevity, making it less effective than a slightly longer but more informative 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?

The tool has one parameter and an output schema, but the description provides no context about what taxonomy information is returned, how the species parameter should be formatted, or what taxonomic database is used. The description is too sparse to be considered complete even for a simple single-parameter tool, and the output schema is not visible to the agent in this 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 but does not. The word 'Species' in the description weakly hints at the 'species' parameter, but the schema already provides the parameter name, type, and examples ('human', '9606'). The description adds no clarification on accepted formats or meaning beyond the schema, leaving the agent to infer from the bare examples.

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

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

The description 'Species taxonomy info' is a vague noun phrase with no verb. It does not state what operation is performed (e.g., lookup, search, retrieve) and does not distinguish the tool from siblings like 'metadata' or 'entity_profile' which could also provide taxonomic data.

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

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

There is no guidance on when to use this tool versus alternatives, no context on prerequisites, and no mention of acceptable input formats (e.g., common name vs. taxonomy ID). The description merely states the topic, leaving the agent to guess the intended use case.

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: it discloses that ownership is enforced, that the row is deactivated (not deleted), and that historical events remain accessible via recent_alerts. These are significant behavioral traits that annotations alone do not convey, and they are not contradicted by the annotations.

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

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

The description is two sentences, front-loaded with the action, and every sentence adds necessary context: what it does, ownership rule, and the deactivation behavior. There is no wasted verbiage.

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, idempotent, non-destructive cancellation tool with no output schema, the description is complete. It explains the side effect (deactivation), ownership constraint, and data retention, which are the key behaviors an agent needs to know. No critical information 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?

Input schema coverage is 100%, with the 'id' parameter described as 'Subscription id (uuid) returned by subscribe.' The description merely repeats 'by id' without adding further semantic detail. Per the rubric, high schema coverage yields a baseline of 3, and no additional value is provided here.

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 'Cancel a subscription by id,' a specific verb and resource that clearly states the tool's function. It distinguishes from siblings like 'subscribe' (create) and 'list_subscriptions' (list) by focusing on cancellation, and further distinguishes the behavior by clarifying the row is deactivated rather than deleted.

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 this tool: when you need to cancel a subscription. It provides context about ownership enforcement and the deactivation behavior, which guides usage. However, it does not explicitly mention alternatives or exclusion criteria, though the sibling list makes the use case implicitly clear.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds meaningful behavioral context: the exact percent-delta math for financial claims, the fall-through for any other claim, verbatim evidence grounding, and the list of possible verdicts. This goes beyond the annotations and helps the agent predict behavior.

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

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

The description is long but densely informative, with front-loaded purpose followed by trigger examples and operational details. The list of seven trigger phrases is somewhat repetitive but useful for intent matching. Overall, every sentence contributes to understanding the tool's role, though it could be tightened 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?

Given the tool's complexity (two processing paths, tolerance handling, multiple verdicts) and no output schema, the description fully addresses return values (verdict types, actual value with citation, reasoning) and workflow. It also explains how it replaces multi-step calls, providing complete operational context 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% — both 'claim' and 'tolerance_pct' are described in detail within the schema, including examples and tolerance behavior. The main description adds no extra parameter-specific meaning beyond mentioning 'exact percent-delta math', so a baseline score of 3 is appropriate; it doesn't need to compensate for schema gaps.

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

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

The description clearly identifies the tool as a natural-language claim verification tool with specific trigger phrases ('Is it true that…', 'fact check', 'verify the claim that…'), and distinguishes it from sibling tools by detailing the two processing paths (SEC EDGAR for financial claims, grounded pipeline for other claims). It also states the concrete return value (verdict, actual value with citation, reasoning), making the purpose unambiguous.

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

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

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct' and elaborates on when the structured vs grounded path applies. It also notes that the tool replaces 4–6 sequential calls, providing clear context for when this is the right choice among siblings. No explicit alternative names, but the trigger phrases and scope effectively guide usage.

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