Remotive

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

Annotations already mark readOnly/idempotent/non-destructive; description adds external API call behavior, default model (Workers AI Llama-3.3-70b), and BYO Anthropic key with direct billing. This meaningfully supplements the structured hints, though rate-limit or privacy details are absent.

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

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

Three sentences with high information density: purpose, default/cost behavior, output, and use cases. No filler or redundancy.

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

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

The description explains input (entity/models/key/context implicitly via schema), default behavior, return structure per model and combined view, and typical use cases. With no output schema, it carries return-value responsibility and meets it.

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

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

Schema covers all 4 params at 100%, so baseline is 3. Description enhances the schema by documenting the default model, that _apiKey is only needed when anthropic is in models, and that it's passed straight through; this justifies above baseline.

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

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

Description opens with 'Probe one or more LLMs...' and specifies scoring 0-100 per model, clearly distinguishing this from sibling research/search tools. It names the exact scope (business/brand/product/topic) and output shape, making the tool's function unambiguous.

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

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

Clearly lists use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring'), giving agents solid context on when to select it. It doesn't explicitly name alternatives or exclusions, so it stops short of full when-not guidance.

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

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

The annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, and the description does not contradict these. It adds behavioral context such as 'routes the question to the right one of 5,564 tools', 'returns the structured answer with stable pipeworx:// citation URIs', and 'works on every tier, one fast call', which are not available from annotations alone. This helps the agent understand the tool's internal routing behavior and output format.

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

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

The description is relatively long but well-structured with clear paragraphs. It packs useful guidance and examples without being redundant. It could be shorter by cutting some examples, but each sentence contributes to the decision-making process, earning a 4.

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

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

Despite no output schema, the description explains what the tool returns (structured answer with citations), how it selects tools, and when to use alternatives. It covers the key edge cases (grounded vs. broad research) and provides examples. Given the complexity of a meta-tool, this is quite complete, though it does not discuss error handling or rate limits.

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 with six parameters, all documented as aliases for 'question'. The description does not add new parameter-specific information beyond schema, but it provides natural-language examples of valid queries that help the agent formulate the question parameter. Since schema coverage is high, this is a 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: to answer factual questions about real-world data by routing to one of 5,564 tools across 1,462 sources, returning structured answers with citations. It differentiates from siblings by positioning itself as the default entry point, with explicit alternatives (ask_pipeworx_grounded, deep_research) for specific use cases.

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

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

The description explicitly says 'START HERE for most questions' and 'PREFER OVER WEB SEARCH', and provides specific alternatives: 'for a hallucination-resistant single answer with verbatim evidence + confidence use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research'. It also lists trigger examples and the types of questions it handles, making when-to-use unmistakable.

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

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

Annotations already cover readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is established. The description adds genuinely useful context beyond this: the beta nature with live candidate routing changes, the current matching of the stable router, and the explicit 'Falls back to nothing — this IS a full working router, just the experimental edge' clarification. This helps the agent understand variable behavior across calls. It doesn't contradict annotations.

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

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

Four sentences, front-loaded with the most critical facts (beta identity, tool count, current parity with stable). Each sentence earns its place: identity, current state, usage direction, and fallback clarification. It is slightly dense at ~120 words given this could have been said in two sentences, but the operational detail about candidate testing and merge comparisons 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?

Given the tool's complexity (a beta router over 5,564 tools with live-changing routing behavior and no output schema), the description covers the essential ground: identity, current operational state, usage, and the no-fallback guarantee. It deliberately defers response shape and argument details to ask_pipeworx ('same response shape', 'same arguments'), which is a reasonable reference for the agent to consult. It could state the response format directly, but the sibling reference is adequate.

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% — all six parameters (question plus five aliases: q, text, input, query, prompt) are already fully documented in the schema as natural-language questions. The description adds only the generic 'same arguments' pointer to ask_pipeworx, which provides no per-parameter enrichment. This meets the baseline of 3 for high-coverage schemas but adds nothing beyond it.

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

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

The description immediately identifies the tool as 'Beta version of ask_pipeworx: identical universal router (same 5,564 tools, same arguments, same response shape)', which clearly states what it does (a universal router that routes questions across 5,564 tools) and differentiates it from its stable sibling by framing it as the experimental edge. It further clarifies current state (no active candidate) and that it IS a full working router, which removes any ambiguity about it being a stub.

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

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

'Use it exactly like ask_pipeworx when you want the newest routing' explicitly states when to use this tool and names the alternative (the stable ask_pipeworx). It also contextualizes behavior ('results are compared against the stable router to decide what merges'). However, it stops short of explicit when-not-to-use guidance or mention of other siblings like ask_pipeworx_grounded, so a half-point deduction is warranted.

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?

Extremely transparent: describes routing, extraction using ONLY tool data, and the exact refusal reasons. Aligns with readOnlyHint (non-destructive), idempotentHint (reads only), and no contradiction.

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

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

The description is longer than typical but every sentence adds critical context: mode, behavior, refusal, usage, cost tradeoff. It's front-loaded with the key promise and structured effectively.

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 (routing, extraction, refusal modes), the description comprehensively covers behavior, output structure, use cases, and cost considerations. No output schema, but detailed return fields are described. Context is complete.

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

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

The description doesn't elaborate on each parameter, but schema covers all aliases thoroughly (100% coverage). Baseline 3 applies, and description adds minimal additional semantic value for the question parameter 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 the purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It further explains the core function and distinguishes it from the sibling tool ask_pipeworx, making the purpose unambiguous.

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

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

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on' and gives examples (financial verdicts, legal claims, etc.). Also advises preferring ask_pipeworx for casual lookups, providing clear 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds exceptional behavioral detail beyond these: low-confidence matches short-circuit with status:'low_confidence_match', closed markets return 'market_closed_or_inactive', wide spreads carry tradeability:'illiquid_wide_spread', and cancellation rules quantify void settlement risks. This is rich, non-contradictory disclosure.

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

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

The description is long but extremely well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.). Every block adds critical operational context, and the format helps an agent parse it quickly. It could potentially be trimmed, but the density is justified by the tool's complexity.

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

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

There is no output schema, so the description carries full responsibility for explaining return values. It thoroughly covers result.market, result.analysis, result.evidence, the resolver contract with confidence fields and suggestions, parent_event extraction, news fallback flags, and status codes for low confidence/closed markets. The cancellation-rule risk guidance is a notable completeness bonus.

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 providing concrete examples for the 'market' parameter (slug, URL, question text) and clarifying the fan-out behavior based on bet classification. It reinforces the 'include_raw' default behavior indirectly, but the schema already documents these parameters thoroughly.

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

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

The description opens with a specific verb+resource+scope: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes this tool from siblings like polymarket_edges and polymarket_arbitrage by focusing on per-bet research with data fan-out. The classification and fan-out details reinforce a precise purpose.

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

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

The description explicitly states intended use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This provides clear context for when to invoke the tool. It does not explicitly mention when not to use it or name alternative tools, but the context is strong enough to avoid duplication with 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?

Beyond the readOnly/openWorld/idempotent annotations, the description reveals concrete behaviors: data sources (SEC EDGAR/XBRL, FAERS), fiscal-year handling, sorting by primary metric, and citation URIs. 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?

Although long, every sentence adds operational value: trigger examples, data source details, sorting behavior, output format, and efficiency context. It is front-loaded with usage triggers and flows logically from purpose to specifics.

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

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

For a tool with no output schema, the description adequately describes returned data ('paired data + pipeworx:// citation URIs'), covers both entity types, and clarifies sorting behavior. Combined with rich annotations and schema, it is fully contextualized.

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

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

Despite 100% schema coverage, the description enriches parameter meaning by explaining the data pulled for each type (company vs drug) and giving concrete examples for values (['AAPL','MSFT'], ['ozempic','mounjaro']). It also notes off-calendar fiscal year handling, which is critical for correct invocation.

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

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

The description clearly defines the tool's function with specific verb ('compare') and resource ('2–5 companies or drugs') in one call. It explicitly distinguishes from sequential single-entity lookups, making it unmistakable when to invoke.

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

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

It provides explicit trigger phrases ('Compare X and Y', 'X vs Y', 'rank these companies') and instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities'. This gives clear when-to-use guidance and an implicit alternative.

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

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

The description discloses substantial behavior beyond annotations: parallel decomposition to 5,564 tools, returns findings packets with gaps[], never invents, depth-dependent behavior (quick/standard/thorough hop recovery), contractions[] for standard/thorough, semantic excerpting, expected latency ~15-90s, citation_uri always fetchable, account tier requirements. Annotations (readOnly, idempotent, non-destructive) are consistent and supplemented richly.

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 packs dense, relevant information. It is front-loaded with critical account requirement and immediate alternative. Every sentence adds value (behavior, use cases, exclusions, timing, citation guarantees). Slight redundancy in mentioning contradictions twice and depth details, but it earns its 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?

The description is comprehensive for a complex tool with no output schema. It explains return value shape (findings packet with verbatim evidence, confidence, source, fetched_at, gaps[], contradictions[], hop field, citation_uri), failure modes (empty gaps[] for uncatalogued topics), latency expectations, depth semantics, and account/auth requirements. It covers what the agent needs to select and invoke correctly.

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

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

Schema coverage is 100% for both params, so baseline is 3. Description adds significant extra semantics: depth levels are explained with detailed behavior (quick=3 facets, standard adds gap recovery + contradictions, thorough=6 facets + iterative hop), and question param is described as accepting broad/multi-part natural language because decomposition is the point. That elevates above baseline.

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

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

The description states a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources' in ONE call. It clearly distinguishes from siblings by noting 'this is NOT open-web search' and contrasting with ask_pipeworx for single lookups and current-news.

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 when-to-use and when-not-to-use: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. Also covers account requirements and fallback if not signed in.

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, so the description doesn't need to repeat safety. It adds valuable behavior details: returns top-N tools with names, descriptions, and full input schemas, and each result is ready to call directly without a second schema lookup. This goes beyond what annotations provide.

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

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

The description is three sentences long, each with a distinct purpose: define the action, enumerate the domains and output behavior, and specify usage context. It is front-loaded with the core purpose and contains no redundant or filler content.

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

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

Given the tool's complexity (6 params, many aliases, no output schema), the description fully covers the return value (names, descriptions, schemas, examples), usage context (call first when exploring), and scope (domain list). It is complete for an agent to decide whether to invoke this tool and what to expect.

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

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

Schema coverage is 100%, so all parameters are described in the schema. The description adds meaning by providing concrete example queries ('analyze housing market trends') and explaining the 'top-N' limit behavior. This enriches understanding of the 'query' and 'limit' parameters beyond their basic schema definitions.

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

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

The description opens with 'Find tools by describing the data or task,' which clearly identifies the action (find tools) and the input (description of data/task). It distinguishes from sibling tools like 'search' by focusing on tool discovery rather than data retrieval, and the extensive domain list (SEC filings, FDA drugs, etc.) clarifies the 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?

Explicit when-to-use guidance is provided: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set.' It also implies when not to use it ('not just one answer'), but does not name specific alternative tools.

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

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

Annotations declare readOnlyHint and idempotentHint, but the description adds significant context: it fans out across multiple sources, lists exact return fields, notes USPTO API sunset and soft-fail behavior, and specifies input constraints (ticker/CIK, not names). This goes beyond what annotations provide.

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

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

The description is long but information-dense. It starts with user query examples, explains behavior and return structure, and ends with input format. Each sentence adds value, though it could be slightly more compact. The structure is logical 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 no output schema, the description enumerates all returned components (cik, filings, fundamentals, patents, news, LEI) and also mentions failure modes (USPTO sunset) and fallbacks. It is remarkably complete for a complex tool.

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

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

Schema covers both parameters with descriptions. The description reinforces value semantics with examples ('AAPL' or '0000320193') and restates the restriction on names. While schema coverage is 100%, the added examples improve clarity, so above baseline.

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

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

The description clearly states the tool creates a 'full cross-source profile of a US public company' with specific examples of user queries. It distinguishes itself from siblings by explicitly preferring this over chaining individual lookups and referencing resolve_entity for name-only inputs.

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 'ALWAYS PREFER' guidance for holistic company research, and directs users to use resolve_entity if only a name is available. This clearly differentiates when to use entity_profile versus alternatives or pre-steps.

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

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

Annotations already provide destructiveHint=true, readOnlyHint=false, and idempotentHint=true. The description adds the 'clear sensitive data' context but no additional behavioral details such as permanence or side effects. It does not contradict annotations, but the bar is low due to annotation coverage.

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

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

Two sentences, front-loaded with purpose, and all content is relevant. 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?

For a simple single-parameter delete tool with annotations covering safety and schema covering parameters, the description provides complete context including purpose, usage, and related tools. No output schema is needed.

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

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

Schema description coverage is 100% with a clear description for 'key'. The description repeats 'by key' without adding extra semantic details like format, constraints, or examples beyond what the schema's example provides.

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

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

The description states 'Delete a previously stored memory by key', which is a specific verb+resource+scope. It clearly distinguishes from sibling tools like remember and recall by indicating deletion.

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

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

The description explicitly provides when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. It also suggests pairing with remember and recall, but does not provide explicit when-not-to-use or alternative tool names.

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 behavior. The description adds valuable behavioral context: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format,' plus output placement. No contradiction with annotations.

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

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

The description is three sentences, each earning its place: first sentence states purpose and outcome, second explains the process, third lists use cases. It is front-loaded with the action verb and remains entirely free of fluff.

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

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

Given the tool's simplicity (2 params, no output schema), the description is complete. It covers what the tool does, how it works, what the output looks like, and when to use it. No significant gaps remain.

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

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

Schema descriptions cover both parameters completely (100% coverage), including the default and max for max_links. The description adds no additional parameter-specific semantics beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Generate a production-ready llms.txt file for any URL.' It also details the process (fetches page, extracts info, emits markdown) and output, making it distinct from sibling tools like ai_visibility_check or scan_competitor_ai_presence.

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

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

The description provides clear use-case context via 'Useful for: getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' However, it does not explicitly state when not to use the tool or mention alternative tools, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false. The description adds only that it returns profile and active listings, which is data scope rather than behavioral traits. No rate limits, pagination, or other behavioral details are mentioned, but with strong annotations, the lack of contradiction and some added context is acceptable.

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, front-loaded sentence: 'Company profile + active listings by company slug.' It contains no superfluous words and is appropriately sized for the tool's simplicity.

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

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

With a single required parameter, an output schema, and rich annotations (read-only, idempotent, non-destructive), the description is sufficient. It clearly states what the tool returns, and the output schema covers return-value details. Nothing critical is missing for this low-complexity tool.

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

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

The schema already provides 100% coverage with the description 'Remotive company slug' for the required `slug` parameter. The tool description reinforces that the slug identifies the company and that output includes listings, but it does not add beyond the schema's semantic detail. Baseline of 3 is appropriate.

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

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

The description clearly states the tool returns a company profile and active listings for a given company slug. This specific verb-less phrasing is unambiguous and distinguishes it from siblings like entity_profile by describing the exact data scope.

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

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

The description implies use when you have a company slug and need profile plus listings, but it does not explicitly mention when to prefer this over alternatives like entity_profile or search. There are no usage exclusions or alternative comparisons.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds useful context by stating 'All' (complete result set) and naming the return fields ('slug and name'), which goes beyond the annotations and helps set expectations.

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

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

The description is a single, short, front-loaded sentence. Every word adds value: 'All' conveys scope, 'Remotive categories' identifies the resource, and 'with slug and name' specifies the output. No unnecessary information.

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

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

For a zero-parameter, read-only, list-all tool with a rich output schema and annotations, the description is complete. It accurately sets expectations for the result content without needing to cover pagination, auth, or 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?

The tool has zero parameters, so parameter semantics are not applicable. The description does not need to explain any inputs, and the baseline score of 4 is appropriate because there are no parameter gaps to compensate for.

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 returns all Remotive categories, specifying both the scope ('All') and the data fields ('slug and name'). It is unambiguous and distinct from sibling tools like list_subscriptions or search, as no other tool focuses on category listings.

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

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

Usage is implied rather than explicit: if you need all Remotive categories, this is the tool. There is no mention of alternatives or when not to use it, but given the simplicity and uniqueness of the tool, the implied usage 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, and non-destructive behavior. The description adds useful context by specifying the return fields (id, type, params, created_at, last_fired_at, fire_count) and the 'caller's active' scope, going beyond the annotation baseline.

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

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

The description is two sentences, front-loaded with the primary purpose, and includes only essential details: the action, return fields, and usage guidance. 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 covers the purpose, usage scenarios, and return format. With annotations covering safety and the schema covering the optional parameter, the description is complete for a simple read-only list tool. No output schema is present, but the return fields are enumerated.

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

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

The single parameter include_inactive is fully described in the schema (with default behavior), and schema coverage is 100%. The description does not add any parameter-specific details, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: 'List the caller's active subscriptions' and enumerates the exact fields returned. This distinguishes it from sibling tools like subscribe/unsubscribe and list_categories.

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 offers explicit use cases: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This gives clear context for when to use the tool, though it does not mention alternatives or explicit exclusions.

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

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

The description goes well beyond the annotations by disclosing the async token flow (filing returns a claim_token, which can be passed back later to read status/resolution), operational details (team reads digests daily), and constraints (rate-limited to 5 per identifier per day, free, doesn't count against quota). All annotations are false, so the description carries the full burden of transparency and does so thoroughly.

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 fairly long but well-structured, starting with the core purpose and then covering when, when-not, token behavior, and limits. Every sentence adds useful information; it is slightly verbose but not bloated. The front-loaded purpose sentence ensures the agent immediately knows what the tool does.

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

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

Despite having no output schema, the description fully explains what happens after filing (claim_token, status read), how to write good feedback (specific tool/error/data, maximum length), and what self-imposed limitations apply (rate limit). It leaves no meaningful gaps for an agent to misuse the tool.

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

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

Schema description coverage is 100%, and each parameter already has detailed descriptions (e.g., claim_token explains passing it 'with no other arguments'). The prose adds context about the token workflow, but it essentially repeats what the schema says. This meets the baseline for high schema coverage but adds little new per-parameter meaning.

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

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

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist' – a clear, specific action. It further clarifies scope by stating it is ONLY for tools served by this Pipeworx connection, which distinguishes it from the many research/subscription 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 explicitly enumerates when to use it: wrong/stale data (bug), missing tool (feature/data_gap), or praise. It also provides an exclusion and alternative ('if the tool came from a different MCP server... file it with that server instead') and gives clear guidance on what to include/exclude ('don't paste the end-user's prompt').

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive behavior, and the description adds valuable context beyond those: caching behavior (5min-1h), data provenance (CF analytics-engine), privacy (no PII), and the return shape (pack, tool, count). This is rich, useful behavioral disclosure with no contradiction.

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

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

The description is compact and front-loaded: the first sentence states the core purpose, followed by concrete outputs, then a tightly numbered 'Useful for' list. Every sentence contributes new information, and the final note on caching and privacy is efficient rather than verbose.

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

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

This is a simple read-only tool with one optional parameter; the schema fully documents the parameter and the description explains its semantic trade-offs. The output (top tools, top packs, total call volume, count) is described sufficiently, and no output schema is needed for this level of 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?

The single parameter `window` is fully described in the schema (enum + description), so the baseline is 3. The description adds extra meaning by explaining that shorter windows surface current hotness and longer windows show steady-state demand, which helps the agent choose the right value.

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

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

The description opens with a clear, specific statement of what the tool does: "What other AI agents are calling on Pipeworx right now." It then lists concrete outputs (top tools, top packs, total call volume) and explicitly distinguishes this as a self-aggregating, cross-agent signal, differentiating it from sibling tools like discover_tools or 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?

The description provides explicit use cases via a numbered 'Useful for' list, covering discovery, canonical-choice confirmation, and alignment checking. It also explains window semantics (shorter vs. longer windows), but does not explicitly state when not to use the tool or name alternative tools, so it stops short of a 5.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive. The description goes far beyond annotations by explaining the semantic anchor (Jaccard similarity threshold), partition placeholder filter, and the fill check caveat (realizable_edge_pp ≤ 0 means don't trade). This provides deep insight into the tool's behavior without contradicting annotations.

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

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

The description is long but efficiently structured with bolded sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and a clear mode-by-mode breakdown. Every sentence adds functional value, and the response format is specified upfront. It is dense but not wasteful.

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

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

The tool is complex with three modes, filters, and a fill-check subprocess. The description covers the output shape, edge cases, and actionable advice (e.g., 'do not trade it' when realizable_edge_pp ≤ 0). Even without an output schema, the description fully explains return values and failure conditions, making it complete for an agent to use correctly.

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

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

The schema already covers both parameters with helpful descriptions and examples. The description adds extra context by clarifying the recommended use case for event ('recommended for a specific market') and the cross-event purpose of topic, plus the implicit no-args mode. This goes beyond the schema but much of the parameter detail is already present, so a 4 is appropriate.

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

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

The description opens with a specific verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes the tool from siblings by focusing on arbitrage detection, not just edge tracking or fill risk, and explicitly references polymarket_fill_risk for sizing.

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

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

The description provides explicit usage modes: call with NO args for trending_scan, pass event for per-event scan, or pass topic for cross-event scan. It recommends event for specific markets, explains the difference between modes, and names an alternative tool (polymarket_fill_risk) for custom sizing. This is exemplary guidance for when and how 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?

The description goes far beyond the annotations by disclosing detailed behavioral traits: three response segments (by_segment), per-opportunity fields (edge_pp_net, kelly_fraction, market.liquidity, etc.), the 24h-move warning, per-sport alpha values, placeholder filters, and 1-hour caching keyed on all knobs. It also explains diagnostics for why segments might be empty, which is valuable operational detail.

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 unusually long, but it is well-organized and front-loaded with a clear purpose. Given the complexity (three model families, response structure, and parameter nuances) and the lack of an output schema, the detail is justified. It could be tightened in places (e.g., the per-sport α list), but the structure compensates for its length.

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

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

With no output schema, the description fully specifies the response contract: three segments, per-opportunity fields, top-level diagnostics, and the fed_candidates exclusion. It explains the logic behind each model family and how knobs affect the output, making it self-contained for an agent to invoke and interpret results correctly.

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

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

Although the schema already covers 100% of parameters, the description adds meaningful context: it explains the tradeable-edge knobs (min_liquidity, max_spread_pp) as filters for realizable edges, clarifies that min_kelly does not apply to partition arbs but min_partition_leg_kelly does, and provides rationale for slippage_pp defaults. This goes beyond the schema's basic descriptions.

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

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

The description opens with a specific verb-resource pair: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly distinguishes itself from sibling Polymarket tools by focusing on Pipeworx data vs market price and outlining three model families. This is a precise, non-tautological statement of purpose.

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

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

The description explicitly states its intended use: 'Built for "what should I bet on today"' and notes that agents can 'discover opportunities without paging hundreds of markets.' It also explains tradeable-edge knobs (min_liquidity, max_spread_pp) and the caveat about Fed candidates. However, it does not directly compare itself to sibling tools like polymarket_arbitrage or polymarket_edge_tracker, so the differentiation is implicit rather than 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?

Despite annotations already declaring read-only and idempotent behavior, the description goes far beyond them by detailing response structure (tracked[] with edge_pp_net time-series, trend, decay; expired[] with lifespan_days; snapshot_dates[]), explaining data gaps (snapshots written on cache-miss), and disclosing history limits (60-day TTL, start time). It also clarifies the signed nature of edge_pp_net, which is critical for interpretation.

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

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

The description is dense but structured into clear segments (purpose, args, response, limits). It is front-loaded with the main purpose, uses caps for key terms, and every sentence contributes meaningful information. The length is justified because there is no output schema, so the description must carry response formatting details.

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

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

Given the tool's complexity and absence of an output schema, the description provides comprehensive coverage: it details all response fields, explains data freshness and gaps, states historical depth limitations, clarifies calculation basis, and offers an actionable insight ('median lifespan is your competition clock'). It is difficult to identify any critical missing information.

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 both parameters (days: lookback, clamp 2-30; window: family with choices). The description adds extra context like 'max 30' and the default window, but this is mostly redundant with the schema. It does add the nuance that window refers to the 'snapshot family,' which slightly enriches meaning, but the schema already conveys the essence.

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

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

The description clearly defines the tool as 'Edge persistence and decay telemetry' built from daily polymarket_edges snapshots, and explicitly states the core question it answers ('how long has this edge existed and is it shrinking?'). It distinguishes itself from sibling tools like polymarket_edges by focusing on historical persistence versus current edge data.

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

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

The description provides a clear use case ('a fresh wide edge and a 3-week-old wide edge are different trades') and explains what the response tells the user (tracked, expired, snapshot_dates). It does not explicitly name alternative tools or say 'when not to use,' but the context is strong enough to guide selection. Limits are stated, aiding proper 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?

The description adds rich behavioral context beyond annotations: it explains the two modes (single-market vs basket), parameter interpretation (size_usd differs by mode), the order-book walk, return fields (verdict, slippage, thin_legs, etc.), and the specific risk of forced directional risk. No contradiction with readOnlyHint=true; this is a read-only analysis tool.

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

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

The description is long but every sentence carries information. It is structured with clear mode separation (SINGLE-MARKET vs BASKET), uses uppercase keywords for emphasis, and front-loads the core purpose. No fluff or repetition.

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

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

With no output schema, the description thoroughly enumerates all significant return fields and their meaning (top_of_book, vwap_fill_price, slippage_pp, capture_ratio, thin_legs, forced_directional_risk, etc.). It also covers edge cases like thin books and partial fills. The combination of purpose, usage, and return semantics makes it complete for this 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?

Even though schema coverage is 100%, the description adds meaningful semantics: it explains that market vs event are mutually exclusive modes, clarifies side options with defaults and auto-detection in basket mode, and interprets size_usd as 'max spend on buys, target proceeds on sells' in single-market mode and as settlement notional in basket mode. 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 a specific purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes itself from sibling tools by explicitly naming when to use it (before polymarket_arbitrage or polymarket_edges trades) and what differentiates 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?

Provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why, naming the risk of partial basket fills and unhedged directional positions. This clearly distinguishes from 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 goes far beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint). It discloses the compatibility_warning conditions, temporal alignment semantics, skipped_cross_type/subtype counters, and the exact meaning of spread values. It also warns that 'pre-mapped ≠ tradeable,' adding crucial behavioral context that annotations do not provide. No contradiction with annotations.

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

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

The description is long but dense with essential information. It is well-structured with clear labels for modes (TWO MODES), response fields, and safety fields. Capitalized field names and consistent terminology help an agent parse it. However, the extensive technical detail about skipped_cross_type and cum_ge vs cum_le makes it longer than necessary for a concise description, though each sentence does earn its place.

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

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

Given the tool's complexity (3 optional params, no output schema), the description fully compensates. It explains the return format (leg-by-leg prices, top_spreads_pp), the safety fields (compatibility_warning, temporal_alignment), and the skip counters. It also provides practical context about the rarity of real spreads and the difference between pre-mapped and tradeable. No output schema exists, so this description carries the full burden and succeeds.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds valuable semantics by explaining how the three parameters interact: topic triggers pre-mapped shortcuts, while kalshi_event_ticker and polymarket_event_slug override the mapped side for custom pairings. It also documents the allowed topic enum values in the schema, but the description enriches the meaning by explaining the mode structure and response semantics beyond the schema.

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

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

The description opens with a specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes this from sibling tools by focusing on the Kalshi–Polymarket comparison and the 'same resolving question' scoping, and further differentiates via the two modes and safety fields.

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

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

It provides clear guidance on when to use the tool: for cross-venue spreads, with two explicit modes (topic shortcuts vs explicit ticker/slug pairing) and explains the override relationship. It also warns that most pre-mapped topics return compatibility_warning, implying when not to expect tradeable spreads. However, it does not explicitly name alternative sibling tools like polymarket_arbitrage, so the when-not-to-use guidance is implicit rather than 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?

The description adds context beyond the annotations by explaining the key-based scoping ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the optional key behavior for listing all keys. Since annotations already declare readOnlyHint=true and idempotentHint=true, this additional disclosure of scope and dual-mode behavior is valuable.

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

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

The description is comprised of three focused sentences: core function, use case, and scoping/pairing. It front-loads the primary action and avoids redundancy with the schema, making it 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?

For a simple one-parameter tool with strong annotations, the description fully covers the behavior, scoping, and relationship to sibling tools. It explains both modes and gives a practical use case, so the 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?

The input schema already provides a full description of the 'key' parameter ('Memory key to retrieve (omit to list all keys)'), so the description's mention of omitting the key doesn't add much. The examples of potential keys (ticker, address, research notes) offer some flavor but don't fundamentally change parameter understanding. Baseline 3 is appropriate given 100% schema coverage.

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

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

The description uses the specific verb 'retrieve' with the resource 'a value previously saved via remember', and explicitly contrasts with the alternative behavior of listing keys when the key is omitted. It also distinguishes itself from siblings by naming 'remember' and 'forget' as complementary 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?

It states 'Use to look up context the agent stored earlier' which clarifies its primary use case, and 'without re-deriving it from scratch' reinforces the intent. It also explains the relationship with remember and forget for saving/deleting, but doesn't explicitly discuss alternatives like search or when-not-to-use scenarios.

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

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

Annotation Contradiction: annotations declare readOnlyHint=true, but the description states mark_read:true flags events as read, a state mutation. This contradicts the read-only hint, giving the agent conflicting signals about side effects.

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

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

Four dense sentences, no filler. Front-loads the primary purpose, then delivers high-value details (return payload contents, filtering, mark_read semantics, external endpoint) each pulling their weight.

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?

Description covers purpose, filters, mark_read side effect, return payload fields, and even an alternative access method. No output schema exists, but description compensates well. Minor gap: no error behavior or rate limits, but acceptable for a polling 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 already covers all 5 parameters with descriptions (100% coverage). Description adds value by giving a concrete type example ('sec_8k'), specifying ISO timestamp format for since, and explaining mark_read's effect beyond the schema's simple 'Flag returned events read'.

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

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

Description uses specific verb 'Pull' with clear resource ('fired events from your subscription feed') and explains exactly what is returned. Clearly distinguishes from siblings like recent_changes and list_subscriptions by detailing the feed context, filtering, and mark_read behavior.

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

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

Provides concrete usage guidance: filtering by type and since, using mark_read to advance the feed, and noting that polling works fine. Also points to an equivalent HTTP endpoint for scripts. Does not explicitly name alternative tools or when-not-to-use scenarios, but the context is sufficient.

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

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

The description goes well beyond the annotations by revealing the parallel fan-out to SEC, GDELT/GNews, and USPTO, including specific conditions like 'GNews when rate-limited or 5xx' and the PatentsView API sunset. It also specifies the return shape ('structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs'), which is not available in any structured schema.

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

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

The description is dense but every sentence adds value: example queries, source details, parameter formats, and the alternative tool. It front-loads the core purpose and organizes the information logically, avoiding fluff despite its 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?

Given the tool's complexity (multiple external sources, fallback logic, date parsing), the description covers all necessary aspects: inputs, behavior, output structure, and edge cases like the USPTO soft-fail. No output schema exists, so the description's explicit mention of `changes[]` and `total_changes` compensates fully.

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

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

Even though schema coverage is 100%, the description adds meaningful semantics: it explains accepted formats for `since` ('ISO date or relative shorthand') and `value` ('Ticker or zero-padded CIK'). It also clarifies that `type` only supports 'company', which is not obvious from the enum alone.

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

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

The description clearly identifies the tool as a change feed for a company over a time window, with explicit examples of user intent ('What's new with X'). It distinctly contrasts with the sibling tool entity_profile, saying 'Use entity_profile instead when you want the static profile', which differentiates it effectively.

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 through example queries and states when NOT to use it, naming the alternative (entity_profile). It also describes the fallback chain (GDELT→GNews) and the soft-fail for USPTO, helping the agent decide when the tool is appropriate.

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

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

Annotations already cover read-only/destructive/idempotent hints. The description adds meaningful context beyond those: memory is key-value scoped by identifier, authenticated sessions persist indefinitely, and anonymous sessions have a 24-hour retention window. This gives the agent a clear expectation of durability and scope without contradicting 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 five sentences, front-loaded with the primary purpose, then usage guidance, storage semantics, and companion tool references. Each sentence adds meaningful information without fluff. It is slightly longer than strictly necessary but every line earns its place.

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

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

For a simple two-parameter tool with no output schema, the description provides sufficient context: what to store, when to use it, how it behaves across sessions, and how to retrieve/delete. It doesn't explain overwrite behavior or success/failure responses, but those are not critical given the idempotent annotation and 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?

Input schema covers both parameters with descriptive examples and value semantics, so schema coverage is 100%. The description reinforces the key-value relationship and examples but doesn't add substantial new meaning beyond the schema. Baseline 3 is appropriate given the schema fully documents the parameters.

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

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

The description uses a specific verb ('Save data') and resource ('memory') and clearly distinguishes itself from siblings by explicitly mentioning 'recall' and 'forget' as companion tools. It also gives concrete examples of what to store (ticker, address, preference, subject), leaving no ambiguity about purpose.

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

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

Explicitly states when to use the tool ('when you discover something worth carrying forward') and provides the alternative tools ('Pair with recall to retrieve later, forget to delete'). It also clarifies the persistence difference for authenticated vs. anonymous sessions, which helps the agent decide whether to use this tool in the current 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?

Goes well beyond annotations (readOnlyHint, idempotentHint, destructiveHint) by explaining internal cascade, graceful degradation when GLEIF/OpenFIGI are unavailable, and that unresolved identifiers are explicitly stated. No contradiction with annotations.

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

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

The description is long but front-loaded with examples and usage cue. Every paragraph adds necessary detail for a complex multi-source lookup tool. Could be slightly tighter but remains 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?

Despite no output schema, the description comprehensively explains return values for both entity types, including sources, citation links, and behavior for unresolved identifiers. Covers edge cases like ISIN-to-LEI mapping and graceful degradation.

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 both parameters. The description adds substantial value by giving example inputs, explaining the resolution process for each type, and detailing what identifiers are returned.

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 resolves entity names to canonical identifiers, with specific examples of user queries like 'find the CIK for...' and distinguishes it from siblings by positioning it as the first step when a name is available. It covers two entity types with detailed resolution logic.

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 FIRST whenever you have a name but need an ID.' Provides guidance on when to choose company vs. drug type. It describes the tool as replacing 2-3 manual lookups, but does not explicitly contrast with sibling tools like 'get_company' or 'entity_profile.'

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

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

Annotations declare readOnly/OpenWorld/idempotent. The description adds behavioral detail: 'Probes each entity with ai_visibility_check, ranks by score, surfaces which is most/least recognized' and describes the return structure ('ranked list with score, confidence, signal density per entity'). 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?

Four sentences, front-loaded with the main action. Each sentence adds value: action, mechanism, use case, return format. No redundant filler.

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

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

Despite no output schema, the description specifies the return format ('ranked list with score, confidence, signal density per entity'). It covers the probe mechanism, ranking, and typical use. Schema covers parameter details. The description is sufficient for a tool of moderate complexity.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds critical semantic nuance beyond the schema: 'First entry treated as the 'subject' for narrative; rest are competitors.' This enriches the entity parameter meaning.

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

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

The description uses a specific verb 'Compare' and resource 'AI visibility across multiple entities side-by-side'. It distinguishes from siblings by explicitly referencing ai_visibility_check and ranking multiple entities, and gives a concrete use case (competitive AI-marketing audits).

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

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

Provides clear context: 'Compare AI visibility across multiple entities side-by-side' and 'Useful for competitive AI-marketing audits'. It implies this tool is for multi-entity comparison vs the single-entity ai_visibility_check, but does not explicitly name alternative tools or when not to use.

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

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

The description goes far beyond annotations by disclosing partial-failure behavior, performance expectations (bundlephobia's first measurement can take 5-30s), and the sources_failed field for timeouts. It also details the output structure including summary blocks, advisory details, links, and alternative versions. This adds rich operational context beyond the readOnly/idempotent hints.

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

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

The description is well-structured and efficient: first sentence states the composite purpose, second gives usage triggers, third lists return fields, fourth clarifies ecosystem scope, and fifth handles failure behavior. Every sentence delivers essential information without redundancy or fluff.

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

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

For a complex tool with two services, no output schema, and only basic annotations, the description is remarkably complete. It covers when to use it, what data it returns, its limitations (NPM-only), and failure modes. The agent has everything needed to decide when and how to invoke this tool correctly.

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

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

The input schema already fully documents both parameters (100% coverage), including scoped package acceptance and default version behavior. The description adds no new parameter-level information beyond what the schema descriptors provide, so it earns the baseline score but nothing more.

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

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

The description clearly states what the tool does: a composite npm package evaluation check across deps.dev and bundlephobia. It uses a specific verb ('scan') and resource ('npm package'), and distinguishes itself from any sibling tool by being the only one that aggregates licensing, security, and bundle-size data.

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

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

Excellent usage guidance: explicitly says to use it whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'. It also provides exclusion criteria by stating 'NPM ecosystem only in v1' and directs non-npm package queries to use deps.dev:version directly. This clearly differentiates from alternatives.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds contextual details such as 'curated remote-only' and specifies the return fields (title, company, location tags, salary range, job type, apply URL), which goes beyond the schema. No contradictions found.

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

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

The description is a single, concise sentence followed by a brief list of return fields. It is well-structured, front-loaded with the core purpose, and contains no redundant information.

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

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

Given the rich annotations, complete schema (100% coverage), presence of an output schema, and manageable complexity (4 optional params), the description fully satisfies the tool's contextual needs. It covers the purpose, query options, and expected output without over-explaining.

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

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

The input schema covers all four parameters with clear descriptions (e.g., 'Free-text — title / description', 'Category slug'). The tool description adds minimal additional meaning beyond the schema, so the baseline score of 3 for high schema coverage is appropriate.

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

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

The description clearly states the tool's function: searching Remotive's curated remote-only job board using free-text, category slug, or company name. It uses a specific verb ('Search') and a distinct resource ('Remotive's curated remote-only job board'), which differentiates it from sibling tools like list_categories or get_company.

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 (searching jobs by various criteria) and mentions the supported query types. However, it does not explicitly name alternatives or state when not to use this tool, such as contrasting with search_within or other similar siblings, so it falls short of a 5.

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

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

Beyond the readOnly/idempotent annotations, the description discloses technical behavior: BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, a 200K character cap with truncation flagging, and output containing character offsets and similarity scores. No contradiction with annotations.

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

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

The description is three focused sentences: purpose, use case, and mechanism. It is front-loaded with the core action, and every sentence provides distinct 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?

Despite having no output schema, the description explains the return format (passages with offsets and similarity scores), the truncation behavior, and the integration with ask_pipeworx_grounded. This is sufficient for an agent to correctly invoke and interpret the 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 already descriptive parameter definitions. The description adds extra meaning by explaining limit as 'top-N' and illustrating query forms with examples, but it doesn't significantly redefine each parameter beyond the schema's own 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 states a specific verb+resource: 'Semantic search INSIDE a fetched record.' It clearly distinguishes from siblings by emphasizing the input is pre-fetched text and positioning itself as a context-saving tool, even naming the complementary sibling 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?

Explicit usage guidance is provided: 'Use when the record is too big to cram into the prompt' and it explains a workflow pairing with ask_pipeworx_grounded. This tells the agent when to select this tool over alternatives like general search.

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 readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description builds on this with important behavioral details: OAuth requirement, always-on feed, webhook signing secret returned only once, auto-disable after 10 failed webhook runs, and a 10/day SMS cap. No contradiction with annotations.

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

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

The description is dense and informative, front-loaded with the purpose and return value. It is lengthy but every sentence adds operational detail; a slight reorganization into type and delivery sections would improve scannability, but it remains 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?

For a tool with nested objects and no output schema, the description is exceptionally complete: it covers supported types, per-type parameters, delivery channels, authentication prerequisites, rate limits, and webhook behavior. It even specifies the persistent feed retrieval URL.

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% parameter coverage with examples, and the description adds even more semantic value: concrete examples like 'sec_8k items:["5.02"] = officer change', 'polymarket_edge topic:"fed"', and detailed webhook signature verification steps. It goes well beyond the schema.

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

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

The description opens with a specific verb+resource: 'Create a proactive monitoring subscription to a live-data event stream' and states the return value (subscription id). It clearly distinguishes this from sibling tools like list_subscriptions, unsubscribe, and recent_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 provides rich when-to-use context: supported subscription types, delivery channels, and prerequisites (Pipeworx OAuth account, verified phone for SMS). However, it does not explicitly name alternative sibling tools or state when NOT to use this tool, so it falls just short of full guidance.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable context by explaining the return shape (category-bucketed example questions with exact tool + argument shape) and that it draws from the live catalog. No contradiction; it complements annotations without redundancy.

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 average but front-loaded with example phrases and ends with an explicit usage instruction. Every sentence contributes to onboarding clarity, and the length is justified for a tool designed to help new agents understand capabilities. Slightly verbose but not wasteful.

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

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

With no output schema, the description fully compensates by describing the return structure (category-bucketed example questions), the optional topic narrowing, and the intended first-use scenario. An agent has sufficient information to invoke the tool correctly and interpret its response.

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

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

Schema coverage is 100% for the single optional `topic` parameter, including the allowed focus areas and omission behavior. The description essentially restates the same examples ('finance', 'pharma', 'betting'), adding no new semantics 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 opens with concrete example queries ('What can I ask Pipeworx?') and explicitly identifies it as 'the onboarding entry point' for a newly connected agent. It clearly distinguishes itself from siblings like ask_pipeworx or discover_tools by framing itself as the first-stop discovery tool with a specific verb+resource ('suggest questions').

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

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

The description gives explicit guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you' and states it teaches how to call meta-tools. It provides clear context for when to use it, but does not explicitly name alternatives or when-not-to-use conditions, so it stops short of a 5.

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

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

Beyond the annotations (destructiveHint=false, idempotentHint=true), the description adds critical behavioral context: ownership is enforced, the row is deactivated rather than deleted, and historical events remain accessible via recent_alerts. This provides concrete insight into side effects and data persistence.

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

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

The description is two sentences, front-loaded with the primary action, and every clause adds value. It covers purpose, ownership, and data retention without padding or redundancy.

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

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

For a simple one-parameter tool, the description explains the operation, ownership restrictions, and data persistence, making it largely complete. It doesn't explicitly state the return value, but the absence of an output schema and the simplicity of the action make this a minor gap.

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

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

The schema already fully documents the single parameter (id, a uuid from subscribe), so description adds minimal new parameter-level meaning. The ownership enforcement implies constraints on valid id values, but this is contextual behavior rather than parameter syntax.

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

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

The description opens with a specific verb+resource ('Cancel a subscription by id'), making the tool's function immediately clear. It also distinguishes this from sibling tools like subscribe and list_subscriptions by emphasizing ownership enforcement and the deactivation behavior.

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

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

The description clearly indicates when to use the tool (to cancel a subscription by id) and prerequisites (own subscription, id from subscribe). However, it doesn't explicitly name alternative tools or state when not to use it, though the sibling context makes these obvious.

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

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

Explains critical behavioral nuances beyond the readOnly/idempotent/openWorld hints: the two pipeline paths (SEC EDGAR structured vs. grounded fallback), and the exact meaning of could_not_verify (not evidence, must not be shown) and unsupported. This prevents misinterpretation and goes well beyond annotation defaults.

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

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

Although the description is long (~260 words), it is dense and each sentence adds value: triggers, use case, routing logic, output contract, and failure semantics. It is front-loaded with user intents and ends with efficiency benefit; slight tightening could improve but it is well-structured for the complexity.

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

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

With no output schema, the description fully describes the return values: all six verdicts, the cited value, and reasoning. It also covers the two-tier routing, constraints, and the meaning of error states, giving an agent complete operational guidance.

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

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

Schema covers both parameters fully (100%), so baseline is 3. The description adds practical guidance on tolerance_pct, such as 'set 1–2 for hallucination detection' and explains the default cap of 5, enriching the schema's numeric constraint with usage intent.

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

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

The description clearly identifies the tool as a claim verifier, using explicit trigger phrases like 'fact check' and 'verify the claim that…', and specifies the output verdicts. It distinguishes itself from sibling tools by emphasizing the routing and replacement of 4–6 sequential calls.

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 when-to-use directive: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also details the behavior for company-financial versus other claims, providing clear context, though it does not explicitly name alternative tools or when-not-to-use cases.

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