Hubspot

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, describing safety. The description adds behavioral context: default model is free, probing Anthropic requires a BYO key with direct payment to Anthropic, and returns per-model objects with score, confidence, signals, raw_response. No contradictions.

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

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

Description is a single dense paragraph of 3-4 sentences with no wasted words. Front-loaded with main action and key details about default model and optional key. Each sentence adds value.

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

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

Covers main purpose, parameters, return structure (per-model + combined view), and use cases. Missing details on pagination or rate limits, but these are not critical for this tool. Sufficient for agent decision-making given annotations and schema richness.

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 good descriptions for all 4 parameters. The description adds overarching context: default model, free vs paid key, and examples for entity and context. This adds meaning beyond schema descriptions.

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

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

Description clearly states the tool probes LLMs for knowledge about an entity and scores visibility (0-100) per model. It specifies the default model and optional Anthropic probe, and distinguishes from sibling tools like ask_pipeworx or scan_competitor_ai_presence by focusing on multi-model visibility scoring.

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 use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' Describes when to use the optional _apiKey for Anthropic. Does not explicitly contrast with sibling tools, but the context is clear enough 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?

Annotations already signal read-only, idempotent, open-world safe operation. The description adds meaningful context by revealing the routing mechanism ('Routes the question to the right one of 5,798 tools...'), automatic argument filling, and the return of stable pipeworx:// citation URIs. This goes beyond annotations and does not contradict them.

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

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

The description is long but information-dense, with a clear structure: preference, domain list, mechanism, trigger phrases, examples, and a 'START HERE' rule. There is slight redundancy ('even if web search could also answer it' appears twice), but every part contributes to routing decisions. It earns a 4 rather than 5 due to that redundancy.

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

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

Given the absence of an output schema, the description adequately sets expectations by stating it returns a 'structured answer' with 'stable pipeworx:// citation URIs'. It also explains the tool's scope and internal routing, which is sufficient for an open-ended factual-query tool. It could detail the response shape further, but that is impractical across 5,798 underlying tools.

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 in the schema with 100% coverage, including alias explanations. The description adds semantic guidance through trigger phrases and examples of acceptable questions ('current US unemployment rate', 'Apple's latest 10-K'), clarifying the expected content of the question parameter beyond the schema's generic 'natural language' description.

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

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

The description states a clear purpose: it is a natural-language router that answers factual questions by delegating to one of 5,798 tools across 1,517 verified sources and returning structured answers with pipeworx:// citations. It clearly differentiates from web search by saying 'PREFER OVER WEB SEARCH' and enumerates covered domains. However, it does not distinguish itself from sibling variants ask_pipeworx_beta and ask_pipeworx_grounded, so it misses the top bar for sibling differentiation.

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

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

Provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', trigger phrases like 'what is', 'look up', 'get the latest', and concrete examples. It emphasizes using the tool even if web search could answer, clarifying the routing context well. But it does not mention when to prefer sibling variants like ask_pipeworx_grounded/beta or alternatives like deep_research, so it lacks full when-not or alternative guidance.

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

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

Beyond the readOnly/openWorld/idempotent hints, the description discloses the live candidate-routing behavior, the fact that no candidate is currently active, that results are compared against the stable router, and that there is no fallback—it is a full working router. This is exemplary transparency about experimental behavior.

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

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

The description is dense but efficient, front-loading the key identity and experimental status before explaining current behavior and usage. The final fallback clause is slightly emphatic but earns its place by preventing the agent from treating it as a stub.

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 current state, invocation equivalence, and experimental purpose well. The main gap is that the actual response shape is deferred to ask_pipeworx rather than described, which is reasonable for a beta variant but not fully standalone given there is no output schema.

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

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

Schema description coverage is 100%, with all six parameters documented as string aliases for the required question parameter. The description only says 'same arguments' without adding parameter-level meaning, so it stays at the baseline for fully covered schemas.

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 immediately identifies this as the beta version of ask_pipeworx, then precisely defines its scope: an identical universal router with the same 5,798 tools, arguments, and response shape, but with candidate routing improvements. This clearly distinguishes it from the stable ask_pipeworx sibling and from ask_pipeworx_grounded.

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

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

It explicitly says to use it exactly like ask_pipeworx 'when you want the newest routing' and contrasts it with the stable router used for comparison. It does not explicitly state a when-not-to-use case, but the beta/experimental framing makes the distinction clear enough.

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

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

Annotations already indicate read-only, open-world, and idempotent behavior, and the description adds substantial context beyond that: it routes across 5,798 tools, fills arguments, extracts only from the tool result, and returns a structured success or refusal payload. It also discloses the refusal reasons and the additional cost, giving the agent a clear behavioral model.

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

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

The description is dense but every sentence earns its place: core behavior, return shape, refusal reasons, usage conditions, and trade-off with the sibling are all included. It is front-loaded with the most important distinction, 'hallucination-resistant,' and no content 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?

Even without an output schema, the description explains the exact success shape, the refusal shape, all possible refusal reasons, and the operational cost. For a complex tool with rich routing behavior, this is remarkably complete: an agent knows what to expect, when to prefer the alternative, and what failure modes look like.

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 input schema fully documents the single question parameter and all six aliases. The description adds no parameter-specific detail, but the schema already carries that burden, so the baseline 3 applies.

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

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

The description states a specific verb and resource: an answer mode that extracts answers only from tool results, explicitly labeled 'Hallucination-resistant answer mode for high-stakes reads.' It clearly differentiates itself from ask_pipeworx by emphasizing grounded extraction and refusal behavior, so an agent can distinguish it from siblings.

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

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

The description provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also names the alternative, ask_pipeworx, and says to prefer it for casual lookups, and even mentions the extra LLM call cost as a trade-off.

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. The description adds extensive behavioral context: resolution process, fan-out to external APIs, response shapes, safety mechanisms (low-confidence short circuit, closed market handling, wide spread warnings), resolver contract, and resolution-rule risk. No contradictions with annotations.

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

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

The description is long but justified by tool complexity. It is front-loaded with the core purpose, then organized with headings (CLASSIFIERS, FAN-OUT EXAMPLES, RESOLVER CONTRACT, etc.) making it scannable. Every paragraph adds value; no redundant sentences.

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

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

Given the tool's complexity (3 params, no output schema), the description is exhaustive. It covers resolution confidence, parent event extraction, news fallbacks, safety behavior for low-confidence/closed/illiquid markets, and resolution-rule risk. All return value shapes are described in detail, compensating for the lack of output schema.

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

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

Schema description coverage is 100%, so baseline 3 is appropriate. The description does not add meaning beyond schema: it restates market input format and mentions depth default, but does not clarify constraints or provide additional usage details for parameters beyond what is 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 clear verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and distinguishes itself from sibling tools like polymarket_edges and polymarket_arbitrage by focusing on comprehensive research rather than quick edges or arbitrage.

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

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

Explicitly states use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' Provides classifiers and fan-out examples. However, it does not explicitly exclude situations where sibling tools would be better suited (e.g., quick edge check with polymarket_edges).

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

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

Annotations indicate read-only, idempotent, open-world behavior. Description adds specifics: pulls latest 10-K data for companies handling off-calendar fiscal years, FAERS data for drugs, sorts results by primary metric, returns paired data with citation URIs. No contradiction.

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

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

Front-loaded with example queries and core purpose. Every sentence adds value, but slightly verbose with details that could be condensed. Still efficient and well-structured.

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

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

No output schema, but description mentions return type: paired data and citations. Adequate for a comparative tool. Lacks mention of error handling or edge cases, but overall 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?

Both parameters are 100% described in schema. Description adds meaning: for 'type', explains data sources per enum; for 'values', gives examples (tickers/CIKs, drug names) and format. Adds real-world context beyond schema.

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

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

Description clearly states it performs side-by-side comparison of 2–5 entities (companies or drugs) in one parallel call, using example queries like 'X vs Y' and distinguishing from sequential single-pack lookups. The verb and resource are specific and differentiate from sibling tools.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing clear usage guidance. Example queries further indicate when to use.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral context beyond these: parallel decomposition across 5,798 tools, explicit gaps[] never-invented behavior, depth-tier differences (quick/standard/thorough), contradiction scanning, semantic excerpting of large records, citation resolvability guarantee, and expected latency ranges (15-60s, up to ~90s). It also discloses account/pricing requirements, which is critical behavioral information.

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 dense with high-signal information; nearly every sentence covers a distinct mechanic (auth, sibling routing, data-source scope, parallel routing, return packet, gaps, depth variation, contradictions, excerpting, latency). Starting with the ACCOUNT REQUIRED caveat is a bit unusual, but it is arguably the first practical gate. Minor structural redundancy exists (the 'not many' pun and parenthetical examples stretch length slightly).

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

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

Given no output schema, the description thoroughly covers return format (findings packet, fields, citations, gaps, contradictions), pagination-like caveats (latency), error-avoidance behavior (never invented), and depth semantics. For a complex research tool with no output schema, this is unusually complete; an agent can form correct expectations of the result and side effects.

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 description enriches both params: it explains what 'depth' values actually do (quick=single hop, standard=gap recovery + contradictions, thorough=paid iterative hop), and clarifies that 'question' should be broad/multi-part because 'decomposition is the point.' This goes well beyond the schema's enum descriptions.

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

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

The description opens with a clear verb-resource pair: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources... in ONE call.' It explicitly distinguishes from open-web search and names sibling ask_pipeworx as the alternative for signed-out users. It also specifies what the tool returns (findings packet with verbatim evidence, confidence, source, fetched_at, citations, gaps[]), making its purpose concrete.

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

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

The description explicitly states when to use it ('Best for broad/multi-part questions over structured data') and when not to ('For a single lookup use ask_pipeworx instead'). It also adds a conditional: if not signed in, use ask_pipeworx. This is clear routing guidance relative to siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: returns top-N most relevant tools with names, descriptions, and full input schemas (with examples), and each result is ready to call directly. No contradictions.

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

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

The description is a single paragraph that front-loads the purpose and usage context. It lists many domain examples efficiently. While not extremely concise, every sentence serves a purpose. Slight improvement possible in structure.

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

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

No output schema exists, but the description fully explains what is returned: top-N most relevant tools with names, descriptions, and full input schemas (with curated examples), and that each result is directly callable. Parameters are well documented via schema and examples. Complete for a discovery tool.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds examples of queries and mentions aliases, but does not provide additional semantic depth beyond what is in 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 'Find tools by describing the data or task', using a specific verb and resource. It distinguishes the tool from siblings by positioning it as a browser/discovery tool, contrasting with specific tools like entity_profile or validate_claim.

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 when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available', providing clear context for when to use. It does not explicitly state when not to use, but the directive is sufficient.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, and the description adds substantial context beyond that: source fan-out list, USPTO soft-fail behavior, expected empty fda_products for small-molecule-only companies, sources_used/sources_failed semantics, and resolved:false handling. 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?

Long but dense, and front-loaded with usage examples followed by the core definition. Every segment about return sections and failure modes adds needed context, especially since there is no output schema, though the opening example list is slightly overlong.

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

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

Despite having no output schema, the description enumerates all major return sections (CIK, filings, fundamentals, patents, contracts, FDA products, hiring, news, LEI) and explains source success/failure semantics. It gives enough information for an agent to call the tool correctly without requiring additional lookups.

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

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

Schema description coverage is 100% and already documents ticker/CIK/name, the type enum, and interchangeability. The description mostly restates this with examples; it adds useful behavioral context around private-company resolution but not much new parameter 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 states a specific resource (a US public company) and action (build a full cross-source profile), with many concrete query examples. It differentiates the tool from chaining single-pack SEC/XBRL/news lookups and positions it as a holistic one-call research tool.

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

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

It explicitly says to ALWAYS PREFER this tool over chaining single-pack lookups when the user asks for a holistic view, and provides trigger-phrase examples and accepted input forms. It also sets scope expectations: private companies return resolved:false with notes rather than a bare failure.

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?

Description complements annotations by specifying conditions (stale, done, sensitive) and the destructive action. Annotations already indicate idempotent and destructive, so 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?

Three concise sentences with front-loaded action verb. No wasted words; every sentence adds value.

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

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

Adequate for a simple delete tool with one parameter and annotations covering safety profile. Lacks output schema but not necessary here.

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 one parameter fully described. The description does not add further semantic detail beyond the schema, so baseline 3 is appropriate.

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

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

Clearly states the action ('Delete') and the resource ('a previously stored memory by key'). Differentiates from siblings by mentioning 'remember' and 'recall'.

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

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

Provides specific scenarios for use (stale context, task done, clear sensitive data). Does not explicitly state when not to use, but gives clear context and pairing advice.

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?

Descriptions adds significant context beyond annotations: fetches page, extracts title/description/key links, emits standard markdown format, ready to deploy. Non-contradictory to 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 plus a bulleted list of use cases, front-loaded with verb and resource, no wasted words.

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

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

Covers input, process, output format, and use cases adequately. No output schema needed as output is described as 'single text blob in standard llms.txt markdown'.

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 already provides 100% coverage with descriptions for both parameters; description adds minimal extra meaning (e.g., 'default 25 link entries' mirrors schema). Baseline 3.

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

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

Clearly states verb 'Generate' and resource 'llms.txt file for any URL', distinguishes from sibling tools by specific output format and use cases (e.g., AI crawler indexing, auditing).

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 lists three use cases (client indexing, personal drafting, competitor auditing) but does not compare with or exclude sibling tools like ai_visibility_check or scan_competitor_ai_presence.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the description carries a lighter burden. It adds context by listing returned fields, which is helpful but does not disclose additional behavioral traits beyond what annotations imply.

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

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

Two sentences, front-loaded with the action and resource, no unnecessary words. Every sentence adds value.

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

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

With only one parameter, full schema coverage, annotations present, and an output schema (known from context), the description is complete. It adequately describes what the tool does and returns.

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

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

Schema description coverage is 100% with a clear description for the only parameter 'id'. The description adds 'by ID' but no further 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 action ('Fetch'), the resource ('company's full profile by ID'), and enumerates return fields (name, domain, industry, revenue, custom properties). This distinguishes it from sibling tools like hs_get_contact or hs_get_deal.

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

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

The description implies usage when you have a company ID, but provides no explicit guidance on when to use this tool versus alternatives like hs_list_companies or hs_search_contacts. No exclusions or context are mentioned.

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 non-destructive nature. Description adds context about returning all custom properties, which complements annotations. No contradictions.

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

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

Single front-loaded sentence containing all essential information (action, resource, output) with no wasted words.

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

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

Simple tool with one parameter, full schema coverage, rich annotations, and presence of output schema. Description fully covers necessary context for a single-entity fetch operation.

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

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

Schema coverage is 100% with clear schema description for 'id'. Description simply says 'by ID', adding no extra meaning beyond the schema. Baseline 3 applies.

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

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

Description uses specific verb 'Fetch' and resource 'contact's full profile', lists returned fields (name, email, phone, company, all custom properties). Clearly distinguishes from siblings like hs_list_contacts (bulk list) and hs_search_contacts (search by criteria).

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?

Description implies usage via ID but provides no explicit guidance on when to use this tool versus alternatives (e.g., hs_search_contacts, hs_list_contacts). Does not state exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds value by specifying the data returned (deal details plus linked contacts and companies), which goes beyond the annotations. No contradictions.

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

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

Two concise sentences with front-loaded action and immediate value. No unnecessary words.

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

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

Given a single required parameter and the presence of an output schema, the description provides sufficient context (returned fields) to set expectations. No further details are needed.

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

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

The input schema has 100% coverage for the single 'id' parameter, described as 'HubSpot deal ID'. The description does not add further detail (e.g., format or example), so it meets the baseline.

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

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

The description clearly states the action ('Fetch a deal's full details by ID') and specifies the resource ('deal'). It lists the key fields returned (deal name, amount, stage, owner, linked contacts and companies), distinguishing it from sibling tools like hs_get_company or hs_get_contact.

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?

While no explicit when-to-use or when-not-to-use is given, the description clearly implies usage for retrieving a single deal by ID. The sibling context (e.g., hs_list_deals for listing) provides implicit differentiation. A brief mention of when to prefer hs_get_deal over hs_list_deals would improve clarity.

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. The description adds value by specifying returned fields and pagination behavior, which are beyond the annotations.

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

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

Two sentences with no waste: first states purpose, second states output and pagination. Efficient and 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?

Given the simple list tool with annotations and output schema present, the description covers the necessary context: what it returns and how to paginate. No gaps remain.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description only mentions pagination generally without adding new meaning, so it meets 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 uses 'Browse all companies in your HubSpot workspace' to clearly indicate a list operation. It distinguishes from sibling tools like hs_get_company (single) and hs_list_contacts (different entity) by specifying the resource and 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?

While it implies use for listing companies, it does not provide explicit guidance on when to use this tool vs alternatives like search or single retrieval. No when-not or alternative tools are mentioned.

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 signal readOnlyHint, idempotentHint, and destructiveHint=false. The description adds value by clarifying the paginated nature and the specific fields returned, which helps the agent understand behavior beyond the annotations.

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

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

Three concise, front-loaded sentences: purpose, return values, and pagination. Every sentence adds essential information with no filler.

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

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

Given the simplicity of the tool (2 params, output schema exists), the description covers purpose, returned data, and pagination. It does not mention potential errors or rate limits, but for a read-only list tool, the coverage is nearly complete.

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

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

The input schema has 100% description coverage, so baseline is 3. The description reinforces that 'limit' and 'after' are for pagination, which is helpful but not novel beyond the schema. No additional parameter semantics are added.

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 ('Browse') and resource ('contacts in your HubSpot workspace'). It specifies what is returned (IDs, names, emails, properties) and how pagination works, making the tool's purpose distinct from sibling tools like hs_search_contacts.

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

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

No explicit guidance on when to use this tool vs. alternatives (e.g., hs_search_contacts). The description implies browsing all contacts but does not exclude filtering or searching scenarios, leaving the agent to infer usage context.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, covering safety and idempotency. The description adds clarity that this is a read-only browsing action returning specific fields, which is useful context beyond annotations.

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

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

Two concise sentences: first states purpose and return fields, second explains pagination. No unnecessary words, highly efficient.

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 is fairly complete given the output schema exists (claimed) and the annotations cover behavioral traits. It explains the tool's function, output fields, and pagination. Could optionally mention the default limit (10) but schema covers that.

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

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

Schema coverage is 100% with descriptions for both parameters. The description mentions pagination with limit and after but adds no new meaning beyond what the schema already provides. 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 verb 'Browse' and the resource 'all deals', and lists return fields (IDs, names, amounts, pipeline stages, close dates). This distinguishes it from sibling tools like hs_get_deal (single deal) and hs_list_contacts (list contacts).

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

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

The description implies use for listing all deals without filters, but does not explicitly provide guidance on when to use this tool versus alternatives like hs_search_contacts or hs_get_deal. No exclusion criteria or contextual comparisons are given.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds search scope but no additional behavioral traits beyond annotations. 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?

Two sentences that are front-loaded with the core action and usage context. No unnecessary words.

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

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

Given the presence of output schema and comprehensive annotations, the description covers the primary use case. Could mention that it returns matching contacts, but not essential.

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

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

Schema covers both parameters (query, limit) with descriptions. The description adds semantic value by indicating searchability by custom properties, which is not 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 clearly states the action (search), resource (contacts), and criteria (name, email, custom properties). It differentiates from sibling tools like hs_list_contacts by targeting specific people.

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

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

Provides a basic usage context ('when you need to find specific people') but does not explicitly state when not to use or mention alternatives like hs_get_contact for single contact by ID.

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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds context on default behavior (active only) and the include_inactive parameter, enhancing 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?

Two sentences: first defines purpose and output, second provides usage guidance. No filler, efficient and clear.

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

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

For a simple list tool with one parameter and no output schema, the description covers purpose, output fields, usage context, and parameter default. Complete and sufficient.

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

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

Schema coverage is 100%, so description adds minimal value beyond the schema. It clarifies the default for include_inactive ('default false'), but no further semantic enrichment.

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?

Explicitly states 'List the caller's active subscriptions' and enumerates return fields. Clearly distinct from sibling 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?

Provides explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Clearly states when to use this tool.

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

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

With all annotations false, the description bears full responsibility for disclosing behavior. It reveals the two-step claim_token flow, rate-limiting (5 per identifier per day), the team's daily digest review and roadmap impact, and the instruction not to paste end-user prompts. It even states the tool is free and doesn't count against quota. No contradiction with annotations.

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

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

Though longer than average, every sentence earns its place. The description is front-loaded with the core purpose and then sequentially covers when-to-use, exclusions, operational semantics (claim_token, rate limit, quota), and user guidance. There is no fluff or repetition; the structure makes the tool's requirements and constraints immediately scannable.

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

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

This is a moderately complex tool with 4 parameters, a nested object, and no output schema. The description covers the full behavioral contract: when to use, what to report, how the claim_token works, constraints (rate limit, quota), and scope boundaries. It even addresses the 'not sure' case with a heuristic (tool names listed by this connection). Complete enough to invoke correctly without further clarification.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by showing a concrete claim_token usage example ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'), clarifying that claim_token should be used 'with no other arguments,' and reinforcing message specificity (which tool, what error). These additions go beyond schema text without being redundant.

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

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

The description opens with a clear, specific verb-plus-resource statement: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly lists the feedback categories (bug, feature/data_gap, praise) and distinguishes this tool from sibling tools like ask_pipeworx or discover_tools by framing it as a reporting channel for Pipeworx tool issues.

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 a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides a clear exclusion and alternative: if the tool came from a different MCP server, file it with that server instead, and clarifies how to identify Pipeworx tools. This is exemplary usage direction.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds context: data source (CF analytics-engine), no PII, caching behavior (5min-1h). 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 well-structured with a brief overview followed by a bullet list of use cases. It is not overly long, though the bullet list could be integrated more tightly. Still effective.

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

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

Given the tool's simplicity (1 optional param, no output schema), the description covers purpose, data source, privacy, and caching. It mentions the output structure ('pack, tool, count'), which aids understanding. Slightly more detail on the response format could improve completeness.

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 the single parameter with enum and description. The description adds practical guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand,' enhancing understanding beyond the schema.

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

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

The description clearly states it returns 'top tools, top packs, and total call volume' for trending activity. It specifies the time window and multiple use cases, distinguishing it from sibling tools like discover_tools and ask_pipeworx.

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?

Three explicit use cases are listed (discovering hot data sources, confirming canonical tool, seeing alignment). While it does not explicitly mention when not to use, the context is clear and helpful for selecting this tool over alternatives.

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

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

The description richly details internal logic (semantic anchor, partition filter, fill check) and response structure. All behavioral traits are disclosed beyond what annotations provide (readOnlyHint, idempotentHint, etc.), explaining edge cases like placeholder filtering and fill check conditions.

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 thorough but long; however, it is well-structured into distinct sections (event, topic, semantic anchor, partition filter, response, fill check). Each sentence adds essential detail, though slight redundancy in all-caps headers could be tightened.

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

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

Despite no output schema, the description fully documents the response format for each mode and explains fill check output fields. It covers error cases (placeholder fraction >20%) and references sibling tools for custom sizing, making it complete for a complex tool.

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

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

With 100% schema coverage, baseline is 3, but the description adds significant value: explains modes in depth, provides examples (event slugs, topic questions), and clarifies parameter behavior (e.g., full URLs accepted). This goes well beyond the schema descriptions.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes from siblings by specifying the method and providing mode-specific behavior (trending_scan, event, topic), making it highly specific.

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

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

Explicit guidance on when to use each mode: no args for trending_scan, event for specific market, topic for cross-event scanning. It also recommends polymarket_fill_risk for custom sizing, providing clear alternatives and context.

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

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

The description adds significant behavioral context beyond annotations: it explains caching (1h at KV level), output segments (by_segment with model families), diagnostics for empty results, and treatment of Fed bets. It aligns with readOnlyHint and other 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 very long and dense with algorithmic formulas and model details. Although front-loaded with purpose, it contains excessive technical content that could be condensed for an AI agent.

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

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

Despite no output schema, the description comprehensively explains the output structure (by_segment, fed_candidates, diagnostics) and behavior like caching, filtering, and empty segment reasons. It is complete for the tool's complexity.

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

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

Schema coverage is 100% with detailed parameter descriptions. The description reiterates some knob usage (e.g., min_liquidity) but does not add substantial meaning beyond the schema. Baseline 3 applies.

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

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

The description explicitly states the tool scans Polymarket markets to find opportunities where Pipeworx data disagrees with market price, with a clear purpose for 'what should I bet on today'. It distinguishes itself from siblings like polymarket_arbitrage by focusing on Pipeworx-derived edges.

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

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

The description provides clear context for when to use the tool, such as discovering opportunities without paging hundreds of markets and using tradeable-edge knobs like min_liquidity. However, it does not explicitly state when to use sibling tools like polymarket_arbitrage or polymarket_edge_tracker as 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 adds significant behavioral detail beyond the annotations, including time-series construction, signed edge values, trend computation details, expired opportunity handling, snapshot date gaps, and history limits. All annotations (readOnlyHint, idempotentHint, destructiveHint) are consistent and further reinforced.

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 detailed but well-structured: it starts with a clear purpose, then explains arguments, response format, and limitations. It uses formatting (caps for keys) and is front-loaded. Slightly verbose but not excessive 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?

Since there is no output schema, the description takes full responsibility for explaining return values (tracked[], expired[], snapshot_dates[]), their fields, and computational details. It also covers edge cases like gaps and TTL limits, making it complete for an agent to use effectively.

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

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

The input schema already has 100% coverage with parameter descriptions. The description adds minor context (e.g., 'snapshot family' for window, max 30 for days) but mostly reiterates schema info. Given the high schema coverage, the added value is marginal.

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

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

The description clearly states the tool's purpose: edge persistence and decay telemetry from daily snapshots. It uses specific verbs (track edges over time, compute first_seen, trend, decay) and distinguishes itself from sibling tools like polymarket_edges (which likely shows current edges only) and polymarket_arbitrage.

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 contextual guidance on when to use this tool (e.g., comparing fresh vs. old edges) and implies it complements polymarket_edges. However, it does not explicitly state when not to use it or list alternative tools for different needs.

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 explains the tool's walk-the-ladder logic for single-market mode, return fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and basket mode details including theoretical_sum, realizable_sum, capture_ratio, and directional risk. It adds behavioral context beyond the annotations (readOnlyHint, idempotentHint) by detailing what the tool does and its limitations.

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

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

The description is several paragraphs long, but it is well-structured with clear sections (summary, requirements, single-market, basket, usage guidance). Every sentence adds value, and the key information is front-loaded. While it could be slightly more concise, the complexity justifies the length.

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

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

Despite lacking an output schema, the description comprehensively covers return fields for both modes, parameter behavior, and risk warnings. It addresses the tool's complexity (two modes, edge cases like thin legs) and provides enough context for an AI agent to use it correctly.

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

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

Schema coverage is 100% but each parameter's description is brief. The tool's description expands on them significantly: for example, size_usd is clarified as 'USD to spend (buys) or target proceeds (sells)' in single-market mode and 'settlement notional' in basket mode, adding meaning beyond the schema. The distinction between market vs event parameters and the default behavior for side is also explained.

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 checks 'realizable-vs-theoretical edge against live CLOB order-book depth' and differentiates between single-market and basket modes. It specifies the exact resource (Polymarket order books) and action (edge check), distinguishing it from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

The description explicitly tells when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also warns against partial basket fills converting arb into directional positions, providing clear guidelines on when not to rely on theoretical edges.

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

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

Annotations already mark it read-only/idempotent, and the description goes well beyond them: it discloses that returned pairs can still carry compatibility warnings, that unclassified legs are never paired, that temporal_alignment null means unknown rather than aligned, and that spreads are gross because Kalshi fees are not modeled. No contradiction with the annotations.

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

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

The description is long but tightly organized into labeled sections (modes, response, safety fields, skipped counters, fees), and nearly every sentence carries a distinct disclosure. It earns its length given the tool's complexity, but a reader must digest a large wall of text.

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

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

With no output schema, the description carries full responsibility for return semantics, and it delivers: leg-by-leg prices, spread top_spreads_pp, compatibility fields, skipped counters, fee treatment, and the temporal_alignment object are all explained. An agent has enough context to invoke it correctly.

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

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

Schema coverage is 100% and the description still adds meaning by explaining the two modes, how explicit tickers override topic-mapped sides, and that both modes run the identical matching logic. This is meaningful enrichment over the schema's field descriptions, though not a radical leap.

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

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

The description opens with a clear definition ('Cross-venue spread between Kalshi and Polymarket for the same resolving question') and elaborates exactly what the tool computes. It does not name a sibling like polymarket_arbitrage or polymarket_edges, so it stops short of explicit sibling differentiation.

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

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

It gives strong, user-actionable guidance for choosing between the topic shortcuts and explicit event pairing, and warns that pre-mapped topics often return compatibility warnings. However, it never explicitly contrasts when to call this versus sibling spread/arbitrage tools, so exclusions are implied rather than stated.

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

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

Annotations already indicate read-only and non-destructive behavior; description adds scoping by identifier, enhancing transparency 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?

Four concise, front-loaded sentences with no wasted words; structure aids quick comprehension.

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

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

For a simple tool with one optional parameter and no output schema, the description covers retrieval, listing, scoping, and pairing with other tools completely.

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 describes the key parameter; description adds no new parameter meaning beyond what schema provides.

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

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

The description clearly states the tool retrieves a value by key or lists all keys, distinguishing it from siblings like remember and forget.

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

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

Explicitly states when to use (look up previously stored context) and pairs with remember/forget, but does not specify when not to use.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds that mark_read:true flags events as read, which is a behavioral trait (mutating state) not fully captured by annotations. It also mentions the raw payload and citation_uri format. No contradictions with annotations (though readOnlyHint might be questionable, the description is transparent).

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

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

The description is four sentences, front-loaded with the main purpose, then details on returned fields, filtering, mark_read, and a note on polling. Every sentence adds value 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?

No output schema, but the description states returned fields (source, citation_uri, raw payload). It also covers filtering, mark_read behavior, and mentions the HTTP endpoint. For a read-oriented list tool, this is complete and sufficient.

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

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

Schema description coverage is 100%, so the schema already documents all 5 parameters. The description provides minor additional context (e.g., example for type, consequence of mark_read), but does not add significant 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 pulls fired events from the subscription feed, returns recent alerts with specific fields (source, citation_uri, payload), and supports filtering. This is a specific verb+resource combination that distinguishes it from siblings like list_subscriptions (which likely lists subscriptions, not alerts).

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

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

The description notes that polling works fine and the feed is also available via an HTTP endpoint for scripts/dashboards, providing context for when to use the tool vs the alternative. However, it does not explicitly compare to sibling tools like list_subscriptions or recent_changes, leaving some ambiguity.

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 (readOnlyHint, idempotentHint), the description adds details about parallel calls, fallback behavior (GDELT→GNews), soft-fail for USPTO, and rate-limiting context. 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 efficient and front-loaded with example queries, but is a single dense paragraph. Slight improvement possible with structure, but overall concise and 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?

Despite no output schema, the description explains return format (grouped changes, total_changes, citation URIs). Also notes limitation (only 'company' type). Complete for a tool with 3 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?

All parameters have schema descriptions (100% coverage), but the description adds value by explaining `since` with relative shorthand examples and clarifying `value` accepts tickers or CIK. Justifies a 4 rather than baseline 3.

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

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

The description clearly states the tool's purpose as a change feed for a company, listing example queries and specific sources (SEC EDGAR, GDELT→GNews, USPTO). It distinguishes from sibling 'entity_profile' by noting the difference between dynamic changes and static profile.

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

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

Explicitly states when to use (e.g., 'What's new' queries) and provides an alternative: 'Use entity_profile instead when you want the static profile'. This gives clear guidance on tool selection.

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

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

Annotations already indicate idempotence and non-destructiveness. The description adds context about key-value scoping by user identifier and persistence duration (persistent for authenticated, 24h for anonymous), which is valuable beyond annotations. However, it doesn't explicitly address overwriting behavior on duplicate keys, but the idempotent hint covers that case.

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

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

The description is concise (4 sentences) and well-structured, with the main purpose in the first sentence, followed by usage guidance, technical details (scoping, persistence), and a hint at related tools. No wasted words.

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

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

The description is comprehensive for the tool's simplicity: it explains what to store, when to use it, how it scopes data, persistence rules, and how it relates to recall and forget. No critical information is missing.

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

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

With 100% schema coverage, the parameter descriptions in the schema are already detailed with examples. The tool description adds no significant new parameter information beyond restating the examples, so it doesn't elevate above the baseline.

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

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

The description clearly states the tool saves key-value data for later reuse, distinguishes from related tools recall and forget, and provides concrete examples of when to use it.

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

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

The description provides explicit usage guidance with examples (resolved ticker, target address, user preference), indicates it's for cross-session reuse, and references sibling tools for retrieval and deletion, making it clear when to use this tool.

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

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

Annotations already signal read-only, idempotent, open-world behavior. The description adds substantial behavioral detail: multi-source identity cascading, graceful degradation when GLEIF/OpenFIGI is unavailable, ambiguity handling via figi_candidates, explicit unresolved identifiers, and source labeling. This goes well beyond the annotations.

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

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

The description is information-dense with no obvious filler, and the main instruction is near the front. However, the company path is one long, run-on parenthetical and the overall text would be much easier for an agent to parse with bullets or shorter sentences.

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 resolver with no output schema, the description covers supported types, input variants, failure/ambiguity behavior, fallback degradation, and return contents for drugs. An agent has enough context to select and invoke the tool correctly.

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

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

Schema coverage is 100%, but the description adds meaning beyond the schema: accepted input forms for company (ticker, CIK, ISIN, company name), the crucial warning to pass only the issuer name and not the full noun phrase for bond lookups, and brand/generic examples for drug lookup.

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

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

The description states a clear, specific job — resolving a user-spoken NAME to canonical identifiers — and reinforces it with concrete user-phrase examples and supported types. It is easy to distinguish from sibling tools like entity_profile or compare_entities because its function is identifier resolution, not profiling or comparison.

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

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

The description gives an explicit trigger: 'Use FIRST whenever you have a name but need an ID.' It also explains the tool replaces 2-3 manual lookups. It does not name alternative sibling tools or state when it should NOT be used, so it lacks exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds behavioral details: it probes multiple entities, treats first as subject, ranks by score, and returns confidence/signal density. No contradictions with annotations.

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

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

Two sentences: first describes core action and process, second gives use case and output. No fluff, front-loaded, and highly 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 tool with 4 parameters and no output schema, the description explains the return format (ranked list with score, confidence, signal density) and the probe mechanism. It lacks explanation of edge cases (e.g., invalid entity count) but schema covers that. Overall sufficient.

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

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

Schema coverage is 100% and schema descriptions are detailed (e.g., first entity as subject). The description does not add semantic meaning beyond what the schema already provides, so baseline 3 applies.

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

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

The description clearly states it compares AI visibility across multiple entities side-by-side using ai_visibility_check, ranks them, and returns metrics. It distinctly separates from sibling tools like ai_visibility_check (single entity) and compare_entities (likely different 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 gives a concrete use case (competitive AI-marketing audits) with an example question. It implies that for a single entity check one would use ai_visibility_check, but does not explicitly state when not to use this tool or list alternatives. Still, the context is clear and helpful.

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

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

Adds substantial behavioral context beyond annotations: describes fan-out, return summary block, per-advisory detail, links, alternative versions, and graceful degradation with sources_failed list. No contradictions with annotations.

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

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

The description is moderately long but well-structured with clear sentences. Every sentence adds useful information; could be slightly more concise but is effective.

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

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

Given the tool's complexity (multiple sources, timing, partial failures), the description covers return format, behavior, limitations, and ecosystem scope. No output schema exists, but description compensates adequately.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by noting scoped packages are accepted for the package parameter and that version defaults to latest.

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

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

The description clearly states it's a composite check for adding an npm package to a project, fanning out to deps.dev and bundlephobia. It distinguishes itself by specifying NPM ecosystem only, while other ecosystems are handled by other tools.

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

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

Explicitly says 'Use whenever an agent asks ...' providing concrete examples. Also mentions timing caveats for bundlephobia and partial failure handling, and notes alternatives for other ecosystems.

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

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

Beyond annotations (readOnlyHint, etc.), description adds details: embedding model (BGE-base-en), chunking (500-char overlapping windows), character cap (200K chars with truncation flag), and return format (passages with offsets and similarity scores). No contradictions.

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

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

Front-loaded with purpose, then adds necessary details. Single paragraph is efficient, though some sentences are slightly dense. No waste.

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?

Fully explains behavior, limitations, return format, and usage context (pairing with another tool). No output schema, but description compensates by detailing what passages contain (offsets, scores).

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. Description adds examples for queries and clarifies that text is the document to search, max chars, and limit defaults. Adds value beyond schema.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' with specific verb and resource. It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded.

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

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

Explicitly says when to use: 'when the record is too big to cram into the prompt' and mentions alternative tool ask_pipeworx_grounded for grounded reasoning.

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 show mutability, open world, idempotency, and non-destructiveness. The description adds significant behavioral context: requires a Pipeworx OAuth account, delivery constraints (email, SMS with caps, webhook HMAC auto-disable after 10 failures), and the need for phone verification. This goes well beyond the annotations.

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

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

The description is long but well-structured with paragraphs for type explanation and delivery channels. It front-loads the main purpose and key requirements (OAuth account). While it could be slightly more concise, every sentence serves a purpose and adds 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?

Given the tool's complexity—multiple subscription types, nested parameters, delivery channels with constraints, and no output schema—the description is comprehensive. It covers all aspects needed for an agent to use the tool correctly, including authentication, type-specific params, and delivery options.

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

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

Schema coverage is 100%, but the description provides rich additional meaning: each subscription type is explained with examples (e.g., sec_8k with items codes, polymarket_edge with topic), and the delivery object is detailed with constraints and webhook signing. The description adds substantial value beyond the schema.

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

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

The description starts with 'Create a proactive monitoring subscription to a live-data event stream,' which is a specific verb+resource combination. It also mentions 'Returns the new subscription id,' further clarifying the action. The sibling tools include list_subscriptions and unsubscribe, making this tool's distinct purpose 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?

The description explains when to use this tool: to create subscriptions for specific event types. It provides context on authentication and delivery channels but does not explicitly state when not to use it or mention alternatives like list_subscriptions or unsubscribe. The sibling tool list helps, but the description could be more explicit.

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 readOnly=true, idempotent=true, etc. Description adds behavioral context: returns category-bucketed examples with tool shapes, drawn from live catalog. No contradictions, and it explains the output format beyond annotations.

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

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

The description is front-loaded with trigger phrases and structured in a single paragraph. It is comprehensive but slightly verbose; could be trimmed without losing clarity. Good use of dash-separated list within text.

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

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

Given no output schema, the description fully explains what is returned: category-bucketed example questions with exact tool and argument shapes. It covers optional parameters and the catalog source, providing complete context for an onboarding tool.

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

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

Schema coverage is 100% with a clear description for the 'topic' parameter. The description adds value by listing valid topic values and explaining the behavior when omitted (full spread), which is not 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 clearly states that the tool returns category-bucketed example questions with exact tool and argument shapes, serving as an onboarding entry point. It lists trigger phrases and distinguishes itself from siblings like discover_tools by focusing on suggesting questions rather than discovering tools.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you', providing clear context. It mentions optional topic filtering but does not compare with direct siblings like discover_tools, which could cause slight ambiguity.

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 important behavioral detail beyond annotations: 'The row is deactivated (not deleted) so its historical events stay available via recent_alerts.' Also clarifies ownership enforcement. Annotations already indicate non-destructive and idempotent, so description complements well.

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 succinct sentences covering purpose, constraint, and side effect. No unnecessary words.

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

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

Given tool simplicity (1 param, no output schema), description covers behavior, ownership, and side effects. Sufficient for agent understanding.

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 description adds meaning by specifying that id is 'returned by subscribe', linking to the subscription creation tool.

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') and resource ('subscription by id'). It effectively distinguishes from the sibling 'subscribe' tool.

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

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

Provides explicit ownership constraint ('you can only cancel your own subscriptions'), giving clear usage context. Does not explicitly mention alternatives but the sibling tool list includes 'subscribe' as counterpart.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds critical behavioral context: the two-pipeline routing, the meaning of verdicts, and especially the caution that could_not_verify is not evidence. This is useful beyond the annotations and does not contradict them.

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

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

The description is longer than minimal but well-structured: it front-loads the purpose with examples, then explains routing, return values, and caller cautions. Every sentence contributes value; nothing is 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?

Despite lacking an output schema, the description enumerates the verdict values (confirmed, refuted, etc.), explains the error semantics for could_not_verify, and describes the fallback pipeline. This is comprehensive for a tool of this complexity and leaves no major 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?

Input schema has 100% coverage, so baseline is 3. The description adds meaningful nuance for tolerance_pct (overrides implied tolerance, default behavior) and gives concrete claim examples, helping the agent understand parameter semantics beyond the schema descriptions.

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

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

The description clearly identifies the tool as natural-language claim verification with concrete example phrasings ('Is it true that…', 'fact check'). It specifies the resource (authoritative sources) and distinguishes from sibling research tools by focusing on returning a definitive verdict rather than open-ended research.

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

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

Provides explicit usage context ('Use whenever the agent needs to check whether something a user said is factually correct') and explains the routing for two claim types (company-financial vs. other). It does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to decide.

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