translate

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

Annotations already declare read-only and non-destructive behavior. The description adds valuable context about external calls (Workers AI free default, Anthropic BYO key with direct billing), and the per-model return structure. It does not describe rate limits or failure modes, but these are less critical given the strong annotation coverage.

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 purpose and output, then efficiently covers model options, billing, return format, and use cases. No wasted words; every clause earns its place.

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

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

The tool has 4 parameters, no output schema, and moderate complexity. The description covers the return structure (per-model fields + combined view), the default model, the optional key, and the use cases. It doesn't explain 'signals' in detail or address rate limits, but for a read-only probe with good annotations, it is sufficiently complete.

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

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

Schema coverage is 100%, providing a baseline of 3. The description goes beyond the schema by explaining the default model, the conditionality of `_apiKey` (only needed if 'anthropic' is in models), and the output format per model. This added meaning justifies a 4.

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

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

The description clearly states the verb ('Probe one or more LLMs'), the resource (what they know about an entity), and the output (visibility score 0-100). It is specific and distinguishes itself from obvious read-only tools, but does not explicitly differentiate from sibling 'scan_competitor_ai_presence' which may overlap in use case.

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

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

The description provides clear usage context: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not, however, state when not to use it or mention alternatives, so it falls just short of a 5.

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

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

Annotations already convey readOnly, open-world, idempotent, and non-destructive behavior. The description adds meaningful context by revealing that the tool routes to sub-tools, fills arguments, and returns a structured answer with stable citation URIs. Minor limitations exist—such as not describing latency or exact result shape—but the disclosure is strong given the annotations.

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

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

The description is long but front-loads the most important guidance ('PREFER OVER WEB SEARCH'), then moves through supported domains, trigger phrases, examples, and sibling alternatives. There is slight redundancy between 'START HERE' and 'default entry point', and the example list could be trimmed, but the structure remains efficient for the amount of routing information conveyed.

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 covers what the tool accepts, what it does internally, what it returns, when to use it, and when to choose alternatives. For a broadly applicable factual-question router, the agent has everything necessary 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?

The schema already documents all parameter aliases at 100% coverage, so the baseline is 3. The description adds trigger examples and says the question is in natural language, but it does not add substantial parameter-level meaning beyond what the schema already states. It is sufficient, not exceptional.

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 names the tool as a default question-routing tool that maps natural-language questions to 5,798 tools across 1,517 sources and returns structured answers with pipeworx:// citations. It also distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, so an agent can tell exactly what this tool does.

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

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

The description explicitly says to prefer this tool over web search, gives trigger phrases, provides concrete examples, and names alternatives with selection criteria: ask_pipeworx_grounded for a single verifiable answer, deep_research for broad multi-part questions, and live news routing for breaking-news queries. This is excellent routing guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds what annotations cannot: the tool's behavior is volatile — 'candidate routing improvements enabled live whenever one is under test' — and it currently 'matches ask_pipeworx exactly' after the last candidate was retired on 2026-07-26. This proactive disclosure of live-changing behavior and experimental status is exactly the kind of context an agent needs, and it contradicts nothing in the annotations.

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

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

Four sentences, each carrying distinct information: identity/scope, current state, usage condition, and functional-completeness reassurance. It is front-loaded with the most important fact (experimental twin of ask_pipeworx) and wastes little. The dated retirement detail (2026-07-26) is precise but will age, and the description is slightly dense for a beta alias tool.

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

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

For a tool with one required string parameter, no output schema, and rich annotations, the description covers identity, current behavior, usage, and response shape by reference ('same response shape' as ask_pipeworx). The pointer to ask_pipeworx's response shape is a reasonable substitute for a missing output schema. Nothing an agent needs to decide whether and how to call it is missing.

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

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

Schema description coverage is 100%, so every parameter (question plus aliases q, text, input, query, prompt) is already documented as an 'Alias for question.' The description adds only 'same arguments' as a cross-reference to ask_pipeworx, which is marginal but consistent with the schema. With full schema coverage the 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 opens by naming the tool as a 'Beta version of ask_pipeworx' and defines it as a 'universal router' with 'same 5,798 tools, same arguments, same response shape,' making the verb+resource+scope explicit. It clearly differentiates from siblings by positioning this as the experimental edge ('candidate routing improvements') versus the stable ask_pipeworx and the separate ask_pipeworx_grounded. An agent can distinguish this tool from all 34 siblings from the first sentence alone.

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 an explicit selection condition: 'Use it exactly like ask_pipeworx when you want the newest routing,' which tells the agent when to prefer this over the stable sibling. It also explains the evaluation context ('results are compared against the stable router to decide what merges'), reinforcing that this is the experimental alternative. It stops short of an explicit when-not-to-use clause, but the condition implies the stable ask_pipeworx is the default for normal routing.

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 readOnly/idempotent annotations by disclosing the exact success return shape, the explicit refusal contract with all possible refusal_reason values, and the extra LLM call cost. It also explains the grounding constraint (uses ONLY the tool result). 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 dense and front-loaded with the core purpose. Each major section earns its place: the routing context, the return contract, the refusal contract, usage guidance, and cost comparison. It is slightly long but justified given the behavioral complexity it must convey.

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

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

The description provides everything needed to invoke and interpret this tool correctly: what it does, how it differs from the sibling, when to use it, what success and refusal look like, and the performance cost tradeoff. Since there is no output schema, the return contract in the description is essential and well 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?

Schema description coverage is 100%, and the schema already documents that all six parameters are aliases for a natural-language question. The description adds no additional parameter semantics beyond confirming the tool 'fills arguments' during routing, which is not about caller-provided parameters. Baseline 3 is appropriate because the schema carries the full burden.

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

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

The description clearly identifies this as a hallucination-resistant answer mode that routes like ask_pipeworx but extracts answers only from tool results. It explicitly names the resource, the behavior, and the key differentiator from the sibling ask_pipeworx. The distinction is concrete and actionable.

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

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

It explicitly states when to use this tool: when answers will be quoted, cited, or acted on and facts must not be invented. It also gives a clear preference rule: prefer ask_pipeworx for casual lookups because this mode costs an extra LLM call. This is strong, direct usage guidance with an explicit alternative.

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

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

The description goes far beyond the annotations by detailing internal behaviors: the resolver contract (match_confidence, match_score, alternatives), fan-out to specific data packs, safety short-circuits (low_confidence_match, market_closed_or_inactive), wide-spread tradeability warnings, and cancellation-rule parsing. It also discloses that closed markets may surface via low_confidence_match and that both routes are blocking. This is exceptionally transparent for a read-only tool.

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

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

The description is long but well-organized with clear section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.). Every sentence provides useful detail, and it is front-loaded with a concise opening. The length is justified by the complexity of the tool, though a slightly tighter structure would be even better.

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

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

With no output schema, the description fully explains the return structure: result.market, result.analysis, result.evidence, result.parent_event, news fields with fallback info. It also covers edge cases like low-confidence matches, closed markets, wide spreads, and cancellation-rule risks. For a complex data-fan-out tool, this is a comprehensive and complete description.

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

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

The schema already covers 100% of parameters with descriptions, giving a baseline of 3. The description adds extra semantic value by explaining how the 'market' parameter is resolved (slug, URL, or question text) and the consequences of depth (fan-out extent) and include_raw (response size under ~20KB vs 50-500KB). This enhances parameter understanding beyond the schema.

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

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

The opening sentence clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb (research), resource (Polymarket bet), and mechanism (fan-out to data packs). The description also lists concrete use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'), distinguishing it from sibling tools like polymarket_edges or deep_research.

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

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

The description provides explicit usage guidance with 'Use for...' examples, telling agents when to invoke this tool for bet-related research. It also explains the one-call fan-out behavior, which differentiates it from more manual alternatives. However, it does not explicitly mention when not to use this tool or name alternative tools for different scenarios, so it falls short of a 5.

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

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

Adds substantial behavioral detail beyond the readOnlyHint annotation: pulls latest 10-K data, handles off-calendar fiscal years, sorts results by primary metric, and returns paired data with citation URIs. This enriches the agent's understanding of execution 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 dense but every sentence contributes: trigger phrases, comparison scope, preference rule, data details, sorting, and output. It is front-loaded with the core purpose and efficiently packs secondary details without redundancy.

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

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

Even without an output schema, the description covers the return format (paired data + pipeworx:// URIs) and data source specifics. For a 2-parameter tool with rich annotations, this is sufficient for confident invocation.

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

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

The description significantly enhances the parameters: it explains the 'type' enum values with concrete data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs) and provides examples for the 'values' parameter format. With 100% schema coverage, this extension is valuable.

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

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

The description clearly states the tool performs side-by-side comparisons of 2–5 companies or drugs in a single parallel call, with explicit trigger phrases ('X vs Y', 'rank these companies'). It distinguishes itself from sibling tools by emphasizing 'ALWAYS PREFER over sequential single-pack lookups when comparing 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?

Provides explicit when-to-use guidance via trigger phrases and a strong directive to prefer this over sequential lookups. It also details what each type ('company' vs 'drug') retrieves, giving clear context for 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 already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description goes far beyond: it discloses account and plan requirements, parallel decomposition across 5,798 tools, gap reporting with gaps[], never-invented behavior, hop semantics, citation_uri resolvability, contradictions[], semantic excerpting, and expected latency. This is rich behavioral context that structured annotations alone would 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 prerequisites and routing guidance front-loaded. No sentence is filler, though the density and heavy parentheticals make it harder to parse than ideal. It earns its length given the tool's complexity, but is not as cleanly structured as it could be.

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

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

With no output schema, the description compensates thoroughly: findings packet contents, confidence/source/fetched_at fields, stable citations, gaps[], contradictions[], hop field, and latency are all described. Auth requirements, alternative routing, depth tiers, and scope boundaries are also covered. An agent has enough context to select and invoke this tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful detail beyond the schema: depth 'thorough' requires a paid plan, depth behaviors are tied to hop counts and gap recovery, and question accepts broad/multi-part natural language. This exceeds baseline but the schema already does substantial work.

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

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

The description states a specific verb and resource: grounded multi-source research across 1517 structured data sources in one call. It also explicitly distinguishes itself from open-web search and names the sibling ask_pipeworx as the alternative for single lookups, so an agent can tell it apart without opening schemas.

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

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

The description gives explicit when-to-use guidance: broad/multi-part questions over structured data, with examples. It also provides clear exclusions: if not signed in, use ask_pipeworx instead; for a single lookup, use ask_pipeworx. Depth tiers are mapped to behaviors, so an agent can choose appropriately.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds the return format (array with confidence scores), which is useful behavioral detail beyond the annotations. No contradictions.

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

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

Two sentences, front-loaded with the core action, no unnecessary words. Excellent 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?

For a simple one-parameter tool with an output schema and strong annotations, the description provides the essential behavior and return information. Nothing more is needed.

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

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

Schema coverage is 100% with the 'text' parameter described as 'The text whose language should be detected'. The description only repeats this, adding no additional semantic detail, so the baseline 3 applies.

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

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

The description uses a specific verb ('Detect') and resource ('language of a text string'), clearly distinguishing it from siblings like translate and list_languages. The scope is unambiguous and matches the tool name.

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 context of use is clear: when you have a text and need to identify its language. However, it does not explicitly mention alternatives or exclusions, so it falls short of a 5.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral context by disclosing the return format (top-N tools with names, descriptions, full input schemas, curated examples) and that results are directly callable without a second lookup. This 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?

Purpose is front-loaded in the first sentence. The domain list is lengthy but directly supports usage guidance, and the output format is explained in a single, information-dense sentence. Slightly verbose but effectively structured, and every part 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?

The description covers purpose, usage conditions, return format, and actionable guidance. It also explains what results look like in the absence of an output schema. Combined with a thorough input schema and safety annotations, it is sufficiently complete for a discovery tool. Missing only edge-case details like ranking methodology, which are not essential.

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

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

Schema description coverage is 100%, with all parameters and aliases thoroughly documented. The description does not add significant meaning beyond the schema's parameter descriptions; it only reiterates that query is a natural language description. Baseline 3 is appropriate because the schema carries the parameter burden.

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: 'Find tools by describing the data or task.' It lists supported domains and explicitly positions itself as a tool-discovery meta-tool, distinguishing it from sibling tools that perform specific tasks. The instruction to 'Call this FIRST' further reinforces its unique role.

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

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

Provides clear when-to-use guidance: browse, search, look up, or discover tools, and 'Call this FIRST when you have many tools available'. It also hints at a when-not-to-use condition ('not just one answer'), but does not explicitly name alternative tools or exclusions, preventing a top score.

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 readOnly/openWorld/idempotent annotations: it discloses the full fan-out across SEC EDGAR, XBRL, USPTO, USAspending, Purple Book, DOL LCA, news, and GLEIF; explains soft-fail behavior for the USPTO sunset; notes that empty fda_products is expected for certain companies; and clarifies that sources_used/sources_failed distinguish real no-data from bugs.

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 the length is earned by the tool's complexity: it front-loads user intents, states the core behavior, then compactly enumerates return sections with semicolons. The structure is dense and scannable, though a bit of repetition around accepted value shapes could be trimmed.

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

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

With no output schema, the description must carry the burden of explaining return values, and it does: it enumerates cik/company_name, recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI, and sources_used/sources_failed. It also explains edge cases like private companies, empty sections, and input resolution, so an agent has enough context 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%, so the baseline is 3, but the description adds meaningful semantics beyond the schema: it gives concrete ticker/CIK/name examples, requires zero-padded CIKs, explains name resolution via SEC EDGAR, and clarifies that type accepts 'company' or 'ticker' interchangeably. This is a clear enhancement, though the schema already covers the basic types.

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 direct user intents ('Tell me about X', 'research Acme', 'brief me on Tesla') and then states a specific, high-value purpose: a full cross-source profile of a US public company in one parallel call. It also differentiates itself from chaining single-pack SEC/XBRL/news lookups, so an agent can tell what this tool is for.

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

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

The description explicitly instructs 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' giving the agent a clear when-to-use rule. It also covers the private-company fallback and the expected 'no data' behavior, helping the agent choose this tool appropriately.

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 annotations already declare destructiveHint=true, and readOnlyHint=false, so the agent knows it's destructive. The description adds context by stating the deletion purpose and the kind of data (memories, sensitive data), which goes beyond the annotations. It doesn't mention irreversibility or missing-key behavior, but the idempotentHint covers safety.

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

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

The description is two sentences, front-loaded with the action, and includes usage guidance without unnecessary verbosity. Every sentence earns its place.

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

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

For a simple delete-by-key operation, the description is complete: it states the action, key usage, when to use, and companion tools. Annotations cover safety. The lack of output schema is acceptable for a deletion tool. Minor missing detail is the behavior on missing keys, but idempotentHint implies tolerability.

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 'key' ('Memory key to delete'), so the schema already provides full meaning. The description only says 'by key', adding no additional detail beyond the schema. 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', which is a specific verb (delete) and resource (memory). This distinguishes it from sibling tools remember and recall, making its purpose unambiguous.

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

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

It explicitly provides usage guidance: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier. Pair with remember and recall.' This tells the agent when to use the tool and mentions companion tools, satisfying the 'when vs alternatives' requirement.

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

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

Annotations already declare the tool as read-only, open-world, idempotent, and non-destructive. The description adds valuable behavioral context by revealing that the tool 'fetches the page' (external network request) and emits a 'single text blob' as output. This goes beyond the annotations without contradicting them.

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

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

The description is concise and front-loaded, with two clear sentences followed by a bulleted 'Useful for' list. Every sentence adds value, and the structure makes the tool's purpose and use cases immediately 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?

For a tool with only two parameters, no output schema, and comprehensive annotations, the description covers the core functionality, workflow, output format, and use cases. It could add notes about network dependency or error handling, but the current content is sufficient for effective tool 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?

The input schema already fully describes both parameters with 100% coverage. The description adds no additional parameter-specific meaning beyond what the schema provides, so it meets the baseline of 3 for high schema coverage.

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

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

The description clearly states a specific action ('Generate a production-ready llms.txt file for any URL'), the exact output ('standard llms.txt markdown format'), and the process ('Fetches the page, extracts title/description/key links'). It uniquely identifies the tool among siblings by focusing on llms.txt generation, and the use cases distinguish it from related tools like scan_competitor_ai_presence.

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

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

The description explicitly lists three 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.' This provides clear context for when to use the tool, though it does not explicitly mention when not to use it or name alternative tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds that it returns language codes and names, but this is likely redundant given the output schema exists. No contradiction with annotations; however, no additional behavioral context is disclosed.

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 concise sentences: first states the action and scope, second states the return content. Every word earns its place, with no redundancy or unnecessary detail.

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

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

For a simple listing tool with zero parameters, an output schema, and robust annotations, the description is complete. It accurately communicates the tool's purpose and output, and no further context is needed.

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 there is nothing to document. The description correctly omits parameter details, and the baseline score for a no-parameter tool is 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 the specific verb 'List' and identifies the resource as 'all languages supported by the translation API'. It clearly distinguishes from sibling tools like 'translate' or 'detect_language' by specifying the tool's unique output of language codes and 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?

The description implies usage when one needs the full set of supported languages before using translation or detection tools, but it does not explicitly state when to use or not use this tool versus alternatives. No exclusions or alternative tool mentions are provided.

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. The description adds behavioral insight by specifying that it lists only the caller's subscriptions and by enumerating the returned fields (id, type, params, created_at, last_fired_at, fire_count), which is useful context beyond the annotations.

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

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

The description is three concise sentences with no wasted words. It front-loads the core purpose and then efficiently adds return-value details and usage 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?

For a simple read-only list tool with one optional parameter, the description covers the purpose, the returned fields, and the intended use case. The output schema is absent, but the description explicitly lists the output fields, making the tool sufficiently complete without needing to over-explain.

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 the include_inactive parameter already documented as 'Include cancelled subscriptions in the response (default false).' The description does not add additional meaning to the parameter beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description uses the specific verb 'List' and clearly identifies the resource as 'the caller's active subscriptions,' which unambiguously distinguishes it from sibling tools like subscribe and unsubscribe. It also lists the returned fields, making the tool's 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 provides clear usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to invoke the tool, though it does not explicitly name alternative tools or state when not to use it.

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

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

Annotations are all false, so the description adds critical context: rate-limited to 5 per identifier per day, free (doesn't count against quota), and the claim_token workflow. While it doesn't detail data retention or internal handling beyond "team reads digests daily," it covers the key operational behaviors.

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 adds necessary information for correct usage. It is slightly long, but the complexity of the tool (claim_token, rate limits, scope) justifies this length. The structure flows logically from purpose to exclusions to mechanics.

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

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

Despite having no output schema, the description fully explains the claim_token return behavior and how to check resolution status. It covers required context: what counts as relevant feedback, how to scope it, rate limits, and the follow-up mechanism. No significant gaps remain.

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

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

The schema already provides 100% coverage of parameters, so baseline is 3. The description adds value by explaining the claim_token lifecycle (filing without an account returns a token, pass it back later to read status) and by clarifying the message should be specific but not include end-user prompts. This supplement goes beyond the schema.

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

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

The description clearly states the tool's purpose: "Tell the Pipeworx team something is broken, missing, or needs to exist." It lists specific feedback types (bug, feature/data_gap, praise) and emphasizes it applies only to tools from this Pipeworx connection, distinguishing it from sibling tools like ask_pipeworx or bet_research.

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

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

Provides explicit when-to-use guidance (bug, feature, data_gap, praise) and when-not-to-use (if tool is from a different MCP server). It even gives a heuristic: "Not sure? Pipeworx tool names are the ones this connection lists" and clear instructions on what to include/exclude (don't paste end-user's prompt).

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

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

Annotations already declare read-only, idempotent, and open-world hints, but the description goes further by disclosing that the signal is self-aggregated from a specific analytics engine, that no PII is included (only pack, tool, count), and that caching varies from 5 minutes to 1 hour depending on the selected window. This adds meaningful behavioral context beyond the structured annotations.

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

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

The description is compact yet information-dense. It front-loads the core purpose, then uses a numbered list for use cases, and finishes with the aggregation source, privacy note, and caching detail. Every sentence serves a purpose without bloat, making it easy for an agent to parse and act on quickly.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description is comprehensive. It explains what results are returned, why the metric is useful, how it is derived, what data is excluded (PII), and that results are cached. This fully equips an agent to decide when and how to invoke the tool without additional lookups.

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

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

The input schema already documents the single optional 'window' parameter with enum values and a clear description, so schema coverage is 100%. The tool description adds extra semantics by linking cache duration to the window choice ('Cached 5min-1h depending on window'), which is not present in the schema and helps agents reason about freshness expectations.

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, engaging question ('What other AI agents are calling on Pipeworx right now') and immediately specifies the exact returns: top tools, top packs, and total call volume over a 24h/7d/30d window. This makes the tool's purpose unmistakable and clearly distinguishes it from sibling discovery tools like discover_tools, which focus on catalog discovery rather than popularity signals.

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

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

The description provides explicit use cases via a 'Useful for' list: discovering hot data sources for current events, confirming a canonical tool before asking a question, and checking alignment with common agent needs. It clearly states when to use the tool but does not mention when not to use it or name alternatives, so it falls short of the top mark.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description adds extensive behavioral context: the SEMANTIC ANCHOR with Jaccard threshold, PARTITION FILTER with placeholder fraction, response structure, and the FILL CHECK that compares theoretical vs realizable edge at the CLOB depth. It clearly discloses a limitation and warns against trading when realizable edge is ≤ 0. 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 section earns its place. It is well-structured with clear labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded with the primary purpose and mode selection. No fluff or redundancy; it packs a large amount of critical detail into a scannable format.

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 of this complexity (three modes, custom filters, output shape, fill-check caveat), the description covers everything needed for correct invocation and interpretation. It describes the return fields, explains the internal checks, and includes safety guidance. Given no output schema, the description carries the full burden and succeeds.

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

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

Schema coverage is 100% with descriptions for both `event` and `topic`, but the tool description significantly enriches semantics. It provides example slugs ('fed-decision-may-2026'), explains the single-event vs cross-event distinction, and clarifies that `event` is recommended for a specific market while `topic` catches cross-event patterns. This goes well beyond the baseline schema descriptions.

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

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

The description opens with a specific and clear statement: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' This identifies the exact action (find arbitrage), resource (Polymarket), and methodology, making the tool's purpose unambiguous. It also differentiates from siblings like polymarket_fill_risk by pointing to it for custom sizing.

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, actionable usage instructions: 'Call with NO args for a `trending_scan`... pass `event`... or `topic`.' It gives concrete examples of event slugs and topic queries, explains when to use each mode, and even tells the agent 'do not trade it' when the fill check yields realizable_edge_pp ≤ 0. It also names an alternative tool for custom sizing, satisfying the when/when-not/alternatives criterion.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description does not contradict them. It adds extensive behavioral detail: edge is computed net of slippage, Kelly is capped at 0.25, there's a 24h-move warning, placeholder-slug filters, diagnostics counters, and 1h KV-level caching. This goes far 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 long but every sentence earns its place. It is front-loaded with the core purpose, then organized into segments, knobs, response structure, diagnostics, and caching. Each section is clearly labelled and dense with actionable details, making it appropriately concise for the tool's complexity.

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

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

With no output schema, the description compensates thoroughly: it explains top-level response fields (by_segment, fed_candidates/fed_note, _diagnostics), what diagnostics show (funnel counters, filter_skips), and why segments can be empty. It also covers caching and the Fed signal caveat, leaving no major gaps 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?

Though the schema covers 100% of parameters, the description adds substantial meaning: it groups knobs into 'tradeable-edge' filters, explains min_partition_leg_kelly's unusual per-leg behavior, and details why slippage_pp matters (no trading fees but 20-50bp book walking). This enriches the schema baseline.

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

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

The description opens with a specific verb+resource+outcome: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly positions the tool for 'what should I bet on today' and distinguishes it from manual market browsing ('without paging hundreds of markets').

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, including the intended discovery use case and guidance on when to adjust knobs (e.g., min_liquidity, max_spread_pp as 'tradeable-edge filters'). It also warns about the Fed signal being unreliable and notes the rare-by-design nature of concentrated longshots. However, it does not explicitly contrast with sibling tools like polymarket_arbitrage or edge_tracker, so alternatives are only 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 mark it read-only, open-world, idempotent, and non-destructive. The description adds significant behavioral context: snapshot TTL (60 days), cache-miss-driven gaps, daily-close calculation for decay, sign convention for edge_pp_net, and response structure. No contradiction with annotations.

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

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

The description is front-loaded with the core question, then organizes args, response fields, and limits. It is dense and well-structured, though the rhetorical example ('wide for a reason nobody is willing to take') and some extra prose add length without carrying essential information.

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

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

With no output schema, the description fully explains return values (tracked[], expired[], snapshot_dates[]), their semantics, and important caveats like TTL limits and data gaps. This is complete for a 2-parameter read-only tool.

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

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

Schema coverage is 100% with descriptions for both parameters. The description restates defaults ('default 14, max 30', 'default 1wk') and adds the phrase 'snapshot family' but does not meaningfully extend what the schema already provides. Baseline 3 applies.

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

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

The description clearly identifies the tool as 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and states the exact question it answers ('how long has this edge existed and is it shrinking?'). This distinguishes it from sibling polymarket_edges (the snapshot source) and other market 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?

Usage context is clear: use it to assess edge longevity and decay, with a concrete example comparing a fresh wide edge to a 3-week-old one. However, it does not explicitly name alternatives or state when not to use this tool, so it misses the 'explicit when-not/alternatives' bar.

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?

With readOnlyHint, openWorldHint, idempotentHint, and destructiveHint already provided, the description adds substantial behavioral context beyond annotations. It explains how the tool 'walks the ladder', interprets size_usd differently per mode, returns specific fields like 'vwap_fill_price' and 'verdict', and warns about 'forced_directional_risk' and 'partial basket fills'. No contradiction with annotations.

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

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

The description is front-loaded with the core purpose and then uses clear section labels ('SINGLE-MARKET', 'BASKET') for structured reading. It is quite long, but nearly every sentence adds critical detail. The only minor issue is that some explanatory content (e.g., 'the dominant loss mode in real arb-bot P&L') could be trimmed without losing essential usage information.

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

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

Given the tool's complexity (two modes, multiple parameters, and no output schema), the description is remarkably complete. It enumerates key return fields for both modes, including 'top_of_book', 'slippage_pp', 'thin_legs[]', and 'max_clean_notional_usd'. It also covers risk scenarios such as partial fills and unhedged positions, making the agent fully informed.

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

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

Even though schema coverage is 100%, the description significantly enriches parameter meanings. For instance, it clarifies that size_usd is 'max spend on buys, target proceeds on sells' in single-market mode and 'settlement notional S (shares per leg)' in basket mode. It also explains side defaults and clamping behavior (10–1,000,000), 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 clearly defines the tool as a 'realizable-vs-theoretical edge check against live CLOB order-book depth,' which immediately communicates its function. It further distinguishes itself from sibling tools by explicitly stating to use it 'before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.'

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, directly naming the sibling tools and the threshold condition. It also delineates two modes ('single-market mode' vs 'basket/partition mode') and explains when each is applicable, including the default auto behavior for basket side. 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 mark the tool read-only, idempotent, and non-destructive, so the safety burden is low. The description goes well beyond that by disclosing the fee asymmetry, the gross-vs-net caveat, the meaning of compatibility codes, the unclassified-legs behavior, and the fact that pairings are unverified keyword matches. This is especially valuable because there is no output schema.

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

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

The description is long, but it carries a large amount of non-obvious behavioral detail that is directly relevant to safe and correct invocation. It is front-loaded with the core purpose and mode distinction before diving into caveats. A few sentences could be tightened, but the length is largely justified by the tool's complexity.

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

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

Given no output schema and a complex cross-venue comparison tool, the description is remarkably complete: it explains response fields, safety fields, compatibility codes, per-entry flags, skipped-leg counters, fee assumptions, and the meaning of null temporal alignment. An agent can form an accurate mental model of what will happen and how to 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%, so the baseline is 3. The description adds meaning by explaining that topic is a pre-mapped shortcut, that explicit parameters override the mapped sides, and that both modes invoke the identical token-overlap matcher. It also enumerates the ten topic values in context, which helps an agent select the right mode.

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

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

The description opens with a clear statement of what the tool computes: cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from likely siblings by naming both venues and the concept of matching equivalent bet shapes, though it does not explicitly compare itself to polymarket_arbitrage or polymarket_edges.

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

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

The description gives explicit usage modes: topic shortcuts versus explicit kalshi_event_ticker and polymarket_event_slug, and states both run the same matcher. It also provides practical guidance like 'pre-mapped ≠ tradeable' and cautions that real cross-venue spreads are rarer than the shortcut list suggests. It does not explicitly discuss when to choose this tool over its named siblings.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description aligns with these. The description adds valuable context beyond annotations by disclosing scoping: 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID).' It also explains the dual behavior (retrieve vs. list all) which is not obvious from annotations. Minor missing details like error behavior for unknown keys prevent a perfect score, but the addition of scoping is a strong transparency plus.

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

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

The description is three sentences, each with a distinct purpose: action and alternation, usage scenario, and scoping/relationship to siblings. It is front-loaded with the primary verb and resource, contains no redundant or filler content, and every sentence adds critical decision-making information. This is exemplary 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?

For a simple tool with one optional parameter and no output schema, the description is complete. It covers the action, when to use it, scoping, and how it relates to remember/forget. The absence of return-value details is acceptable given the tool's trivial return types (a value or a list of keys) and the lack of an output schema. An agent has sufficient information to invoke the tool correctly in all expected scenarios.

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

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

The schema already covers the sole parameter (`key`) with 100% description coverage, so the baseline is 3. The description adds semantic richness by providing concrete examples of key values ('user's target ticker, an address, prior research notes') and restating the omit-to-list behavior. This helps the agent understand what keys are meaningful and reinforces the optional nature of the parameter, going slightly beyond the schema's terse description.

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

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

The description clearly states the tool's core function: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It uses specific verbs and identifies the resource (saved memory), and explicitly differentiates from sibling tools by naming remember and forget. The examples of stored context (target ticker, address, research notes) further clarify its purpose.

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 guidance: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also explains when to use the alternative tools via 'Pair with remember to save, forget to delete,' clearly distinguishing the tool's role in the save/recall/delete lifecycle. This gives the agent actionable criteria for selecting this tool over siblings.

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

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

While annotations already indicate readOnlyHint=true, the description goes further by disclosing the optional mutation: 'Set mark_read:true to flag returned events read so the next call only shows newer ones.' It also reveals that events carry source, citation_uri, and raw payload, and explains the persisted feed nature. This adds critical behavioral context beyond the annotations without contradiction.

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

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

The description is five sentences, each earning its place: purpose, return payload, filtering, mark_read side effect, and alternative access method. It is front-loaded with the core action in the first sentence and contains no fluff or repetition. Ideal length for the tool's complexity.

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

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

Despite no output schema, the description clearly explains what each returned event carries (source, citation_uri, raw payload). It also covers the main use cases (filtering, polling with mark_read) and gives an external endpoint fallback. With 5 optional parameters and no required ones, the description provides enough context for an agent to invoke it correctly and understand 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?

The schema covers all 5 parameters with descriptions, so the baseline is 3. The description adds value by providing an example type ('sec_8k'), clarifying the since parameter as ISO timestamp, and explaining the state-changing effect of mark_read. It doesn't rehash limit or unread_only, but the schema already covers those; the added examples and side-effect explanation elevate it above baseline.

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

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

The description opens with a specific verb+resource: 'Pull fired events from your subscription feed.' It clearly distinguishes itself from siblings like list_subscriptions or recent_changes by focusing on fired events from the persisted feed, and even mentions the evaluator's role. This makes 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?

It explicitly provides an alternative: 'the same feed is also at GET registry.pipeworx.io/alerts.json for scripts and dashboards.' This tells agents when to use the tool (interactive polls) versus when to use the HTTP endpoint. It also gives filtering guidance with examples ('sec_8k') and explains the mark_read behavior for sequential polling.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds substantial behavioral detail beyond those: fans out to SEC EDGAR, GDELT→GNews fallback (GNews when rate-limited or 5xx), USPTO patents granted, PatentsView API sunset May 2025 causing soft-fail, and the return format (changes[] grouped by source + total_changes count + pipeworx:// citation URIs). No contradiction.

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

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

The description is front-loaded with user-intent examples, making it immediately clear what problem the tool solves. Every sentence earns its place: data sources, fallback behavior, date formats, return structure, and an alternative tool reference. Dense but efficiently structured without fluff.

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

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

Despite having no output schema, the description fully discloses the return shape (structured changes[] grouped by source, total_changes count, pipeworx:// URIs). It also explains the multi-source fan-out, failure modes (GDELT→GNews fallback, USPTO soft-fail), and a relevant constraint (PatentsView sunset). This is more than adequate for an agent to invoke and interpret results correctly.

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

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

Schema coverage is 100%, but the description adds meaning beyond the schema: it explains `since` accepts ISO date or relative shorthand with examples ('7d', '30d', '3m', '1y'), and `value` accepts ticker or zero-padded CIK. This clarifies format and usage that the schema only hints at.

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

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

The description opens with concrete example queries ('What's new with X', 'latest on Y') then clearly states it's a 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It explicitly names the resource (company change feed) and distinguishes from sibling entity_profile by stating when to use that instead.

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 triggers ('What's new with X' style questions) and an explicit exclusion: 'Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window.' Also notes the fallback chain (GDELT→GNews) and timeout behavior, which helps the agent choose appropriately.

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 valuable behavioral context beyond the annotations: it explains the key-value storage model, scoping by user identifier, and the persistence difference between authenticated users (permanent) and anonymous sessions (24 hours). It also mentions the pairing with recall/forget, which clarifies the full lifecycle. 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 four sentences long, front-loads the core purpose, and then layers usage examples, storage details, and sibling references. Every sentence provides distinct information 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 simple write tool with no output schema, the description covers everything needed: purpose, when to use, storage semantics, persistence behavior, and relationships with recall/forget. The tool's complexity is low, and the description is fully sufficient 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 covers both parameters with detailed descriptions (100% coverage), so the baseline is 3. The description adds extra value with a concrete example for the key format and clarifies that value accepts 'any text,' which helps agents formulate correct inputs. This goes slightly beyond the schema without over-explaining.

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 'save' with a clear resource ('data the agent will need to reuse later') and explicitly contrasts with sibling tools by naming 'recall' and 'forget'. This makes the tool's purpose unmistakable and differentiates it from other memory operations.

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

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

It provides explicit 'when to use' guidance with concrete examples (resolved ticker, target address, user preference, research subject). It also names the companion tools (recall, forget) as alternatives, though it does not explicitly state when *not* to use it. The context is strong enough to guide agent 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?

Beyond the read-only/idempotent annotations, the description discloses meaningful behaviors: graceful degradation when GLEIF/OpenFIGI is unavailable, returning figi_candidates when a name matches multiple instruments, explicitly reporting unresolved identifiers, labelling each identifier with its source, and ISIN-to-LEI mapping. None of this contradicts the annotations.

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

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

The definition is front-loaded with examples and the core 'use first' instruction, and every additional sentence provides substantive behavior. It is long and dense, making parsing harder, but for a tool with this much resolution behavior the length is largely justified.

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

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

With no output schema, the description carries the full burden of explaining what is returned: CIK, ticker, company_name, LEI plus ownership, FIGI, RxCUI, ingredient, brand, and a pipeworx citation. It also covers ambiguity, unresolved identifiers, source labelling, and degradation, so an agent has enough context 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?

Although the schema already describes both parameters, the description adds high-value usage constraints: pass only the entity name, never the question's full noun phrase, with a concrete bond example that explains why trailing security-class words fail. It also enriches the type parameter by clarifying what each type accepts (ticker/CIK/ISIN/company name versus brand/generic drug name), going well beyond the schema's one-line enum 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 opening sentence pairs a specific verb ('resolve') with a clear resource ('user-spoken NAME to canonical/official identifiers') and precedes it with concrete query examples. The supported types section distinguishes it from generic lookup tools by listing exactly what identifiers it returns for companies and drugs.

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

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

It explicitly states 'Use FIRST whenever you have a name but need an ID,' which tells an agent when to choose this tool. It also notes that the tool replaces 2-3 manual lookups, reinforcing its role as the front-door resolver. However, it never names sibling alternatives or states when not to use it, so the guidance is strong but not exclusionary.

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?

Discloses that it probes each entity with ai_visibility_check and returns a ranked list with score, confidence, and signal density—useful behavior beyond the readOnly/idempotent annotations. It does not address potential edge cases or failure modes.

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

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

Three sentences, front-loaded with purpose and mechanism, with no wasted words. Every sentence adds value.

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

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

Covers purpose, mechanism, use case, and return format, and schema/annotations fill in parameter and safety details. Missing explicit exclusions or failure handling, but adequate for this complexity.

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

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

Schema coverage is 100%, so the schema already documents all four parameters. The description adds only contextual meaning ('your brand + N competitors') but no new syntax or 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?

Clearly states the tool compares AI visibility across multiple entities side-by-side, distinguishing itself from ai_visibility_check by referencing it as the underlying probe and adding ranking/surfacing behavior. The verb 'Compare' and resource 'AI visibility' are specific.

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

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

Provides a clear use case: competitive AI-marketing audits, with an illustrative question. It implies using this tool when comparing multiple entities vs. single checks, but does not explicitly mention alternatives or when-not-to-use.

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

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

Discloses substantial behavior beyond the readOnly/openWorld/idempotent annotations: it fans out to two external services, includes both license/advisory and bundle-size data, returns a specific summary block and per-advisory details, degrades gracefully on partial failure, and calls out the 5-30s first-measurement timeout. 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 dense but every sentence earns its place: composite purpose, use cases, return contents, ecosystem scope, and timeout/failure behavior. It is front-loaded and structured appropriately for a complex multi-source tool.

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

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

With no output schema, the description fully carries the burden of explaining the return value, and it does so with a field list, per-advisory detail, links, and alternative versions. It also covers failure modes, ecosystem limits, and timing behavior, making it complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add parameter-level semantics beyond the schema; it mentions package names and versions only in the context of outputs and limitations, not additional syntax or format details.

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 ('Composite check whether to add this npm package') and clearly distinguishes itself from siblings by naming the underlying sources (deps.dev and bundlephobia) and the question it answers. It is far more specific than the generic title.

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".' It also gives an exclusion/alternative: NPM-only in v1, with PyPI/Maven/Cargo/Go falling under deps.dev:version directly.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description discloses key runtime behaviors: returns top-N passages with offsets and similarity scores, truncates inputs over 200K chars with a flag, and uses specific embedding settings (BGE-base-en, cosine, overlapping windows). This materially helps the agent understand what to expect.

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

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

The description is compact but information-dense. The first sentence states the core function, the second gives usage context, the third explains the workflow pairing, and the final sentence covers technical constraints. Every sentence earns its place, and it is front-loaded with the most actionable information.

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

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

With no output schema, the description clearly explains the return format (passages, offsets, scores) and the verification use case. It also provides performance limits and suggests a sibling tool for end-to-end grounding. This gives the agent everything needed to decide when and how to invoke it.

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

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

The schema already provides 100% coverage for all 3 parameters with clear descriptions. The tool description adds useful real-world examples (SEC 10-K body, 'supply-chain risk') but no critical semantics that are absent from the schema, so it stays at the baseline.

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

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

The description opens with "Semantic search INSIDE a fetched record," which clearly identifies the verb and resource. It distinguishes this tool from siblings like ask_pipeworx by focusing on searching within user-provided text, and it explicitly mentions the companion tool ask_pipeworx_grounded to differentiate the workflow.

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?

"Use when the record is too big to cram into the prompt" provides a direct when-to-use. It also explains how it pairs with ask_pipeworx_grounded, offering an explicit alternative and integration path. No exclusions are needed since the scope is well-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 richly discloses behaviors beyond annotations: authentication requirements (Pipeworx OAuth account, anonymous/BYO cannot persist), delivery channel details (feed always on, email/SMS/webhook), constraints (SMS verification, 10/day cap), and webhook-specific nuances (signing secret returned once, auto-disable after 10 failures). This far exceeds the minimal safety info in annotations and provides substantial operational transparency.

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

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

The description is a single dense paragraph but well-organized: purpose, return, requirements, types with examples, and delivery channels with caveats. Every sentence adds useful operational detail, and the front-loading of the main action ensures key information appears early. Despite its length, it is efficient and structured for an agent to parse.

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

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

The description covers the return value, auth requirements, and most delivery details, which is necessary given no output schema. However, it omits two subscription types (patent_grant, clinical_trial) and the webhook channel from the prose, even though they appear in the schema. This creates a potential completeness gap where an agent might assume only the listed types/channels are available.

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

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

With 100% schema coverage, the baseline is 3, and the description adds valuable context: concrete examples for three of the five types, delivery channel constraints (phone verification, daily caps), and the prerequisite of an OAuth account. However, it omits two enum values (patent_grant, clinical_trial) and the webhook delivery channel from the main text, relying on the schema for those, which is a slight 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 tool creates a proactive monitoring subscription to a live-data event stream and returns a subscription ID. It distinguishes itself from siblings like list_subscriptions, unsubscribe, and recent_alerts by focusing on the creation of new subscriptions, with specific resource types and delivery mechanisms.

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—when proactive monitoring of live-data streams is needed—and outlines supported subscription types with examples. It does not explicitly name alternatives or state when not to use it, but the context is strong enough to guide an agent, especially with sibling tools like recent_alerts for one-off queries.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behaviors. The description adds useful context beyond annotations by explaining that calling with no arguments returns the full spread, that results are drawn from a live catalog of thousands of tools, and that the output includes tool call shapes. No contradictions with annotations.

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

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

The description is long but information-dense, front-loaded with example queries and structured with a clear list of categories. Every sentence contributes to understanding the tool's purpose, usage, and output. It could be slightly tightened but is well-organized for an onboarding tool.

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

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

Despite having no output schema, the description adequately explains the return value: category-bucketed example questions with tool and argument shapes. It covers invocation modes, parameter behavior, and provides a clear use case. With annotations handling safety, the description is complete for this tool's complexity.

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

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

Schema coverage is 100% for the single topic parameter, so the schema already fully documents it. The description adds examples of valid topics (finance, pharma, betting) and clarifies the behavior when omitting the parameter, but this is marginal value beyond the schema's own description.

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

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

The description clearly states the tool is the onboarding entry point for discovering what Pipeworx can do, returning category-bucketed example questions with the exact tool and argument shape that answers each. It distinguishes from siblings by explicitly positioning it as the first tool to use when uncertain about capabilities.

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 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 explains when to omit vs. pass the topic parameter. However, it does not explicitly state when not to use it or mention alternative tools like discover_tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds behavioral context by requiring a user-supplied API key or endpoint, which is not covered by annotations. It does not elaborate on rate limits or errors, but this is acceptable given the annotation coverage.

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 primary action, and every sentence provides distinct value: the first explains the mechanism, the second offers an alternative. No redundancy or fluff.

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

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

Given the output schema exists and annotations cover safety, the description is sufficient for effective selection and invocation. It addresses the key prerequisite (API key/endpoint) and alternative tool. A minor gap is not mentioning how to discover language codes, but sibling tools like list_languages cover that.

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 text, source, and target, so the description does not need to repeat those. It adds mentions of _apiKey and _endpoint, but these are not present in the input schema, which could confuse parameter handling. Still, the core parameters are self-explanatory, and the description adds some operational context.

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

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

The description clearly states the tool's function: 'Translate text between languages using a LibreTranslate instance you supply'. It specifies the resource (text translation) and distinguishes it from siblings by highlighting the LibreTranslate backend requirement and the alternative deepl_translate.

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

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

Provides explicit when-to-use guidance: use when you have an API key or endpoint, and explicitly directs users without a key to 'deepl_translate' as an alternative. This gives clear usage context and an exclusion condition.

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

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

The description adds significant behavioral context beyond annotations: 'The row is deactivated (not deleted) so its historical events stay available via recent_alerts.' This clarifies the soft-delete behavior and the ownership restriction, which are not captured in the annotations (readOnlyHint=false, destructiveHint=false, etc.). 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 two sentences, front-loaded with the core action ('Cancel a subscription by id'), followed by two essential behavioral constraints. Every sentence earns its place; no filler or redundancy.

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

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

For a simple single-parameter tool with strong annotations and no output schema, the description is complete. It covers the action, ownership, and side-effect (deactivation) which is enough for the agent to select and invoke the tool correctly. No missing critical info.

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 'id' parameter, which is already described as 'Subscription id (uuid) returned by subscribe.' The description adds no new semantic detail beyond 'by id,' so it doesn't go beyond the schema. Baseline 3 applies.

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

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

The description clearly states the action: 'Cancel a subscription by id.' This is a specific verb (cancel) and resource (subscription). It distinguishes from siblings like subscribe (create) and list_subscriptions (list), and clarifies the operational effect (deactivation, not deletion).

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

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

The description provides clear contextual guidance: ownership is enforced, so only the user's own subscriptions can be cancelled. It implicitly tells the agent when this tool is appropriate (cancelling a subscription) and that it cannot be used for others' subscriptions. However, it doesn't explicitly name alternatives or contrast with siblings, but the context is sufficient.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description goes well beyond this by explaining return verdicts, the distinct meanings of could_not_verify (with verification_error details) and unsupported, the underlying data sources and routing logic, and the fact that it replaces a multi-step workflow. This gives the agent critical behavioral context for correctly using the results.

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

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

The description is long but each sentence delivers functional information: usage, routing, return semantics, and error handling. It is front-loaded with examples and the core directive, and later sections systematically cover behavior and output. No filler or redundancy, though the length might be slightly overwhelming for a simple tool; here it is justified.

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

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

Without an output schema, the description provides a complete picture of return values and verdict types, explains error states, describes the internal pipeline, and even notes the performance benefit. This is more than sufficient for an agent to select and invoke the tool correctly, and it covers edge cases like could_not_verify that would otherwise be ambiguous.

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

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

The schema already documents both parameters with examples, but the description adds substantial value: it explains how tolerance_pct overrides the claim wording, recommends 1–2 for hallucination detection, and states the default cap. The claim parameter is also embedded in the description with natural-language examples, reinforcing the expected input format.

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

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

The description unambiguously identifies the tool's purpose: natural-language factual claim verification with a verdict. It lists concrete trigger phrases ('fact check', 'verify the claim that') and contrasts with sibling tools by framing itself as the replacement for 4–6 sequential calls, making its unique role clear.

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

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

It explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct' and details the two routing paths (SEC EDGAR for company financials, grounded pipeline for everything else). It does not explicitly name alternatives, but the scope is so clearly defined that an agent can easily decide when to invoke this tool. The error semantics (could_not_verify vs unsupported) further guide the caller on how to interpret results.

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