Govcon Intel

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses that Workers AI is free by default, that passing _apiKey triggers external Anthropic calls with direct cost to the user, and it outlines the return structure. This adds valuable behavioral context about external API interactions and cost implications.

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 well-structured sentences: first states the main action and output, second details model options and cost, third lists return fields and use cases. There is no padding, and every sentence conveys essential information without redundancy.

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

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

Given that there is no output schema, the description appropriately discloses the return shape (per-model {score, confidence, signals, raw_response} plus combined view). It also covers the default behavior, optional parameters, and typical use cases. For a read-only probing tool with 4 parameters, this is sufficient for an agent to select and invoke it correctly.

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

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

The input schema already describes all parameters clearly (100% coverage), so the baseline is 3. The description adds extra value by explaining that `models` defaults to just 'workers-ai', that `_apiKey` is only needed for Anthropic and is passed straight through (with cost implications), and clarifies the `_apiKey` format. This goes beyond the schema's structural descriptions.

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

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

The description opens with a specific verb ('Probe') and resource ('one or more LLMs for what they know about a business / brand / product / topic'), followed by the scoring mechanism (0-100 per model). This clearly distinguishes it from siblings like 'scan_competitor_ai_presence' by focusing on LLM knowledge/visibility rather than web presence.

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

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

The description provides clear usage context ('Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the default model and optional Anthropic key. However, it does not explicitly mention when not to use it or compare it to sibling tools like scan_competitor_ai_presence, so it lacks the full when/when-not guidance.

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

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

Annotations already establish readOnly, openWorld, idempotent, and non-destructive behavior. The description adds meaningful behavioral context beyond annotations: it routes to the right tool, fills arguments automatically, and returns structured answers with stable citation URIs, which helps the agent anticipate the tool's open-ended routing behavior.

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

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

The description is long but information-dense: it front-loads the key directive, then compactly covers domains, trigger phrases, examples, and exclusions. Almost every sentence adds value or disambiguates from siblings, though a few examples could be trimmed without losing clarity.

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 routing tool with no output schema, the description covers the essential behavior, expected input style, domain scope, citation output format, and sibling routing distinctions. It also preempts edge cases such as breaking news, evidence-grounded answers, and multi-part queries, leaving the agent well equipped to call and interpret results.

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

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

Schema coverage is 100% and all six parameters are documented as aliases for the single 'question' parameter, so the schema does the heavy lifting. The description provides examples of acceptable questions and clarifies that natural-language factual queries are expected, but it does not add substantial detail beyond what the schema already states.

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 names a specific verb and resource: routes a user's factual question to the right specialized tool across 5,767 tools and returns a structured answer with pipeworx:// citation URIs. It clearly distinguishes itself from web search and sibling tools like ask_pipeworx_grounded and deep_research by defining its exact scope.

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

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

Provides explicit when-to-use guidance: a broad list of domains, trigger phrases, concrete examples, and a 'START HERE for most questions' directive. It also names when-not-to-use alternatives: ask_pipeworx_grounded for verbatim evidence against a single source and deep_research for broad multi-part questions.

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

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

Annotations already mark the tool read-only, idempotent, and non-destructive. The description adds important behavioral nuance: candidate routing improvements may be "enabled live," no candidate is currently active so behavior "matches ask_pipeworx exactly," and it is a full working router rather than a fallback wrapper. This is exactly the kind of context an agent needs to treat beta output appropriately.

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 beta identity and scope, and each sentence has a role: identity, current state, and usage purpose. It is slightly redundant—"identical ... same ... same ... same" and "currently matches ask_pipeworx exactly" repeat one idea—and the specific retirement date is more detail than an agent needs.

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 universal-router tool with no output schema, the description covers what is needed: identity, scope over 5,767 tools, same arguments and response shape as ask_pipeworx, current active-candidate state, and a warning that it is a full router rather than a fallback wrapper. The input schema covers the question parameter and aliases, leaving no significant gap for correct invocation.

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

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

All six parameters are documented with 100% schema coverage, and five are explicit aliases of `question`, so the schema already carries the semantic load. The description only says "same arguments" and adds no new meaning about how to form a question or parse the answer, so the baseline schema-based score is appropriate.

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

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

The description opens with "Beta version of ask_pipeworx" and characterizes the tool as an "identical universal router" over 5,767 tools, which states a concrete purpose. It explicitly differentiates itself from the stable ask_pipeworx sibling by the beta/experimental status, 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?

It says "Use it exactly like ask_pipeworx when you want the newest routing," which is a clear use condition and names the stable alternative. It does not spell out when-not-to-use beyond the "experimental edge" implication, but the beta context and routing comparison make the choice criteria clear.

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

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

The description adds substantial behavior beyond annotations: it discloses the refusal behavior with specific refusal_reason values, the evidence/verbatim-quote guarantee, the extra LLM call cost, and the constraint that answers are only extracted from fetched tool results. This goes well beyond the readOnly/idempotent hints already present.

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

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

The description is information-dense but every sentence earns its place: purpose, mechanism, success shape, refusal shape, usage guidance, and cost trade-off. The key differentiator ('Hallucination-resistant answer mode for high-stakes reads') is front-loaded.

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

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

With no output schema, the description fully documents the success response and refusal response including refusal reason enums. It also covers when to use the tool, when not to, and the cost relative to the sibling, so an agent has everything needed to invoke it appropriately.

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

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

Schema coverage is 100%, and the schema already documents the required question parameter plus all aliases. The tool description adds no extra parameter-specific semantics, so the baseline of 3 applies.

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

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

The description names a specific verb ('EXTRACTS the answer using ONLY what the tool result contains') and a clear resource/behavior: hallucination-resistant grounded answering. It also distinguishes itself from sibling ask_pipeworx by explaining the same routing but different answer-generation guarantee.

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

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

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also gives the alternative condition: 'prefer ask_pipeworx for casual lookups,' and even mentions cost trade-off, making the selection decision concrete.

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

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

Annotations already declare read-only and safe, but the description goes far beyond: it documents the low-confidence short-circuit status, closed/inactive market handling, illiquid wide-spread warnings, cancellation-rule risk, news fallback fields, and detailed response shapes. This provides rich behavioral context with no contradiction.

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

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

The description is long but every section earns its place with labeled classifiers, fan-out examples, response shapes, safety contracts, and resolution-rule details. It is front-loaded with purpose and then organized as a structured spec, 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?

Despite lacking an output schema, the description fully specifies the return contract (market, analysis, evidence, resolver, parent_event, news fields) and all edge-case statuses, including low-confidence matching and closed-market blocking. An agent has enough to decide when to trust and what to inspect; nothing important 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 covers 100% of parameters, and the description adds valuable usage meaning: depth's 'quick' vs 'thorough' behavior, include_raw's response-size implications and when to enable it, and concrete input formats for the market parameter. This exceeds the baseline for full schema coverage.

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

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

The opening sentence explicitly states the tool researches a Polymarket bet by pulling relevant data in one call, with a clear verb and resource. It distinguishes itself from sibling tools like polymarket_edges or deep_research by describing the classification, fan-out, and evidence-packet pipeline.

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 scopes usage to 'should I bet on X', 'what does the data say about Y', and 'is there edge in Z', with concrete fan-out examples. However, it does not explicitly mention when NOT to use this tool or contrast it with sibling alternatives like deep_research or polymarket_edges, so it misses full exclusion guidance.

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

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

Beyond annotations (readOnly, idempotent, openWorld), the description discloses specific data sources (SEC EDGAR/XBRL, FAERS, FDA), handling of off-calendar fiscal years, result sorting by primary metric, and return format with citation URIs. This rich behavioral context helps the agent anticipate outputs and side effects.

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: triggers, usage preference, type-specific details, output format, and efficiency gain. While longer than average, the complexity of the tool (two entity types, multiple data sources) justifies the length, and it is front-loaded with the most critical information.

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

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

Given no output schema, the description compensates by explaining the return format (paired data + citation URIs) and result sorting. It covers both entity types, constraints (2–5 items), and the tool's advantage, making it complete for selection and invocation without additional context.

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

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

Schema covers both parameters with enum and array descriptions (100% coverage). The description adds meaning beyond the schema by explaining what each entity type pulls (financial metrics for companies, adverse-event and trial counts for drugs), giving examples, and noting sort behavior. This enriches parameter understanding well above baseline.

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

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

The description clearly states the tool performs side-by-side comparison of 2–5 companies or drugs in one parallel call. It specifies the resource (entities) and the action (compare), and distinguishes itself from sequential single-pack lookups and sibling tools 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?

Provides explicit trigger phrases ("X vs Y", "which is bigger", "rank these companies") and a strong directive to prefer this tool over sequential lookups when comparing entities. This gives the agent clear when-to-use guidance and implicitly notes when not to use it (for non-comparison lookups).

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/non-destructive, and the description adds substantial context on top: account/paywall gating for the thorough depth, parallel routing to 5,767 tools, per-depth hop behavior (standard re-angles gaps, thorough chases leads), contradictions[] for standard/thorough, gaps[] that are never invented, semantic excerpting rather than head-truncation, citation_uri present only when resolvable, and latency expectations (15-60s, up to ~90s). No contradiction with readOnlyHint or idempotentHint.

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?

Every sentence carries distinct load-bearing information, and the most critical gate (account requirement) is front-loaded with a signup link. However, it is one wall of text roughly ＂350 words long; the semantic-excerpting and citation_uri mechanics could have been trimmed or bulleted. Dense and valuable, but harder to scan than necessary.

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

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

With no output schema, the description carries the full burden of explaining return values and does so completely: findings packet fields (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), gaps[], contradictions[], the hop field, and citation_uri semantics. It also covers prerequisites, alternatives, parameter behavior, and performance expectations. Nothing an agent needs to select and invoke this tool 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 both parameter descriptions are already detailed. The description still adds value beyond the schema: it ties depth values to pricing (thorough needs a paid plan), hop behavior, contradictions[] availability, and latency bands, and it elaborates question with usage examples and the note that decomposition is the point. This exceeds the schema's meaning, though the schema already carries much of the load, so not a 5.

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 and resource: grounded multi-source research across 1,506 STRUCTURED data sources in ONE call, with concrete example questions ("compare X and Y's regulatory + financial exposure"). Explicitly distinguishes itself from siblings and open-web search with the phrases "this is NOT open-web search" and "For a single lookup use ask_pipeworx." An agent can tell exactly what this tool is for.

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

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

Provides explicit when-to-use and when-not-to-use guidance with named alternatives: use ask_pipeworx if not signed in, for single lookups, and for breaking/current-news topics (because deep_research "returns mostly empty gaps[]" there). Gives positive best-for framing with example question shapes. The key routing decisions relative to the most relevant sibling are fully specified.

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 safety profile is covered. The description adds valuable behavioral context beyond annotations: it returns top-N tools with full input schemas, includes curated examples, and makes results directly callable without a second lookup. This helps the agent know exactly what to expect from the response.

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

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

The description is three sentences, front-loaded with the core purpose, then usage context, then return-value details. The list of topic areas is somewhat long but directly helps the agent judge relevance, and no sentence is wasted.

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

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

There is no output schema, so the description carries the full burden of explaining return values. It clearly states that results include names, descriptions, and full input schemas with curated examples, and that results are ready to call directly. This fully covers the agent's need to understand what the tool returns and how to use it.

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

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

Schema description coverage is 100%, so all six properties including aliases are documented in the input schema. The description reinforces that the query should be a natural language description of the desired task but adds no semantics beyond the schema; thus the baseline score of 3 is appropriate.

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

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

The description opens with 'Find tools by describing the data or task' — a specific verb and resource that clearly differentiates this meta-search tool from the domain-specific sibling tools. It explicitly lists the use cases (browse, search, look up, discover) and the breadth of topic areas, making the purpose unmistakable.

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

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

The description says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives strong positive guidance and implies a contrast with directly calling a known tool, though it does not explicitly name alternatives or exclusion criteria.

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

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

Even with readOnlyHint/openWorldHint/idempotentHint annotations, the description adds substantial behavioral context: patents source 'soft-fails until reactivated,' fda_products showing none is 'expected, not a failure,' empty sections are 'a real no data, not a bug,' private companies return resolved:false with a notes line, and news uses a GDELT→GNews fallback. This goes well beyond what annotations declare.

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 and information-dense, but it is one long uninterrupted paragraph and opens with seven near-identical user-phrase examples. The lengthy source-by-source output breakdown is valuable given no output schema, yet the redundancy and lack of structural formatting keep it from being tightly concise.

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 multi-source tool with no output schema, the description is remarkably complete: it covers input variants, each return section, source fallbacks, soft-fail behavior, expected-empty semantics, and resolved:false handling for private companies. An agent has enough context to invoke the tool correctly and interpret unusual results.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds useful semantic context beyond the schema, particularly that a private company input yields resolved:false with an explicit notes line and that 'company'/'ticker' are fully interchangeable input types. Much of the value/shape explanation is redundant with the schema, but the added failure semantics justify a 4.

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

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

The description opens with multiple natural-language triggers ('Tell me about X', 'research Acme', 'brief me on Tesla') and defines the tool as 'full cross-source profile of a US public company in ONE parallel call.' It lists distinct output sections (cik, recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI), making the purpose and resource unmistakable and distinguishing it from narrower single-source lookups.

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

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

It explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and specifies the accepted input forms (ticker, CIK, company name). It does not explicitly name sibling alternatives like compare_entities or deep_research or state when NOT to use this tool, so it falls just short of full five-level alternative routing.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true, covering safety profile. The description adds context by specifying what gets destroyed—'a previously stored memory'—and frames the action as clearing sensitive data. This goes beyond the structured fields without contradicting them.

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

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

The description is two sentences. The first states the exact action and resource; the second gives usage context and sibling pairing. No wasted words, 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?

This is a simple 1-parameter tool with no output schema. Annotations thoroughly cover destructive and idempotent behavior. The description explains the memory metaphor, when to use it, and how it relates to remember/recall, making it fully self-contained for an agent.

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

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

Schema description coverage is 100%: the 'key' parameter is already described as 'Memory key to delete.' The description's 'by key' reinforces this but adds no new semantic detail (e.g., format, examples, or behavior when key is missing). Baseline 3 is appropriate.

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

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

The description opens with 'Delete a previously stored memory by key,' which is a specific verb and resource. It clearly distinguishes this from sibling tools 'remember' (store) and 'recall' (retrieve) by identifying the destructive action (delete).

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

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds process details (fetching the page, extracting metadata, emitting markdown) and output format (single text blob), which goes beyond the structured data and provides useful context for the agent.

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 (3 sentences) and front-loaded with the core purpose. Each sentence adds value: purpose, process, and use cases. No unnecessary fluff.

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

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

For a simple tool with good annotations and schema, the description is complete. It explains what it does, how it works, output format, and use cases. However, it doesn't mention error handling or edge cases (e.g., invalid URL, max_links bounds), which would make it a 5.

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

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

Schema description coverage is 100% and both parameters have clear descriptions. The tool description does not add extra meaning beyond what the schema provides, so a baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose with a specific verb ('Generate') and resource ('a production-ready llms.txt file'). It explains the process (fetches page, extracts title/description/key links, emits standard format) and distinguishes itself from siblings by focusing on the llms.txt output file. The use cases (client indexing, own project, competitor auditing) further clarify its unique role.

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

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

The description provides clear context on when to use the tool via the 'Useful for' list, covering client work, personal projects, and competitor auditing. However, it does not explicitly state exclusions or name alternative sibling tools, 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, idempotentHint, and destructiveHint=false, so the safety profile is known. The description adds behavioral context by specifying the types of insights returned (spending trends, recent awards, SBIR stats, top contractors), giving the agent a concrete picture of what the tool produces.

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

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

The description is one tight sentence that packs purpose, examples, and return summary without any filler. Every piece of information 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?

With only one parameter, full annotations covering safety, and an output schema present, the description is complete. It explains the tool's purpose, scope, and sample output, and no further caveats are needed for this simple read-only tool.

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

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

The schema covers the single 'agency' parameter with 'Federal agency name'. The description adds realistic examples ('Department of Defense', 'NASA') that clarify expected input format and scope, going beyond the schema's minimal definition.

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 ('Get') and resource ('contracting activity and market insights for a federal agency'), with concrete examples (DoD, NASA) and an enumeration of return content. This clearly differentiates it from sibling tools like govcon_contractor_profile and govcon_opportunity_scan.

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: it is for agency-level landscape insights, which implies when to use it. However, it does not explicitly mention alternatives or exclusions, so it stops short of full guidance.

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

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

Annotations already carry the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false). The description adds return content detail, but no behavioral nuance beyond that (e.g., data quality, latency, or how auth failures are represented). It does not contradict annotations, so a mid-level score is appropriate.

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

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

Two sentences with zero redundancy. The first sentence defines the tool's purpose, the second lists return items and a usage trigger. Every word earns its place, and the key 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?

The description covers purpose, return items, and a use case. Since an output schema exists, explaining return values is not necessary. The only nuance missing is how the optional _apiKey affects behavior, but that is fully documented in the parameter schema. Overall, the context is sufficient for an agent to invoke correctly.

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

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

The input schema has 100% description coverage for both parameters, so the schema already documents company_name and _apiKey in detail. The tool description adds no further meaning about the parameters. Baseline 3 is correct since the description does not compensate beyond schema coverage.

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

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

The description clearly states a specific verb ('Vet') and resource ('government contractor's registration, federal awards, and spending history'), and enumerates the return value types (certifications, past performance, award amounts, contract count). This effectively distinguishes it from sibling tools like govcon_agency_landscape or govcon_opportunity_scan, which target different aspects of government contracting.

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 a clear usage context: 'Use when assessing vendor credibility or experience.' This tells the agent when to select this tool, but it does not explicitly mention when-not-to-use or name alternative tools. That is a minor gap, but the contextual cue is strong enough for easy routing.

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

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

Annotations already declare readOnly/idempotent/openWorld/non-destructive behavior; the description adds transparency about the snapshot data source and the conditional need for _apiKey. This goes beyond the annotations, although the phrase 'opportunity legs' is vaguely worded.

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

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

The description is compact and front-loaded with the search purpose, followed by return contents and API-key note. It earns its sentences, though 'opportunity legs' introduces internal jargon that slightly reduces clarity.

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 a full output schema and informative annotations, the description does not need to explain return schemas. It covers the essential call requirements (keywords, optional set_aside, optional _apiKey) and the snapshot freshness nuance; the only notable gap is that 'by agency' is not operationalized by a parameter.

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 keywords, set_aside, and _apiKey. The description repeats the _apiKey behavior and set-aside examples but does not add substantially new parameter meaning, and 'by agency' is unsupported by any schema property.

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: 'Search open government contracts and grants' against a 'local snapshot of SAM.gov's public Contract Opportunities extract', and enumerates returns (opportunities, set-asides, deadlines, SBIR solicitations). This differentiates it from siblings like govcon_agency_landscape and govcon_contractor_profile, though the phrase 'by keyword or agency' is not directly reflected in the input schema.

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 clearly frames when the tool is relevant (contract/grant search with optional set-aside filters) and gives operational guidance on API-key use for newer postings. However, it does not explicitly state when to prefer this over related govcon siblings or list exclusion criteria.

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

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

With annotations already declaring readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, the description adds valuable context by specifying it returns the caller's subscriptions and listing the returned fields. This goes beyond the annotations without contradicting them.

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

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

The description is two succinct sentences. The first states purpose and return fields; the second gives practical usage guidance. No filler or redundant information.

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

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

For a simple read-only list tool with one optional parameter and no output schema, the description covers the key aspects: what it lists, what it returns, and when to use it. Combined with strong annotations, this is complete.

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

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

Schema coverage is 100% for the single parameter include_inactive, whose description already explains behavior and default. The tool description adds no additional semantic beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource. It also enumerates the returned fields, making it distinct from sibling mutation tools like subscribe 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?

The description provides two explicit use cases: reviewing current subscriptions before adding more, and finding an id to cancel. This implicitly references the subscribe and unsubscribe sibling tools, though it does not name them explicitly or state when not to use the tool.

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

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

Annotations only indicate non-read-only, non-destructive, etc. The description adds valuable disclosure: rate-limited to 5 per identifier per day, free and not counted against quota, returns a claim_token for later status checks, and that the team reads digests daily. This goes beyond annotations and sets accurate expectations for side effects and limits.

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

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

The description is front-loaded with the main action and then covers usage, exclusions, token behavior, and rate limits. It is longer than minimal but each section earns its place. A slight deduction for a motivational sentence ('signal directly affects roadmap') that is not strictly operational, but overall it remains well-structured and scannable.

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

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

For a feedback tool with four optional parameters and no output schema, the description covers everything important: when to use, what to include, how to follow up with a claim_token, rate limits, and what happens after filing. The uniqueness of the tool among siblings is clear, and no critical behavioral 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%, so baseline is 3. The description adds extra meaning for claim_token with a concrete usage example and reinforces message quality guidance (mention Pipeworx tools/packs, avoid pasting user prompts). It also clarifies that claim_token should be used alone, which is not fully detailed in the schema.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes from siblings by scoping exclusively to Pipeworx tools and explicitly stating feedback for other MCP servers won't be handled. The purpose is unambiguous and unique.

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

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

It provides explicit when-to-use criteria: bug, feature/data_gap, praise, and when-not-to-use: any tool not from this Pipeworx connection, with a clear instruction to file elsewhere. It also includes guidance on preferring Pipeworx tool names over end-user prompts and explains claim_token retrieval, making the usage context thorough.

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 and idempotentHint, and the description adds beyond these: it mentions the data source (CF analytics-engine), that no PII is included, and the caching behavior (5min-1h depending on window). It also reveals the result shape (pack, tool, count), which is valuable given no output schema.

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

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

The description is longer than a minimal sentence but every part adds distinct value: what is returned, use cases, data provenance, and caching. It is front-loaded with the primary purpose and remains well-organized.

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

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

Even without an output schema, the description tells the user exactly what is returned (top tools, top packs, total call volume), how the data is aggregated, its source, caching details, and privacy characteristics. This makes the tool self-sufficient for a simple one-parameter interface.

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 single parameter (window) fully, with a description and enum values. The description merely restates the window options without adding new semantic meaning, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Returns the top tools, top packs, and total call volume' over a recent window. It distinguishes itself from sibling tools like discover_tools or recent_alerts by focusing on other agents' live usage patterns.

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 'Useful for' scenarios, which gives clear guidance on when to invoke it. It does not explicitly name alternative tools that should be used instead, but the listed use cases effectively separate it from related tools.

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

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

Beyond the annotations (readOnly/idempotent), the description reveals scan scope (top ~200 markets), Jaccard threshold (≥0.30), placeholder filter (>20% returns null), and output structure. The FILL CHECK section explains how prices are validated against live CLOB depth and warns when not to trade. No contradiction with annotations.

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

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

The description is dense but every section earns its place: it covers modes, examples, filters, output schema, and fill-check caveats. The use of capitalized labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) improves scannability despite overall length.

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

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

With no output schema and only two optional params, the description compensates by detailing the response fields (opportunities[], partition_check), the fill-check pricing logic, and edge cases like skipped_low_similarity and placeholder-dominated partitions. It is complete for an agent to invoke 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?

Although the schema already covers event and topic with descriptions, the tool description enriches them with practical guidance: examples of slugs and seed questions, accepted URL formats, and an explanation of what each mode computes. It also clarifies that calling with no arguments is a valid invocation, which the schema does not convey.

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

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

The description opens with a specific verb+resource+method ('Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks'), and then clearly distinguishes three invocation modes (no args, event, topic) with examples. This differentiates the tool from siblings like polymarket_edge_tracker and polymarket_fill_risk.

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

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

It explicitly states when to use each mode: 'Call with NO args for a trending_scan... pass event for... or topic for...' and recommends 'event (recommended for a specific market)'. It also tells when not to trade (realizable_edge_pp ≤ 0) and directs custom sizing to polymarket_fill_risk.

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, but the description goes far beyond that: it discloses caching ('Cached 1h at the KV level'), diagnostics for empty segments ('_diagnostics so callers can see WHY a segment is empty'), the 24h-move warning, the per-leg Kelly behavior for partition arbs, and the Fed signal caveat. This exceptional transparency helps the agent predict exact behavior and edge cases.

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 very long, dense single paragraph with nested clauses and parentheticals, making it harder to scan than necessary. While every sentence carries substantive information, it sacrifices readability and could benefit from bullet points or clearer segmentation. It is front-loaded well (purpose first), but overall it's more verbose than ideal for an AI agent parsing quickly.

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

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

Given there is no output schema, the description thoroughly explains the response structure: top-level by_segment, fed_candidates, and _diagnostics, plus detailed fields on each opportunity (edge_pp_net, kelly_fraction, market.liquidity, etc.). It also covers filtering behavior, model families, and edge cases. The response shape and gating logic are fully described, so the agent knows exactly what to expect.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds valuable context beyond the schema: it explains tradeable-edge knobs (min_liquidity/max_spread_pp), clarifies the min_partition_leg_kelly behavior with partition overrounds, and gives practical slippage advice ('Bump for very thin partitions; drop to 0 if you have a smarter fill model'). Not every parameter gets extra detail, but the most nuanced ones do.

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

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

The description opens with a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly states what the tool does and immediately distinguishes it from siblings like polymarket_arbitrage and polymarket_fill_risk by positioning it as an edge discovery tool. The phrase 'Built for "what should I bet on today"' further reinforces its purpose and target usage.

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 strong context for when to use the tool: 'agents discover opportunities without paging hundreds of markets' and explicitly frames it for day-to-day betting decisions. It also explains when certain segments may be empty (e.g., concentrated_longshot is 'rare-by-design') and why some filters exist. However, it doesn't explicitly name alternative tools to use instead, though sibling names are available for inference.

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/idempotent/non-destructive, and the description adds substantial behavioral detail: 60-day snapshot TTL, cache-miss gaps, decay computed on daily closes, and the tracked vs expired distinction. This goes well beyond what annotations provide.

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

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

Description is dense but well-organized with ARGS and RESPONSE labels. Every sentence earns its place by explaining behavior, limits, or return shape; 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?

Despite lacking an output schema, the description fully specifies the response fields and their meaning, explains data gaps and TTL, and covers parameter constraints. Highly complete for a read-only analytics tool with simple parameters.

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

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

Schema covers both parameters fully (defaults, clamps, and enum-like values). The description merely restates the defaults without adding new semantics, so the baseline 3 is appropriate.

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

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

Description states a specific analytic purpose ('how long has this edge existed and is it shrinking?') and distinguishes from sibling tools by focusing on persistence/decay rather than current edge values. The verb 'tracker' plus explicit telemetry framing makes the scope clear.

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

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

Provides clear context for when to use (evaluating edge persistence over time) and explains the trade relevance of edge age. However, no explicit exclusions or named alternatives are given, leaving some burden on the agent to infer differentiation from 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 readOnly/openWorld/idempotent/non-destructive, but the description adds rich behavioral detail beyond that: it 'walks the ladder', returns specific fill metrics (top_of_book, vwap_fill_price, slippage_pp), identifies thin_legs, and exposes forced_directional_risk. No contradiction with annotations.

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

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

The description is dense and front-loaded, with no wasted sentences. However, it is a single continuous paragraph covering multiple modes and numerous return fields, which could benefit from structural separation (e.g., bullet points for SINGLE-MARKET vs BASKET). Still, every sentence earns its place given the tool's complexity.

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

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

With no output schema, the description must convey return values and behavior, and it does so comprehensively: return fields for both modes, interpretation of results (capture_ratio, profit_usd, verdict), risk warnings, and clear usage context relative to siblings. The 4-parameter, 0-required tool is fully specified 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% (baseline 3), but the description substantially enriches parameter meaning: it explains the market vs event mode distinction, how size_usd is interpreted differently for buys vs sells vs basket mode (max spend vs target proceeds vs settlement notional), and includes defaults and clamps. This goes well beyond the schema's per-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?

Description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes this from sibling tools (polymarket_arbitrage, polymarket_edges) by focusing on fill risk rather than opportunity detection, and further differentiates single-market vs basket modes.

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

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

Explicit guidance is given: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It names specific alternatives and explains the failure mode (partial fills converting arb into unhedged directional position), making the when-to-use decision unambiguous.

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

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

Annotations already declare readOnlyHint/openWorldHint/idempotentHint, and the description adds substantial behavioral context beyond those hints. It discloses failure and warning signals (compatibility_codes[], pairing_unverified set in EITHER mode), explains that unknown legs are NEVER paired, clarifies that null temporal_alignment means uncomputable rather than aligned, and notes that all spreads are gross because Kalshi fees are not modeled. This is exemplary transparency.

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

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

The description is long, but it is front-loaded with a one-sentence definition and then organized into modes, response shape, safety fields, and counter semantics. Every paragraph adds necessary caveats for correct interpretation; however, the density of warnings makes it read as a wall of disclosures rather than a crisp, easily scanned summary.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: leg-by-leg prices, top_spreads_pp, compatibility_warning/codes, per-entry flags, temporal_alignment semantics, fees_note, and skipped counters. For a complex cross-venue tool with optional parameters and many edge cases, nothing essential 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 input schema already covers 100% of parameters with descriptions and examples, so the baseline is 3. The description adds value by explaining the override relationship — explicit ticker/slug replaces the topic-mapped side — and by stating that both modes produce identical matching and disclosures. It does not add full ticker/slug syntax, but the schema examples carry that weight.

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

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

The description opens with a specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' which precisely identifies what the tool computes. It further distinguishes the signal from non-equivalent bets and describes two input modes, making the purpose unmistakable even among many sibling tools.

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

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

The description explicitly enumerates TWO MODES — topic shortcuts vs explicit kalshi_event_ticker + polymarket_event_slug — and explains that both run the identical token-overlap matcher. It also warns that pre-mapped topics frequently return compatibility_warning and that 'pre-mapped ≠ tradeable.' It does not name sibling alternatives such as polymarket_arbitrage, so there is no explicit when-to-use-this-versus-that routing, but in-tool usage guidance is strong.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotent hint. The description adds behavior beyond annotations by explaining the two modes (retrieve vs. list all keys when key is omitted) and scoping to an identifier. It does not contradict annotations, and the added behavioral context is valuable.

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

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

The description is three sentences, front-loaded with the core purpose, and every sentence adds value: function, usage examples, and scoping/relationships. No wasted words; concise yet informative.

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

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

For a simple tool with one optional parameter, no output schema, and rich annotations, the description is complete. It covers both invocation modes, scoping, and complementary siblings, giving an agent all necessary context to use it correctly.

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

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

Schema description coverage is 100%, so the parameter semantics are fully handled by the schema. The description reinforces what the key parameter does (omit to list all keys) and provides illustrative examples, but it doesn't add meaningful information beyond the schema. Per rubric, baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys.' It clearly distinguishes from siblings like remember and forget by exactly specifying what it does, and gives concrete examples of usage (target ticker, address, research notes).

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

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

Provides explicit when-to-use context: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also states pairings with complementing siblings (remember to save, forget to delete) and notes scoping by identifier, which clarifies the appropriate context for using the tool.

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

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

Annotations already cover readOnly/destructive hints, so the description adds significant context about the persisted feed, the mark_read flag's effect on subsequent calls, and the availability of a public JSON endpoint. The optional state mutation via mark_read is clearly disclosed and does not contradict 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 compact and information-dense, with each sentence covering a distinct aspect: core purpose, return contents, filtering, mark_read semantics, and alternative endpoint. It is front-loaded with the primary action and contains no filler.

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

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

With all 5 parameters optional and no output schema, the description thoroughly covers the tool's behavior, including return contents, filtering, stateful mark_read, and the alternative HTTP endpoint. The unmentioned parameters (limit, unread_only) are fully documented in the schema, so 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%, providing a baseline of 3. The description adds meaningful value by giving a concrete type example ('sec_8k') and explaining mark_read's behavioral impact beyond the schema's simple 'flag returned events read'.

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

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

The description opens with 'Pull fired events from your subscription feed,' clearly stating the action and resource. It further details the return payload (source, citation_uri, raw event payload) and filtering capabilities, distinguishing it from sibling tools like list_subscriptions.

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

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

The description provides usage context by noting 'Polls work fine' and offering an alternative HTTP endpoint for scripts/dashboards, guiding when to use this tool versus direct API access. It also explains the effect of mark_read and filters, but does not explicitly compare against sibling MCP tools.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, and the description adds substantial behavioral context beyond that: it fans out to multiple sources, has a GDELT→GNews fallback with rate-limit/5xx conditions, soft-fails USPTO due to PatentsView API sunset, and returns grouped changes with citation URIs. No contradiction with annotations.

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

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

The description is long but every sentence earns its place: query paraphrases for intent matching, source-fanout behavior, fallback logic, parameter format summary, return shape, and an explicit alternative tool. It is front-loaded with the most important purpose statement and contains no filler.

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

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

Given there is no output schema, the description adequately explains return structure (changes[] grouped by source, total_changes count, citation URIs) and covers source behaviors, fallbacks, and failure modes. It is complete for a tool of this complexity, with no meaningful gaps.

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

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

Schema coverage is 100% and the schema descriptions are already very detailed (e.g., `since` includes both ISO and relative formats, `value` includes ticker/CIK examples). The description mostly restates these details and adds only minor usage nuance such as 'typical monitoring', so it does not significantly elevate meaning beyond the schema.

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

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

The description opens with concrete query phrasings and then states plainly: 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It precisely identifies the resource (company change feed) and the verb (returns recent changes), and explicitly contrasts itself with entity_profile, making sibling differentiation strong.

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 when-to-use guidance via example questions ('What's new with X', 'latest on Y') and an explicit alternative: 'Use entity_profile instead when you want the static profile... regardless of window.' It also gives practical monitoring advice ('Use 30d or 1m for typical monitoring'), satisfying the usage-guidelines dimension fully.

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 idempotent and non-destructive hints; the description goes beyond by revealing that memory is scoped by user identifier, persists for authenticated users, or expires after 24 hours for anonymous sessions. It omits overwrite semantics but provides valuable behavioral context beyond annotations.

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

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

Two sentences pack purpose, usage triggers, storage mechanism, retention policy, and related tools with zero wasted words. The structure front-loads the core function and then gives operational details.

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

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

For a simple two-parameter key-value store, the description covers purpose, when to use, storage scoping, persistence, and relationships to recall/forget. No output schema exists, but return format is not complex. All necessary context is present.

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 for key and value cover 100% of parameters, so the baseline is 3. The description adds illustrative examples of keys (e.g., 'subject_property', 'target_ticker') but does not fundamentally extend schema meaning. It provides marginal value above 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 opens with the specific verb 'Save' and resource 'data the agent will need to reuse later,' clearly distinguishing from sibling recall/forget by stating it stores data. Examples of use cases further clarify scope. The description also explicitly pairs with recall and forget, cementing its unique role.

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

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

The description provides explicit trigger conditions ('when you discover something worth carrying forward') and concrete examples (resolved ticker, target address). It mentions related tools (recall, forget) but does not explicitly state when not to use this tool, so it falls short of a 5.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description reveals rich behavioral details: identifiers are source-labeled, unresolved ones are explicitly listed under 'unresolved', ambiguous matches return figi_candidates rather than asserting a wrong answer, and LEI/FIGI enrichment degrades gracefully. It also explains that an ISIN resolves to the issuing legal entity via GLEIF. This far exceeds what annotations alone provide and gives the agent a clear mental model of side effects and edge cases.

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: opening with user-phrase examples, then diving into supported types and their nuances, and ending with fallback behavior. Every section adds necessary information, and there is no filler. The only minor deduction is that the wall of text could be slightly overwhelming, but the logical organization and front-loaded use case mitigate this.

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 takes on the burden of explaining return behavior. It mentions figi_candidates for ambiguous matches, the unresolved field, source-labeled identifiers, and the specific outputs for drugs (RxCUI + ingredient + brand). It also covers input formats, edge cases (non-US issuers, non-equity instruments), and degradation. For a tool with only two parameters and no output schema, this is remarkably complete.

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

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

Although schema coverage is 100%, the description substantially augments the parameter docs. It provides concrete input examples ('AAPL', 'CH0038863350', 'ozempic'), warns about passing only the issuer name for bonds (avoiding trailing security-class words), and clarifies that 'value' accepts ticker, CIK, ISIN, or name for companies. This goes beyond the schema's basic descriptions and helps the agent format inputs 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 states a specific verb ('resolve') and resource (user-spoken names to canonical identifiers), with concrete examples of use cases. It clearly distinguishes itself from sibling tools by emphasizing that it produces identifiers other tools require as input, and explicitly names the two supported entity types (company, drug). This lets an agent understand exactly what the tool does and why it differs from alternatives like entity_profile or compare_entities.

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

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

The description explicitly instructs 'Use FIRST whenever you have a name but need an ID,' providing a clear when-to-use condition. It also details behavior for company vs. drug types, explains how ISINs map to legal entities, and notes graceful degradation when external sources are unavailable. Although it does not name specific sibling tools to avoid, the 'FIRST' directive and the purpose of supplying inputs to other tools effectively communicate when this tool should be selected.

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 that the tool probes each entity with ai_visibility_check and returns a ranked list with score, confidence, and signal density—useful behavioral details beyond the annotations, which only declare read-only, idempotent, and non-destructive hints. It also implies multiple underlying calls, which is relevant for cost/latency expectations.

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

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

The description is three sentences, front-loaded with the core purpose, then mechanism, use case, and output. Every sentence adds value with no redundancy or unnecessary detail.

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

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

The tool has no output schema, but the description explicitly lists the return fields (score, confidence, signal density). It covers input, mechanism, and use case. It could mention that the first entity is treated as the 'subject', but that is already in the schema, so this is complete enough for a read-only tool with strong annotations.

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

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

Schema coverage is 100% with all four parameters well-described. The description adds some framing (your brand + N competitors) but does not meaningfully enhance parameter understanding beyond the schema. Baseline 3 is appropriate because the schema carries the parameter semantics.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, ranks them, and surfaces the most/least recognized. It distinguishes itself from the sibling tool ai_visibility_check by explicitly stating it probes each entity with that tool, and from compare_entities by focusing specifically on AI visibility rather than generic comparison.

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

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

The description provides a clear use case ('competitive AI-marketing audits') and the question 'does Claude know about us as well as our competitors?' implies when to use this tool versus single-entity checks. It does not explicitly list exclusions or alternatives, but the context is sufficient for an agent to infer appropriate usage.

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

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

Goes beyond annotations by disclosing partial failure behavior, bundlephobia's 5-30s first measurement, and that sources_failed will list timeouts. This enriches the readOnlyHint and idempotentHint annotations with practical runtime 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?

Every sentence contributes: purpose, usage triggers, return payload, ecosystem limits, and failure behavior. No redundant phrasing, and the most critical information is front-loaded.

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

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

Without an output schema, the description provides a detailed list of return fields (summary block, advisories, links, alternative versions) and covers failure modes. It is complete enough for an agent to understand what to expect from the call.

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

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

Schema coverage is 100% and both parameters already have clear descriptions. The description adds no further parameter-specific meaning beyond reinforcing that version defaults to latest, which is already stated in the schema.

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

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

The description opens with a specific verb and resource: 'should I add this npm package to my project' check, clearly stating it fans out to deps.dev and bundlephobia. This distinguishes it from sibling research tools by focusing on npm package evaluation.

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

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

Explicitly states when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also directs non-NPM ecosystems to 'deps.dev:version directly', providing clear exclusions and 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 several behavioral details beyond what annotations provide: it uses BGE-base-en embeddings with cosine similarity over 500-char overlapping windows, has a 200K character limit with truncation and flagging for longer inputs, and returns character offsets and similarity scores. The read-only, idempotent nature is implied by the search operation and aligns with the annotations. There is no contradiction.

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

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

The description is three sentences, each earning its place: the first states the core function, the second provides usage guidance, and the third gives technical implementation details. It is front-loaded with the most important information, uses intentional formatting (CAPS for 'INSIDE') to emphasize key constraints, and contains no filler or redundant content.

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

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

Despite lacking an output schema, the description covers the essential return information (passages with offsets and similarity scores), the operational constraints (character cap, truncation), and the integration with a sibling tool. The tool is a straightforward search operation, and the description fully equips an agent to invoke it correctly and understand its output.

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

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

The input schema already provides 100% coverage for all three parameters (text, limit, query) with clear descriptions, including examples for query. The description adds minor context (e.g., 'Pass the text you already pulled' for text, 'top-N passages' for limit) but does not substantially enhance parameter understanding beyond the schema. Per the rubric, a baseline of 3 is appropriate when schema coverage is high and the description adds marginal value.

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

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

The description opens with a specific verb and resource: 'Semantic search INSIDE a fetched record.' It clearly distinguishes this from sibling tools by emphasizing that it operates on already-fetched text, provides concrete examples (SEC 10-K, article, long tool result), and explicitly describes the return value (top-N passages with character offsets and similarity scores). This goes far beyond the tool name and title, fully clarifying what the tool does.

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

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

The description gives explicit when-to-use guidance: 'Use when the record is too big to cram into the prompt' and explains the benefit (saves context, returns only relevant passages, provides offsets for verifying quotes). It also names a complementary tool (ask_pipeworx_grounded) and describes the workflow (fetch with the gateway, ground over relevant passages). This is clear, actionable guidance on when to use this tool versus alternatives.

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

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

Adds rich behavioral context beyond annotations: returns the new subscription id, feed is always on, SMS requires verified phone, webhook is auto-disabled after 10 failing runs, and signing secret is returned once. No contradiction with annotations (readOnly=false, idempotent=true) is present.

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

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

Though lengthy, every sentence earns its place. The description is front-loaded with purpose, then organized into supported types and delivery channels with concrete examples. No fluff or redundancy; the density is 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 complex nested params and no output schema, the description fully covers return values, auth requirements, all subscription types, delivery channels, verification steps, rate limits, and webhook security. It is complete enough for an agent to invoke correctly without further research.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining type-specific semantics (e.g., items:["5.02"] = officer change) and consolidating examples for sec_8k, polymarket_edge, and fred_series, which helps the agent construct valid params beyond what the schema states.

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

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

The description opens with a specific verb+resource: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly distinguishes from siblings by noting it returns a new subscription id and mentioning the always-on feed accessible via recent_alerts, separating creation from listing/cancellation.

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 usage guidance: requires a Pipeworx OAuth account, warns that anonymous + BYO cannot persist subscriptions, and details delivery alternatives (feed vs email vs sms vs webhook) with prerequisites like phone verification and the 10/day SMS cap. This tells the agent when the tool is appropriate and when it is 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?

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description adds valuable behavioral context: it returns category-bucketed example questions from the live catalog, includes the exact tool and argument shape for each, and accepts an optional topic parameter to focus results. It does not contradict the annotations and explains the output shape without needing an output schema.

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

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

The description is quite long but every sentence adds value: the opening examples help an agent understand natural-language queries, the core purpose is stated, and the parameter behavior is explained. It is front-loaded with an engaging list but that list could be seen as slightly delaying the main point. Still, it is not redundant or padded, earning a 4.

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

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

For a tool with only one optional parameter, no required inputs, no output schema, and strong annotations, the description is fully complete. It explains the purpose, the output structure (category-bucketed examples with tool+argument shape), the parameter behavior, and when to use it. It also names related meta-tools, providing enough context for a newly connected agent to proceed confidently.

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: the `topic` parameter is fully described with its allowed values ('finance | pharma | economics | real-estate | betting | weather | government | science | news') and behavior ('Omit for a cross-category spread'). The description adds only minimal repetition of these values (with 'e.g. finance, pharma, betting') and the notion of 'focus', but no additional meaning 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 the tool's purpose: it is the onboarding entry point for an agent that wants to know what is worth asking. It specifies the verb ('suggest questions' / 'returns category-bucketed example questions') and the resource ('Pipeworx catalog of tools'), and distinguishes itself by being the 'FIRST' tool to use for discovery, with a clear scope of listing example questions with exact tool+argument shape.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and describes the option to call with no arguments or pass a topic. However, it does not explicitly state when not to use it (e.g., for specific data queries) or name direct alternative tools for those cases, only mentioning meta-tools as things to learn about. Thus it is strong on 'when' but lacks explicit 'when-not' and alternative naming.

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 (readOnly=false, destructive=false, idempotent=true), the description adds that the row is deactivated rather than deleted and that ownership is enforced. It also notes historical events remain available via recent_alerts. However, it doesn't describe error behavior (e.g., invalid id, unauthorized cancellation) or return value, which are minor gaps given the simple scope.

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: the core action, the ownership constraint, and the soft-delete behavior with history availability. No fluff, 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?

For a one-parameter mutation tool with strong annotations, the description covers the essential: what it does, constraints, and side effects. The mention of recent_alerts integrates well with sibling tools. No output schema exists but the return value is predictable for a cancel operation, so no gap is significant.

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% — the only parameter 'id' is fully described as 'Subscription id (uuid) returned by subscribe.' The description does not add any additional parameter semantics, so the baseline of 3 is appropriate.

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

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

The description clearly states the action ('Cancel a subscription by id') with a specific verb and resource, and distinguishes it from siblings like subscribe (creation) and list_subscriptions (viewing). The deactivation detail further separates it from a destructive delete.

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: it's the cancellation tool, and ownership is enforced. It implies using recent_alerts for historical events after cancellation, but does not explicitly name alternatives like 'use list_subscriptions to see your subscriptions' or 'use subscribe to create a subscription.' This is clear but lacks explicit when-not/alternative guidance.

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

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

Annotations already declare readOnly/idempotent, but the description adds substantial behavioral context: the SEC EDGAR/XBRL fast path vs. the grounded pipeline, the precise meaning of could_not_verify (not evidence) vs. unsupported, the percent-delta grading, and the inclusion of pipeworx:// citations. No contradiction with annotations.

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

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

The description is dense but well-organized: front-loaded trigger phrases, then purpose, usage, internal routing, return values, and caveats. Every sentence contributes unique information, and the structure makes it easy to scan.

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

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

With no output schema, the description fully explains the return shape (verdict + actual value + citation + reasoning), the nuanced error semantics (could_not_verify vs. unsupported), and the internal routing logic. This is complete enough for correct invocation and interpretation of results.

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

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

Schema coverage is 100% and the schema descriptions are already detailed (claim examples, tolerance_pct range and default cap). The main description adds only contextual mentions like 'exact percent-delta math' without introducing new parameter-level guidance, so it stays at the baseline for high 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 concrete trigger phrases and clearly defines the tool as 'natural-language claim verification against authoritative sources'. It uses a specific verb-resource pair ('verify claims') and distinguishes itself from generic Q&A or research tools by describing the verdict-based output and the structured vs. grounded pipeline.

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 'Use whenever the agent needs to check whether something a user said is factually correct' and clarifies the two kinds of claims (financial vs. other) with different routing. It also notes that it 'replaces 4–6 sequential calls', implying a preference over a multi-tool workflow. However, it does not explicitly name sibling tools as alternatives or state when not to use it.

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