Geoboundaries

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

Annotations already indicate readOnly and idempotent, so safety is covered. The description adds valuable behavior beyond this: the default model is free, using Anthropic requires a BYO key with direct cost to the user, and the return structure is disclosed. No contradictions.

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

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

Three sentences, each earning its place: purpose, model/cost behavior, return format and use cases. Front-loaded with the primary action, no redundant filler.

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

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

For a simple 4-parameter tool with no output schema, the description covers the return value (per-model score/confidence/signals/raw_response + combined view), the optionality of models, cost implications, and concrete use cases. This is sufficient 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 baseline is 3. The description adds meaning beyond the schema by explaining the default model behavior and that `_apiKey` is only needed for Anthropic and incurs direct costs. This helps correctly populate the parameters.

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

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

The description uses a specific verb+resource: 'Probe one or more LLMs for what they know... and score visibility (0-100) per model.' This clearly distinguishes it from sibling tools like ask_pipeworx or compare_entities by focusing on AI visibility scoring across multiple models.

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

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

The description gives explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the default model and how to enable Anthropic probing. It doesn't explicitly name alternative tools, but the context is clear enough for an agent to decide when to use this tool.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and idempotentHint=true, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: it explains that the tool routes internally, fills arguments automatically, and returns structured answers with citation URIs. It doesn't mention rate limits or auth, but with annotations covering safety, the disclosure is sufficient.

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

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

The description is long but front-loaded with the most important guidance ('PREFER OVER WEB SEARCH') and every sentence adds value: trigger phrases, examples, routing behavior, citation output, and alternative tools. It is structured and scannable, though slightly verbose.

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

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

Given that there is no output schema, the description adequately explains the return format ('structured answer with stable pipeworx:// citation URIs') and covers a wide range of use cases with examples and alternatives. It doesn't describe failure modes, pagination, or limits, but for a broad router tool with strong annotations, this is a minor gap.

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

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

Schema description coverage is 100% and the single required parameter is fully documented, including alias fields. The description reinforces that input is a natural-language question and gives example phrasings, but it does not add substantial meaning beyond what the schema already provides.

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

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

The description states exactly what the tool does with a specific verb and resource: it routes a natural-language question to the right one of 5,798 tools across 1,517 sources and returns a structured answer with stable pipeworx:// citation URIs. It also distinguishes itself from named siblings like ask_pipeworx_grounded and deep_research, so an agent can tell them apart.

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 is explicit about when to use this tool versus alternatives: it says to prefer it over web search, gives trigger phrases ('what is', 'look up', 'find', etc.), provides concrete examples, and names specific alternatives with conditions ('hallucination-resistant single answer... use ask_pipeworx_grounded'; 'broad/multi-part question... use deep_research').

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, non-destructive behavior. The description adds meaningful context beyond that: live candidate routing improvements, current inactive state with a retirement date, exact parity with ask_pipeworx right now, and the fact that it is a fully functional router rather than a stub.

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 focused paragraph that front-loads the essential 'beta of ask_pipeworx' identity and then clarifies current behavior, experimental status, and fallback expectations. The date detail is specific but supports the 'nothing active right now' claim without bloating the text.

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 question-routing tool, the description covers identity, current status, usage context, and safety profile via annotations. It references the same response shape as ask_pipeworx rather than spelling it out, which is acceptable given the sibling exists, though slightly less complete than fully documenting the output.

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

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

Schema coverage is 100%, so the schema already documents all six parameters and aliases. The description only repeats that arguments match ask_pipeworx, adding no new parameter-level meaning, which aligns with the baseline for high schema coverage.

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

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

The description opens by identifying this as 'Beta version of ask_pipeworx' and a 'universal router' with the same 5,798 tools, arguments, and response shape, so an agent immediately knows what it does. It differentiates itself from ask_pipeworx as the experimental edge, which separates it from its sibling 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?

It explicitly says to 'Use it exactly like ask_pipeworx when you want the newest routing' and explains results are compared against the stable router. It does not explicitly list when-not-to-use or alternatives like ask_pipeworx_grounded, but the condition for choosing this beta variant is clear.

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

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

Beyond the readOnly/openWorld/idempotent hints, the description discloses meaningful behavioral traits: it makes an extra LLM call, extracts answers only from tool result content, returns verbatim evidence, and refuses with specific enumerated reasons when the data does not directly answer. This gives agents a clear model of failure behavior.

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

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

The description is dense but every sentence adds value: it front-loads the core differentiator, then covers return structure, refusal reasons, usage guidance, and cost trade-off. No filler or redundant restating of schema fields.

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

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

For a tool with no output schema, the description compensates thoroughly by specifying the success response shape, the refusal response shape, the refusal reason enums, and the exact condition under which refusal occurs. Combined with 100% parameter schema coverage, the agent has enough to select and invoke the tool correctly.

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

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

Schema coverage is 100% and documents question plus five aliases with descriptions. The tool description adds no additional parameter semantics beyond 'fills arguments' and natural-language question usage, so the schema already carries the burden. 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 states a specific purpose: a hallucination-resistant grounded answer mode that extracts answers only from tool results. It clearly distinguishes itself from sibling ask_pipeworx by highlighting the grounding behavior, structured evidence output, and explicit refusal mechanism.

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 when to use this tool: when answers will be quoted, cited, or acted on and facts must not be invented, with concrete examples like financial verdicts, legal claims, and medical lookups. It also names the alternative, ask_pipeworx, and advises preferring it for casual lookups due to the extra LLM call cost.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive, and the description adds substantial behavioral nuance: both low-confidence and closed-market paths are blocking, resolver contract with confidence levels and alternatives, parent-event extraction, news fallback fields, wide-spread warnings, and cancellation-rule risk. This gives agents critical safety and interpretation context far beyond the annotations.

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

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

Although lengthy, the description is densely packed with useful information and structured with clear section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT) that make it scannable. Every sentence adds operational value for a complex tool; there is 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?

With no output schema, the description fully documents response fields (result.market, result.analysis, result.evidence), the resolver contract, parent_event behavior, news fallback mechanics, and edge cases like wide-spread markets and cancellation-rule risk. It even explains the two blocking routes and advises when to check cancellation rules, making it robust for safe agent usage.

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 has 100% parameter description coverage, and the description further enriches it: 'depth' is clarified with 'quick = 2-3 evidence sources' and default thorough, 'include_raw' explains the size tradeoff (under ~20KB vs 50KB-500KB) and intended use, and 'market' is given concrete slug/URL/question examples. The extra semantics directly inform invocation and response handling.

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, specific verb-resource pairing: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It then details input forms (slug, URL, question text) and the pipeline (resolve, classify, fan out, return evidence packet plus comparison), effectively distinguishing it from general research or Polymarket edge tools.

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

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

The description explicitly lists intended use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z', and provides extensive fan-out examples per bet category. However, it lacks an explicit 'when not to use' or named alternative tools, so while context is clear, it could go further in differentiation.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive; the description adds substantial context beyond annotations: data sources (SEC EDGAR/XBRL, FAERS, FDA), specific financial metrics, off-calendar fiscal year handling, sorting by primary metric, and output format including 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 lengthy but every sentence serves a purpose: query triggers, core purpose, preference rule, type-specific details, sorting behavior, and return format. It is front-loaded with examples but remains well-structured and information-dense for a tool with two modes and multiple data sources.

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

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

No output schema exists, yet the description explains return contents (paired data, citation URIs) and sorting behavior. It also covers data provenance and edge-case handling (off-calendar fiscal years), providing a complete picture for the agent to invoke the tool correctly without further probing.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description enriches this by explaining how 'type' determines data pulled (10-K metrics vs FAERS/FDA counts) and clarifying the 2–5 entity limit for 'values'. This adds meaningful context beyond the raw enum/array definitions, though the schema already covers basics.

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

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

The description clearly states this tool performs 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call' and supports comparison/ranking queries like 'X vs Y' and 'which is bigger'. It distinguishes itself from single-entity alternatives by emphasizing it replaces 8–15 sequential lookups, aligning with sibling entities like entity_profile.

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

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

Explicitly instructs to 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', giving clear when-to-use guidance. It also describes type-specific behavior (company vs drug) and output sorting, but does not explicitly name sibling alternatives or exclusion cases, leaving minor room for improvement.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds substantial behavioral context beyond that: it discloses parallel decomposition across 5,798 tools, returning a findings packet with gaps[], that it never invents answers, timing expectations (15-60s up to ~90s), and how citations are always fetchable. These go beyond what annotations provide, though it doesn't detail every edge case.

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

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

The description is long but every sentence carries meaningful information — account requirements, alternatives, data scope, mechanics, return format, timing, and exclusions. It's front-loaded with the most critical constraint (account/sign-in requirement and alternative). While it could be trimmed, its density justifies its length for a complex 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 complex tool with two parameters and no output schema, the description covers far more than expected: data coverage, routing mechanism, return packet contents, gap handling, citation resolvability, timing, and tier differences. It lacks an explicit return-format example, but given the rich behavioral description, the tool is well-enough specified for an agent to invoke correctly.

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

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

Schema description coverage is 100%, so both parameters are fully documented in the schema. The description adds context by explaining what 'quick', 'standard', and 'thorough' mean behaviorally in terms of hops and contradiction scanning, which enriches the enum semantics. However, it doesn't add much beyond what the schema describes, so a baseline 3 is appropriate.

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

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

The description clearly states the tool performs grounded multi-source research over 1517 structured data sources in one call, with explicit examples of the kind of questions it handles. It explicitly distinguishes itself from open-web search and names ask_pipeworx as the alternative for single lookups, making it easy to differentiate from siblings.

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

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

The description gives clear when-to-use guidance ('best for broad/multi-part questions over structured data'), explicit when-not-to-use guidance (breaking news / current events -> prefer ask_pipeworx), and names the alternative tool. Also includes account requirements and depth tier explanations, leaving little ambiguity about usage conditions.

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 adds important behavioral detail: it returns top-N relevant tools with names, descriptions, full input schemas, and curated examples, emphasizing results are ready to call directly with no second lookup. This is valuable context beyond the annotations.

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

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

The description is concise but rich, with each sentence serving a purpose: definition, when-to-use, output details, and prioritization. The enumeration of domains is useful and not wasteful. It is well-structured and front-loaded with the core purpose.

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

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

Given the tool's complexity (6 parameters, aliases, no output schema), the description sufficiently covers return values, usage intent, and direct callability. The annotations handle safety, and the schema covers parameters. No critical context 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 the schema and its property descriptions fully document the parameters and aliases. The description does not add parameter-level detail beyond the schema, which is acceptable given the high coverage, but it provides no extra semantics.

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

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

The description clearly states the tool's function: 'Find tools by describing the data or task.' It specifies the resource (available tools) and action (discover/browse/search), and differentiates itself from sibling tools by emphasizing discovery across many domains and providing ready-to-call 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?

Explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist for...' and instructs to 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear context and distinguishes it from directly using a specific tool.

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

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

Annotations already mark read-only, idempotent, and non-destructive, so the description's extra behavior color is valuable: parallel fan-out across EDGAR, XBRL, USPTO, USAspending, FDA, DOL, GDELT, and GLEIF; soft-fail for the USPTO sunset; empty sections meaning genuine no-data; sources_used/sources_failed; and resolved:false with notes for private companies. This goes well beyond the hints.

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 at least one dense introductory sentence captures the core purpose and preference. The subsequent detail about return sections and failure modes earns its place because this tool has many sources and edge cases. Slight deduction for being a dense wall of text without structural separation.

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 full responsibility for explaining results, and it does: it lists every return section (cik, recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI, sources_used/failed) and explains expected empties and fallbacks. For a 2-parameter tool, nothing needed to call it correctly 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 coverage is 100% and the schema descriptions already explain the interchangeable type, the allowed value shapes, examples, and name resolution via SEC EDGAR. The tool description largely restates those param details, so it adds little new parameter-level meaning beyond what the schema already provides.

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

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

States a specific verb ('profile') and resource ('US public company'), anchored by many concrete user phrasings and a clear one-line summary: 'full cross-source profile of a US public company in ONE parallel call.' It also differentiates from chaining single-source lookups and implicitly from siblings like compare_entities and resolve_entity.

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

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

Explicitly says when to prefer this tool: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It then details accepted value forms (ticker, CIK, name) and the graceful private-company path, giving an agent enough guidance to decide and execute.

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

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

Annotations already indicate destructiveHint and idempotentHint, and the description aligns by saying 'Delete'. It adds a subtle behavioral trait by noting 'previously stored memory', implying deletion applies only to existing keys. It also adds context about cleaning sensitive data. 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, with the first sentence front-loading the primary action and the second adding usage guidance and complementary tools. Every sentence earns its place without unnecessary verbosity.

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

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

For a simple one-parameter tool with no output schema and no nested objects, the description is complete. It covers purpose, usage context, complementary tools, and the key parameter is fully documented in the schema. 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 input schema fully describes the single parameter 'key' with a description and example, so schema coverage is 100%. The description merely repeats 'by key' without adding new meaning beyond the schema, which meets the baseline for high schema coverage.

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

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

The description clearly states the tool deletes a previously stored memory by key, using the specific verb 'Delete' with the resource 'memory'. It distinguishes from siblings like 'remember' and 'recall' by positioning itself as the removal operation, and explicitly says 'Pair with remember and recall'.

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 on when to use: 'Use when context is stale, the task is done, or you want to clear sensitive data'. It also names complementary tools ('remember and recall'), offering clear context for selection among 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 idempotentHint=true, so the safety profile is known. The description adds valuable behavioral detail: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format' and specifies the output is a 'single text blob ready to drop at site-root/llms.txt'. No contradiction with annotations.

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

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

The description is three sentences with no redundancy. It leads with the core purpose, explains the mechanism, and concludes with practical use cases. 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?

With only two parameters and no output schema, the description fully covers the tool's behavior, output format ('Output is a single text blob ready to drop at site-root/llms.txt'), and use cases. Annotations cover safety. The description is complete for this simple 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?

The input schema has 100% coverage for both parameters, so the baseline is 3. The description adds context about what the tool does with the URL (fetches, extracts) but does not add new parameter-level details beyond what the schema already provides for max_links or url.

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: 'Generate a production-ready llms.txt file for any URL'. It uses a specific verb and resource, and distinguishes itself from siblings by focusing solely on llms.txt generation, which no other tool handles.

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

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

The description provides explicit use cases ('Useful for: 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') and clarifies the input is 'any URL'. However, it does not explicitly mention alternative tools or when not to use it, 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds meaningful behavioral context by enumerating the exact metadata fields returned, listing download URL types, and noting the default product's CC-BY license—details 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 four sentences, each earning its place: purpose, ISO3 explanation, ADM level explanation, and product/license note. It is dense but not verbose, with clear front-loading of the core function.

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 thoroughly communicates the return payload (unit count, year, source, license, download URLs), fully explains all three parameters, and states defaults and licensing. It provides a complete picture of what the tool does and returns, leaving minimal ambiguity.

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 descriptions cover 100% of parameters, so the baseline is 3. The description adds value by providing concrete ISO3 examples, explaining ADM levels in a natural hierarchy, and clarifying the default product and license, enriching what the schema already provides.

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

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

The description opens with a specific verb and resource: 'Get administrative boundary metadata for a country from geoBoundaries'. It clarifies the return type (metadata with download URLs), distinguishing it from the sibling tool get_geometry which likely fetches geometry itself.

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

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

The description implies when to use the tool (when you need boundary metadata) and explains parameter semantics, but it does not explicitly mention alternatives or when not to use it. With get_geometry as a close sibling, a direct comparison would strengthen this dimension.

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

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

Annotations declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds behavioral context beyond these: payloads can be several MB, the tool refuses payloads over ~4 MB, it returns only simplified geometry, and adm="ALL" is invalid. This enriches the annotation info 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 slightly long but every sentence adds critical information: what it fetches, size warning, size limit, alternative tool, and validity constraint. It is front-loaded with the main purpose and uses compact phrasing, though the warning could be considered a bit verbose for the score of 5.

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

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

Given the tool's complexity (large payloads, restriction on adm='ALL', relationship to get_boundaries), the description covers the return type, size behavior, refusal threshold, and usage context. No output schema exists, but the description sufficiently explains what is returned and the edge cases.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add significant parameter-specific meaning beyond the schema; it focuses on response size and alternatives. It confirms product defaults indirectly via schema, but no extra semantic value is provided for the parameters themselves.

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 fetches simplified GeoJSON FeatureCollection geometry for a country/ADM level, using a specific verb and resource. It distinguishes itself from sibling get_boundaries by noting this tool only returns simplified geometry and explicitly recommends get_boundaries for other cases.

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

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

Explicit guidance is provided: 'Prefer get_boundaries unless you explicitly need the coordinates' and 'Not valid for adm="ALL"'. It also warns about payload size and directs users to get_boundaries for large payloads, covering both when-to-use and 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds useful context beyond annotations by specifying the returned fields (id, type, params, created_at, last_fired_at, fire_count) and the default behavior of only including active subscriptions. It does not contradict any annotation.

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

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

The description consists of two tightly written sentences. The first states the action and output, the second explains when to use it. Every sentence earns its place, with no fluff or repetition.

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

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

For a simple list tool with one optional parameter and no output schema, the description is complete. It states what is listed, what fields are returned, and the intended usage contexts. The tool's simplicity and strong annotations mean no significant information is missing.

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

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

Schema coverage is 100% and the single parameter 'include_inactive' has a clear description. The tool description does not add any additional meaning beyond the schema; it simply restates the default behavior. This matches the baseline where the schema does the heavy lifting.

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

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

The description uses a specific verb and resource ('List the caller's active subscriptions'), clearly identifying what the tool does. It also lists the return fields and distinguishes the tool from siblings like 'subscribe' and 'unsubscribe' by framing it as a review/cancel-id lookup tool.

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

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

The description gives clear context for when to use the tool: 'review what you're monitoring before adding more' and 'to find an id to cancel.' It implies alternative workflows (subscribe/unsubscribe) but does not explicitly state when not to use it or name alternatives. This is clear usage guidance but not a full when/when-not/alternatives breakdown.

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 all annotations set to false, the description carries the full burden of behavioral disclosure, and it succeeds. It discloses the claim_token flow (filing without an account returns a token that can be used later to check resolution), rate limiting ('Rate-limited to 5 per identifier per day'), quota impact ('doesn't count against your tool-call quota'), and operational details (team reads digests daily). It also advises not to paste end-user prompts, adding practical behavioral context. No annotation contradiction exists.

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

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

The description is longer than typical, but every sentence delivers useful information: purpose, use cases, exclusions, token flow, rate limits, and quota. It is front-loaded with the primary purpose and uses clear, direct language. Some redundancy exists (e.g., the 'only Pipeworx connection' point is restated), but the structure is logical and not bloated. It earns a 4 rather than 5 due to its density.

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

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

Given the tool's moderate complexity (4 optional params, nested object, no output schema), the description is remarkably complete. It covers the tool's domain, when to use/discard it, the full claim_token lifecycle, rate limits, and input formatting guidance. The absence of an output schema is mitigated by explaining the return behavior ('returns a claim_token') in the description. This is fully sufficient for an agent to select and invoke the tool correctly.

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

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

The input schema provides 100% description coverage for all four parameters, so the baseline is 3. The description adds meaningful semantic value by explaining the claim_token usage workflow in context ('pass it back later as pipeworx_feedback({claim_token:...})'), which goes beyond the schema's static parameter description. It also ties the context object to specific Pipeworx tools/packs, but the schema already handles that well. This extra operational context 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 tool's purpose with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly distinguishes this tool from sibling ask/research tools by limiting it to feedback about Pipeworx connection tools, and it enumerates the types of feedback (bug, feature/data_gap, praise). This leaves no ambiguity about the tool's 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?

The description provides explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear exclusion rule: 'ONLY for tools served by this Pipeworx connection' and instructs to report other MCP servers' tools elsewhere. This is exemplary usage guidance with alternatives and exclusions.

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

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

Annotations already declare safe read-only and idempotent behavior; the description adds valuable context with data provenance (CF analytics-engine), a privacy guarantee (no PII), and a caching window (5min-1h). 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?

Three tightly-scoped sentences: purpose, use cases, and data/caching details. No filler; the use-case list earns its length by improving selectability.

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

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

For a single-parameter read-only tool without an output schema, the description covers what it returns, the data source, privacy, and caching. The return shape is hinted at ('(pack, tool, count)'), which suffices for a simple 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?

The schema covers the only parameter (window) with an enum and meaning (24h/7d/30d). The description mentions the window options but adds no new semantics beyond what the schema already provides, 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 opens with a concrete question ('What other AI agents are calling on Pipeworx right now') and specifies exactly what it returns (top tools, top packs, total call volume). It clearly distinguishes itself from sibling discovery tools by focusing on real-time aggregate usage from other agents, not generic tool discovery.

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

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

The description provides three explicit use cases that guide the agent on when to call this tool, such as discovering hot data sources or confirming canonical tool choice. It doesn't name alternatives or exclusions, but the use cases are actionable and sufficient for selection decisions.

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

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

The description goes far beyond the annotations, revealing thresholds (deviation >3pp), placeholder filters (>20% -> null), fill-check pricing logic (realizable_edge_pp <= 0 means do not trade), and response structure. It provides rich behavioral context without contradicting the readOnly/idempotent annotations.

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

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

The description is long but well-organized with clear section labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded with the core purpose. Every section contributes necessary operational detail for a complex tool, so the length is justified, though it could be tightened.

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 all critical aspects: modes, parameters, response shapes, similarity thresholds, placeholder filtering, and real-world fill-risk caveats. With no output schema, this text fully compensates by describing the response structure and edge cases, making the tool's behavior completely understandable.

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 describes both parameters, the description adds significant value: example slug formats, accepted full URLs, how the topic is used to search related events, and the consequences of passing each parameter. This is precisely the contextual enrichment needed beyond the raw schema names.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (trending_scan with no args, event-mode, topic-mode) and references the sibling tool polymarket_fill_risk, making it distinct from alternatives.

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

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

It provides explicit guidance on when to use each mode: no args for trending scan, 'event' (recommended for a specific market), and 'topic' for cross-event scanning. It also explicitly directs to use polymarket_fill_risk for custom sizing, offering a clear alternative.

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

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

Annotations already declare the tool read-only, open-world, idempotent, and non-destructive. The description adds substantial behavioral detail: caching for 1 hour keyed on all knobs, diagnostics for empty segments (filter_skips, funnel counters), a 24h-move warning, and the Fed-exclusion caveat. This goes well beyond the static annotation flags and primes the agent for expected behavior.

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

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

The description is front-loaded with purpose but quickly becomes an exhaustive specification of model internals (per-sport α values, GDELT ratios, FRED log-returns, gate thresholds). While this information is useful, it makes the description overly long and hard to scan. A more structured or summarized format would improve conciseness without losing critical meaning.

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 the response, and it does so thoroughly: it details top-level segments (by_segment, fed_candidates, _diagnostics) and per-opportunity fields (edge_pp_net, kelly_fraction, market.liquidity, market.spread_pp, market.volume). It also explains why segments may be empty and how knobs affect the returned opportunities, making the tool self-contained.

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, but the description significantly enriches parameter understanding. For example, it explains that min_partition_leg_kelly applies to per-leg Kelly because parent-level kelly_fraction_half is always 0 for partition overrounds, and that max_spread_pp/min_liquidity serve as tradeable-edge filters. It also ties slippage_pp to Polymarket's zero-fee environment and typical bid/ask costs.

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 function: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price,' and even provides a concrete use case ('what should I bet on today'). It differentiates itself from siblings by emphasizing the Pipeworx disagreement framework and the specific model-family segments it returns.

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: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets' and offers detailed knob-based filtering instructions. However, it does not explicitly compare against sibling tools like polymarket_arbitrage or polymarket_edge_tracker, though the Fed-note section partially warns against relying on Fed-related signals in certain cases.

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

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

Beyond annotations (read-only, idempotent), the description explains data gaps (snapshots written on cache-miss), computation method (decay from daily closes of edge_pp_net, not intraday), signed values, and the meaning of expired opportunities. This is rich behavioral context that enables accurate interpretation.

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

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

Despite being long, every sentence earns its place: purpose, args, response structure, and limits are logically organized. Front-loaded with the core question, then structured sections. No wasted words.

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

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

Without an output schema, the description fully documents return types (tracked[], expired[], snapshot_dates[]) with fields and semantic meaning. It also covers historical limits, data gaps, and computation basis, making it complete for a complex telemetry 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?

With 100% schema coverage, baseline is 3. The description adds meaningful context by labeling days as 'lookback' and window as 'snapshot family' and explicitly stating defaults and max, clarifying the role of each parameter in the overall snapshot architecture.

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

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

The description clearly states it's 'edge persistence and decay telemetry' built from snapshots, answering 'how long has this edge existed and is it shrinking?' This distinguishes it from siblings like polymarket_edges (current edges) and polymarket_arbitrage, with a specific verb and resource.

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 context on when to use it: 'a fresh wide edge and a 3-week-old wide edge are different trades (the latter is wide for a reason nobody is willing to take)'. It doesn't explicitly list alternative tools, but the example makes the use case clear. LIMITS section adds practical constraints on applicability.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral context beyond these: mode requirements, default sides, size interpretation differences (spend vs target proceeds vs settlement notional), return fields including verdicts, and critical risk disclosure about partial basket fills. It does not contradict annotations.

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

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

The description is long but information-dense, with every sentence adding necessary detail. It is structured by mode (SINGLE-MARKET vs BASKET) and uses clear delimiters (e.g., 'REQUIRES', 'USE THIS'). However, it is a single dense paragraph that could benefit from bullet points or section breaks to improve scanability, though no content is redundant.

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

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

Given no output schema, the description thoroughly covers return values for both modes: top_of_book, vwap_fill_price, slippage_pp, verdict, theoretical_sum vs realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs[], and max_clean_notional_usd. It also covers edge cases (cannot_fill verdict, forced_directional_risk) and provides the 'why' behind usage, making it complete for a complex tool.

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

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

Schema description coverage is 100%, so baseline is 3, but the description enriches every parameter significantly. It explains the market/event mode distinction, the auto-detection logic for basket side, and the nuanced meaning of size_usd per mode (spend vs target proceeds vs settlement notional, with clamp range). This far exceeds the schema's terse parameter 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, meaningful purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes this tool from siblings by naming the arb-check use case and referencing polymarket_arbitrage and polymarket_edges explicitly. The verb 'check' plus resource 'live CLOB order-book depth' is specific 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?

Explicit usage guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the two modes (single-market vs basket), when each is appropriate, and the rationale (theoretical overround on thin books is not capturable, partial basket fills lead to unhedged directional risk). This goes beyond generic context and names concrete alternatives.

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

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

Annotations already mark this as read-only, open-world, idempotent, and non-destructive. The description adds rich behavioral detail beyond those annotations: both modes run the identical token-overlap matcher, compatibility codes can be non-empty even when pairs are returned, temporal_alignment null means 'could not be computed' not 'aligned', fees are gross not net, and skipped-unknown legs are never paired. This is exemplary behavioral disclosure.

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

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

The description is long, but every section earns its place: modes, response semantics, safety fields, codes, flags, fees, skipped counters, and limitations. It is front-loaded with the core concept and uses clear labels (TWO MODES, RESPONSE, SAFETY FIELDS). It could be tightened slightly, but for a tool with no output schema, the density 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?

Given three optional parameters, no output schema, and a complex match/spread model, the description is remarkably complete. It covers response contents, compatibility codes, per-leg flags, temporal alignment semantics, fee treatment, skipped-pair counters, and the 'pre-mapped ≠ tradeable' reality. An agent has enough context to call the tool correctly and interpret the result responsibly.

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 covers all three parameters at 100%, so the baseline is 3. The description adds meaningful semantics: it explains that topic is a pre-mapped shortcut auto-fetching matching events, that explicit parameters override the topic-mapped side, and that both modes share identical matcher behavior. It also lists all valid topic values, which reinforces but goes slightly beyond the schema's enum-like content.

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, informative definition: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes this from Polymarket-only tools by stressing cross-venue comparison and same-question pairing. It explains the core concept (participant-pool differences, 2-25pp spreads) and the safety caveat about non-equivalent bet shapes, making the tool's purpose unmistakable.

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

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

The description gives clear intra-tool usage guidance: two modes, topic shortcuts vs explicit kalshi_event_ticker + polymarket_event_slug for custom pairings, and a strong caveat that pre-mapped topics are not automatically tradeable. It does not explicitly compare against sibling tools like polymarket_arbitrage or polymarket_edges, but the context and mode selection are clear enough for an agent to decide when to invoke it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it explains that results are 'scoped to your identifier (anonymous IP, BYO key hash, or account ID)', which is a meaningful behavioral trait not captured in the schema or 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 primary action and mode, followed by usage context and scope. Every sentence conveys necessary information without waste, and the structure is easy to parse for an agent.

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

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

This is a simple tool with one optional parameter, no output schema, and rich annotations. The description covers purpose, modes, usage context, scope, and sibling relationships, which is fully sufficient for an agent to select and invoke the tool correctly. No critical information is missing.

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

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

The schema already provides 100% coverage for the single 'key' parameter, including the 'omit to list all keys' behavior. The description echoes this same semantic, adding illustrative examples but no new technical details. With high schema coverage, the baseline is 3, and the description does not exceed that 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 clearly states the tool's function with a specific verb ('Retrieve') and resource ('a value previously saved via remember'), plus a distinct secondary mode ('list all saved keys' when key omitted). It also explicitly distinguishes itself from sibling tools 'remember' and 'forget', making it unambiguous.

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

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

The description provides concrete use cases ('the user's target ticker, an address, prior research notes') and explains when to use the tool ('without re-deriving it from scratch'). It directly mentions the complementary sibling tools 'remember' and 'forget', effectively guiding the agent on when to use this tool versus alternatives.

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

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

Annotations already declare readOnly, openWorld, and idempotent hints, so the description doesn't need to restate safety. It goes beyond annotations by disclosing the return structure (source, citation_uri, raw payload) and the stateful mark_read behavior that affects subsequent calls. This adds meaningful behavioral context not present in the schema or 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, front-loaded with the core purpose, and every sentence adds value: purpose, return payload, filtering options, stateful behavior, and alternative access. There is no redundancy or filler, making it efficient and easy 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?

Given there is no output schema, the description compensates by describing the return payload fields and behavior. It also covers filtering, mark_read, and polling guidance, which are essential for an agent to use the tool effectively. It doesn't mention limit or unread_only, but those are fully documented in the input schema, so the description covers the remaining context adequately for a list tool.

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

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

Schema description coverage is 100%, so baseline applies. The description adds extra meaning by providing a concrete type example ('sec_8k'), clarifying the since parameter expects an ISO timestamp, and explaining how mark_read affects next calls. These details go beyond the schema's property descriptions and help agents use the parameters correctly.

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

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

The description opens with a specific verb and resource: 'Pull fired events from your subscription feed.' It clarifies the tool returns recent alerts from the evaluator's persisted feed, including source, citation_uri, and raw event payload. This clearly distinguishes it from sibling tools like list_subscriptions or recent_changes, which handle different resources.

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

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

It gives practical guidance: filtering by type/since, using mark_read to advance the read cursor, and note that 'Polls work fine' to indicate suitability for repeated calls. It also mentions the same feed is available via an HTTP endpoint for scripts/dashboards, providing an explicit alternative. It doesn't compare directly to sibling tools but offers clear context.

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

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

Annotations already declare read-only/idempotent/non-destructive, and the description adds substantial behavioral context: multi-source fan-out, GDELT→GNews fallback on rate-limit/5xx, USPTO soft-fail due to API sunset, and the exact return shape (changes[], total_changes, citation URIs). This goes well beyond the safety profile.

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

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

Though long, the description is densely packed with high-value information—examples, source details, fallback behavior, date formats, and output structure. There is no filler or tautology; every sentence earns its place and the structure is logical.

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

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

The tool is complex (three external sources, fallbacks, soft-fail) and has no output schema, but the description covers all major aspects: sources, window semantics, return structure, and the alternative entity_profile. An agent would know exactly what to expect and how to act.

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

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

The schema covers all parameters at 100%, so baseline is 3. The description adds extra value by explaining `since` relative shorthand formats, confirming `value` accepts ticker or CIK, and suggesting '30d' or '1m' for typical monitoring, which is helpful but not transformative.

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

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

The description explicitly states the tool is a change feed for companies over a time window, enumerating the data sources (SEC, GDELT/GNews, USPTO) and the output structure. It distinguishes itself from sibling entity_profile by contrasting dynamic changes vs static profile, making the purpose unambiguous.

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

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

The description gives clear example queries ('What's new with X', 'latest on Y') and explicitly recommends entity_profile for static profiles, providing an alternative. It also explains the fallback behavior between GDELT and GNews, so the agent knows when to use this tool and when not.

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

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

Annotations already indicate idempotent and non-destructive, and the description adds valuable context: persistent memory for authenticated users, 24-hour retention for anonymous sessions, and scoping by identifier. It does not contradict annotations, though it omits details about key overwrite behavior.

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

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

The description is front-loaded with the primary action and uses four tight sentences, each contributing useful information. There is no filler or redundant restatement of the tool's title.

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

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

For a simple two-parameter write tool with annotations and full schema coverage, the description covers purpose, usage context, persistence, scoping, and sibling relationships. It is fully sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% for both key and value parameters. The description adds concrete key examples and clarifies that value accepts any text, going beyond the schema's descriptions and reinforcing the key-value scoping 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 opens with 'Save data the agent will need to reuse later,' which specifies a clear verb and resource. It distinguishes the tool from siblings by naming recall and forget, and it provides concrete usage examples like ticker and address.

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

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

It explicitly instructs when to use the tool: 'Use when you discover something worth carrying forward...' and gives examples. It also positions it against recall and forget, explaining pairing for retrieval and deletion, which makes the choice of tool obvious.

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

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

Despite annotations already declaring read-only and idempotent hints, the description adds substantial behavioral context: graceful degradation of LEI/FIGI enrichment, explicit listing of unresolved identifiers, figi_candidates when ambiguous, and internal cascading of multiple lookups. This goes far beyond the annotations and helps agents set expectations.

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

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

Description is long but structured with sections for supported types and important caveats. It front-loads usage guidance and then provides necessary detail on edge cases. While verbose, every sentence carries meaningful info; a small trim could improve scannability, but it remains effective.

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

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

Given no output schema, the description adequately explains return behavior (candidates, unresolved fields, identifier sources). It covers both parameter semantics, supported entity types, and failure modes, making the tool fully self-contained. Agents can call it correctly without external documentation.

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

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

Schema coverage is already 100% for both parameters, but the description adds critical semantics: value param examples (e.g., passing issuer name exactly as printed for bonds, avoiding security-class words) and clarification of enum behavior for type. This significantly enhances understanding beyond the schema.

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

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

Description states a clear verb 'resolve' targeting the transformation of user-spoken names to official identifiers. It lists example queries and distinguishes from siblings by emphasizing it is the primary tool for name-to-ID lookup, unlike entity_profile or compare_entities which serve other purposes.

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

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

Explicitly instructs to 'Use FIRST whenever you have a name but need an ID,' and details supported types (company/drug) with enrichment fallbacks. It also warns about input formatting for bonds, preventing misuse. No alternative tools are named, but the 'FIRST' directive plus coverage of edge cases gives clear guidance.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds context that the tool internally calls ai_visibility_check for each entity, ranks by score, and returns confidence/signal density—useful behavioral insight beyond the annotations. No contradictions found.

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

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

The description is three sentences, front-loaded with the core action, and every sentence earns its place. It avoids redundancy with the schema and even includes a concrete example without becoming verbose.

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

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

Even without an output schema, the description explicitly states the return value (ranked list with score, confidence, signal density per entity), and covers the operational flow (probing, ranking, surfacing). It provides enough context for an agent to understand what to expect and when to invoke it, especially given the rich schema and annotations.

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

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

The input schema already provides 100% parameter coverage, so the baseline is 3. The description adds valuable semantic detail by stating the first entity in 'entities' is treated as the subject for narrative, which is not in the schema. It also clarifies that 'models' can be omitted for the default worker-ai, aligning with the schema's optional 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 compares AI visibility across multiple entities side-by-side, with a specific verb ('Compare') and resource ('AI visibility'). It also distinguishes itself from the sibling ai_visibility_check by emphasizing multi-entity comparison and ranking, and mentions the underlying probe mechanism.

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

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

Provides concrete use case ('competitive AI-marketing audits') with an example query, and implies it is the multi-entity counterpart to ai_visibility_check. However, it does not explicitly state when not to use the tool or name alternative tools for single-entity checks, leaving some room for interpretation.

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

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

Beyond the readOnly and idempotent annotations, the description discloses important operational behavior: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30 seconds, and sources_failed will list timeouts while the rest still returns. This adds meaningful context about latency and failure modes that annotations alone do not convey. 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 moderately long but each clause carries distinct information: composite nature, use cases, return fields, ecosystem scope, and failure behavior. It is well-structured with clear sequencing, though the final sentence is somewhat run-on. Slight over-elaboration but appropriate for the tool's complexity.

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

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

Given the tool's complexity and the absence of an output schema, the description compensates by listing the exact return fields, per-advisory details, links, and recent alternative versions. It also covers partial failures and latency, making the tool's behavior fully understandable for an agent. 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 input schema already provides 100% coverage with clear descriptions for both package and version parameters, including examples and defaults. The tool description does not add parameter-specific semantics beyond what the schema already states. Per the rubric, high schema coverage earns a baseline of 3, and there is no additional parameter explanation to raise it.

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 specifies the tool as a composite npm package assessment, naming both data sources (deps.dev and bundlephobia) and the specific data points returned. It distinguishes itself from siblings by explicitly scoping to NPM and referencing direct deps.dev usage for other ecosystems. The verb "scan" plus the resource "dependency" and the detailed explanation make the purpose unambiguous.

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

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

The description explicitly states when to use: whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me". It also provides an explicit alternative for non-NPM ecosystems (use deps.dev:version directly), making the boundary clear. This goes beyond implied use and gives concrete triggers and exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds substantial behavioral details beyond that: it reveals the embedding model ('BGE-base-en embeddings + cosine over 500-char overlapping windows'), the character cap ('200K chars'), and the truncation behavior ('longer inputs are truncated and flagged'). It also clarifies the output structure (offsets and similarity scores), providing a transparent picture of what happens internally.

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 dense with critical information. It is front-loaded with the core purpose, then moves to usage context, a pairing recommendation, and technical details. Every sentence earns its place—no fluff or repetition. The structure naturally guides the reader from 'what' to 'when' to 'how.'

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

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

Even without an output schema, the description fully explains what the agent can expect: 'top-N passages with character offsets and similarity scores.' It covers constraints (200K cap, truncation flag) and integration with a sibling tool. For a search utility, this provides all necessary context for the agent to use it correctly.

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

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

The input schema covers all parameters with descriptions (100% coverage), so the baseline is 3. The description reinforces the schema by giving a natural-language example for 'query' and specifying the text input as 'text you already pulled.' However, it doesn't add meaning beyond what the schema already provides; the examples are helpful but not essential.

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: 'Semantic search INSIDE a fetched record.' It specifies the input (text + query), the output (top-N passages with offsets and similarity scores), and provides a concrete example (SEC 10-K body). It distinguishes itself from sibling tools by focusing on searching within an already-fetched text rather than general research or Q&A.

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

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

The description explicitly states when to use this tool: 'Use when the record is too big to cram into the prompt.' It explains the benefit ('saves context, returns only the passages that matter') and even provides a pairing with ask_pipeworx_grounded, showing a clear workflow. This gives the agent strong guidance on when to invoke it over alternatives.

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

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

The description discloses significant behavioral details: OAuth requirement, delivery channel constraints (10/day SMS cap), webhook auto-disable after 10 failures, and one-time signing secret. These go beyond the annotations (readOnlyHint=false, idempotentHint=true) and provide rich context.

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

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

The description is long but well-structured, moving from purpose to requirements, types, and delivery channels. Every sentence contributes unique information, and the core action is front-loaded.

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

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

It covers purpose, auth requirements, all five subscription types, delivery options, return value (subscription id), and limitations. Even without an output schema, the description gives the agent enough context to invoke the tool correctly.

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

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

Although the schema covers 100% of parameters, the description adds practical semantics: type-specific examples (e.g., items:['5.02'] for officer changes), E.164 phone format, and webhook signing details. This supplements the schema meaningfully.

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

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

The description explicitly states 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' The verb and resource are specific, and the tool is distinguished from siblings like list_subscriptions and unsubscribe.

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

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

It explains when to use the tool (to create proactive subscriptions) and contrasts it with pulling from the always-on feed via recent_alerts. It also gives prerequisites such as requiring a Pipeworx OAuth account and verified phone for SMS, without explicitly naming alternatives for management tasks.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive, so safety is covered. The description adds meaningful behavioral context beyond annotations: it states the output is 'category-bucketed example questions... drawn from the live catalog of thousands of tools', which sets expectations about freshness and content. No contradictions.

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

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

The description is on the longer side, but every part earns its place: usage examples, core purpose, output details, and invocation guidance. It is front-loaded with natural language queries that quickly orient the reader. A slight miss on perfect conciseness due to the lengthy example list, but overall well structured.

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

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

For a tool with one optional parameter, no output schema, and strong annotations, the description covers all necessary context: when to use it, what it returns, how to customize, and relationship to meta-tools. The openWorldHint and non-destructive annotations further complete the picture. Nothing critical is missing.

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

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

Schema description coverage is 100%, as the schema already documents the 'topic' parameter's allowed values and the 'omit for cross-category' behavior. The description reinforces this with examples like 'finance', 'pharma', 'betting' but adds no new semantic info 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 this is 'the onboarding entry point' that returns 'category-bucketed example questions' with exact tool+argument shapes. It uses specific verbs like 'suggest' and 'returns', and distinguishes itself from sibling tools by positioning itself as the first thing to use when unfamiliar with Pipeworx. This is a precise, non-tautological 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?

Explicitly instructs when to use it: 'Use this FIRST when you do not yet know what Pipeworx can do for you.' It also explains parameter usage ('Call with no arguments for the full spread, or pass topic to focus') and hints at alternatives by listing meta-tools to learn about. Clear contextual 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 idempotentHint and destructiveHint, but the description adds valuable context about ownership enforcement and the soft-delete behavior (deactivated, not deleted). This goes beyond the structured 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?

Two efficient sentences front-load the action and then add the key ownership and deactivation details. 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?

For a single-parameter mutation tool with annotations and no output schema, the description covers the essential behavioral contract: what is canceled, who can cancel, and what happens to historical data. This is complete and well-scoped.

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 by describing the id as 'Subscription id (uuid) returned by subscribe.' The description's 'by id' adds no additional semantic value, so it appropriately rests at the baseline for high schema coverage.

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

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

The description opens with a specific verb and resource: 'Cancel a subscription by id.' This clearly distinguishes the tool from siblings like subscribe and list_subscriptions, and adds meaningful detail about deactivation versus 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 context: ownership is enforced and only your own subscriptions can be canceled. It also implies when to use recent_alerts for historical access after deactivation, though it does not explicitly mention alternatives like list_subscriptions for finding ids.

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, but the description adds substantial behavioral nuance: routing to sources, emission of verbatim evidence with pipeworx:// citations, the full verdict enum, and the crucial distinction between could_not_verify (check did not happen) and unsupported (no source exists). This goes well beyond annotations and gives agents the interpretation they need to act correctly.

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 information-rich, front-loaded with purpose and usage. It is somewhat long, but each clause earns its place, providing examples, route-specific behavior, return values, warnings, and even a performance note. The structure is mostly linear and readable; a slight tightening of the opening phrasing would make it fully concise, but it is far above average.

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 2-parameter tool with no output schema, the description is exceptionally complete. It specifies the return verdict enum, evidence/citation format, error semantics for could_not_verify, and the unsupported case. It also covers both supported claim types (financial vs. other) and the tolerance behavior. There is no ambiguity left 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 schema coverage is 100%, the description enriches both parameters significantly. It provides a concrete example for claim, explains that tolerance_pct has a 0.5–50 range, defaults to wording-implied with a 5% cap, and notes that 1–2% is appropriate for hallucination detection—details not in the schema. This gives agents precise guidance for setting tolerance.

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

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

The description clearly identifies the tool as a natural-language claim verifier that returns a verdict against authoritative sources, with concrete example phrases ('fact check', 'verify the claim that…'). It distinguishes itself from sibling Q&A tools by focusing on verification with evidence and structured verdicts, and by explicitly describing the two routing paths (SEC EDGAR for financial claims, grounded pipeline for others).

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

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

It explicitly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It further differentiates company-financial claims from other factual claims, explains the automatic routing, and warns about the interpretation of could_not_verify. It also notes that the tool replaces 4–6 sequential calls, giving the agent a strong usage heuristic.

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