swapi

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds genuinely useful behavioral context beyond those flags: the default model is free (Workers AI Llama-3.3-70b), probing Anthropic requires a BYO API key with direct payment, and the response shape is per-model {score, confidence, signals, raw_response} plus a combined view. It does not contradict annotations and gives important operational details.

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

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

Three sentences, front-loaded with the core purpose, then operational details, then use cases. Every sentence adds value and there is no wasteful repetition of schema or annotation content. The structure is easy to scan and information-dense.

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 quite complete: it covers what the tool does, the default behavior, auth requirements, return format, and typical use cases. There is no output schema, but the description adequately explains the response. It could mention limitations (e.g., rate limits, response size) or explicitly differentiate from the closest sibling, but overall it is sufficient for an agent to invoke correctly.

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

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

Schema coverage is 100% (all parameters have descriptions), so baseline is 3. The description adds extra meaning by explaining the interplay between the models and _apiKey parameters — e.g., the default free model, that passing _apiKey enables Anthropic, and that users pay Anthropic directly. This goes beyond the bare schema by clarifying why and when to use specific 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?

Description opens with a specific verb ('Probe') and clear resource ('one or more LLMs') plus a defined output (visibility score 0-100 per model). It explicitly lists the entity types (business/brand/product/topic) and even previews the return structure, making the tool's function unmistakable and distinct from sibling tools like ask_pipeworx or deep_research.

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

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

Provides clear, concrete use cases in the final sentence: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' This tells when to use the tool, but it does not explicitly mention when not to use it or compare it to alternative sibling tools like scan_competitor_ai_presence or compare_entities. Therefore it lacks explicit exclusions/alternatives, so it gets a 4.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: it routes to other tools, fills arguments, returns stable pipeworx:// citation URIs, and works on every tier with one fast call. No contradictions with annotations.

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

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

The description is long but information-dense. It front-loads the most important guidance ('PREFER OVER WEB SEARCH', 'START HERE') and then systematically covers alternatives, examples, and edge cases. Each sentence adds value, though some tightening could be done without losing substance.

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 meta-routing complexity, the description covers a wide range of use cases, alternatives, examples, and even mentions limitations (e.g., hallucination-resistance tradeoffs). It explains what the tool returns (structured answer with citations) without needing an output schema. The only minor gap is lack of explicit rate-limit or authentication info, but other factors make it sufficiently complete.

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

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

Schema description coverage is 100%, with the 'question' parameter fully described and six aliases documented. The description repeats some example queries also present in the schema, and adds no additional parameter-level detail beyond what the schema already provides. Baseline of 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states it routes questions to 5,529 tools across verified sources and returns structured answers with citation URIs. It distinguishes itself from siblings by naming ask_pipeworx_grounded and deep_research as alternatives with different strengths, and it explicitly says 'START HERE for most 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 when-to-use guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and 'Step up only when needed' for grounded or deep_research. It provides many concrete example queries and even covers breaking-news use cases, making the decision criteria very clear.

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

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

Beyond the annotations (readOnly, idempotent, openWorld), the description adds crucial behavioral context: it is an experimental edge with candidate routing improvements enabled live only when under test, currently matches the stable router exactly, and is a fully working router with no fallback. This informs the agent of the experimental nature, current state, and lack of safety net, which annotations alone do not convey.

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 and front-loads the key fact that this is a beta, then covers current state, usage, and reassurance that it is fully functional. It is compact and every sentence earns its place, though phrases like 'Falls back to nothing' add a conversational tone that is slightly less formal than necessary.

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

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

For a complex universal router with no output schema, the description is remarkably complete: it explains current behavior (exact match to ask_pipeworx when no candidate is active), usage context, and that the response shape matches the stable version. This is sufficient for an agent to decide when and how to invoke the tool correctly.

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

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

The input schema provides 100% coverage of all 6 parameters, each described as an alias for the single question field. The description does not elaborate on parameters beyond saying the arguments are identical to ask_pipeworx, so it adds no additional semantic value beyond the schema. Baseline 3 is appropriate given high schema coverage.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx with the same universal routing function, explicitly noting the same 5,529 tools, arguments, and response shape. It distinguishes it from the stable sibling by its experimental routing status, making it unambiguous what the tool does and how it differs from alternatives.

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

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

The description explicitly states to use it exactly like ask_pipeworx when wanting the newest routing and notes results are compared against the stable router. This provides direct when-to-use guidance and implicitly identifies ask_pipeworx as the stable alternative, covering both usage context and exclusion criteria.

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

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

Annotations already declare readOnly/openWorld/idempotent hints, but the description adds significant behavioral detail: the refusal mechanism with specific refusal_reason enum values, the guarantee to use only tool results, and the extra LLM call cost. This goes well beyond the structured data.

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

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

The description is dense but every sentence earns its place: mechanism, return contract, use cases, and cost comparison. It front-loads the core purpose and remains well-structured without unnecessary fluff.

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

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

Despite having no output schema, the description fully specifies the success response shape (answer, evidence, confidence, source, etc.) and all refusal reasons. It also discloses the scale of routing (5,529 tools across 1455 sources), making it 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 coverage is 100% with all six aliases documented, so the description doesn't need to add per-parameter details. The baseline 3 applies; the description only clarifies that the question is natural language, which is already in the schema.

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

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

The description clearly identifies a hallucination-resistant answer mode for high-stakes reads, explaining that it routes through ask_pipeworx and extracts answers strictly from tool results. This distinguishes it from siblings like ask_pipeworx and ask_pipeworx_beta by emphasizing the grounded, evidence-based output.

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: when answers will be quoted, cited, or acted on, and the agent must not invent facts. Also names the alternative (ask_pipeworx) for casual lookups, with the cost tradeoff of one extra LLM call.

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

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

The description goes far beyond the annotations by detailing resolver confidence contracts (market_match_confidence, suggestions), blocking statuses (low_confidence_match, market_closed_or_inactive), fan-out execution, news fallback behavior (_fallback_attempted), and even cancellation-rule risk (refund_50_50). The annotations already declare read-only/idempotent/open-world, and the description aligns without contradiction.

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

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

The description is long but densely structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY) and no filler. It is front-loaded with purpose and usage, and every later section adds meaningful behavioral detail, though its length prevents a perfect conciseness score.

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 result.market, result.analysis, result.evidence, parent_event structure, news fallback fields, and blocking statuses. It covers safety short-circuits and cancellation-rule risks, leaving virtually no ambiguity about the tool's behavior across varied inputs.

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 detailed descriptions for market, depth, and include_raw. The description adds input-format examples (slug, URL, question text) and fan-out illustrations, but these largely reinforce the schema's examples rather than adding new parameter semantics. Therefore, baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: "Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call." It clearly distinguishes itself from sibling Polymarket tools (e.g., polymarket_edges, arbitrage) by focusing on evidence gathering and model comparison for a single market, and it lists concrete use cases like "should I bet on X."

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

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

The description explicitly states when to use the tool: "Use for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'." It does not, however, provide explicit when-not-to-use guidance or name alternative sibling tools, so it stops short of the highest bar.

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

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

Annotations already cover readOnly/idempotent/destructive safety. The description adds rich behavioral context: data sources (SEC EDGAR/XBRL, FAERS, FDA), correct handling of off-calendar fiscal years, sorting by primary metric, and the return format with pipeworx:// citation URIs per entity.

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 yet well-organized. It opens with query triggers, then explains the core parallel-call nature, then type-specific details, sorting, and output. Every sentence earns its place, with 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 having no output schema, the description covers purpose, usage guidance, data sourcing, sorting behavior, and return format. For a comparison tool with two modes, it leaves no significant gaps for correct selection and invocation.

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

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

The schema already covers parameter descriptions at 100%. The description adds type-specific behavior ('type=company pulls...' vs 'type=drug pulls...') and clarifies values format, going beyond schema. However, the schema already documents the ticker/name examples, so the added semantic value is useful but not transformative.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs in a single parallel call. It includes concrete query examples and explicitly distinguishes itself from sequential single-entity lookups, saying 'ALWAYS PREFER over sequential single-pack lookups when comparing entities'.

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

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

Provides explicit when-to-use guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities'. It also gives example trigger phrases and notes it 'Replaces 8–15 sequential lookups', making the intended usage context 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?

Beyond the annotations (readOnlyHint=true, idempotentHint=true), the description adds substantial behavioral context: account and paid-plan requirements, latency expectations (15-60s, up to ~90s), the return packet structure (verbatim evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[], contradictions[]), and the guarantee that it never invents answers. It also explains hop-level details and when citation_uri is guaranteed to be resolvable. 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 information-rich; every sentence earns its place (auth, use cases, return format, limitations, latency). It is appropriately sized for a tool with this complexity, but it is a single wall of text without paragraph breaks, and depth-tier details are slightly redundant with the schema. Minor structural improvement could make it easier to scan.

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

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

With no output schema, the description fully explains the return packet (evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], hop field, citation_uri) and covers auth requirements, alternative routing, latency, and edge cases (e.g., empty gaps for news topics). For a complex tool, this is a remarkably complete spec: an agent can understand what to expect, when to invoke it, and what the output will contain.

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

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

Schema coverage is 100%, so the schema already documents both parameters and the depth enum. The description adds meaningful nuance beyond the schema: 'thorough' requires a paid plan, depth levels are tied to operational behavior (gap recovery vs. chasing leads), and questions can be broad/multi-part. This operational context helps invoking agents choose appropriate depth, though it partly repeats schema enum explanations.

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 combo: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources... in ONE call' and explicitly contrasts with open-web search ('this is NOT open-web search'). It clearly distinguishes from sibling ask_pipeworx by positioning itself for broad/multi-part questions over structured data, making the purpose unmistakable.

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

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

The description provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data', plus alternatives for single lookups ('For a single lookup use ask_pipeworx') and for breaking/news topics ('prefer ask_pipeworx... deep_research returns mostly empty gaps[]'). It even covers the auth fallback: 'If you are not signed in, use ask_pipeworx instead' — a rare level of specificity.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it explains the return format ('top-N most relevant tools with names, descriptions, and full input schemas'), notes that results are 'ready to call directly,' and clarifies there is no need for a second schema lookup.

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

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

The description is four sentences and front-loaded with the core purpose. The domain list is somewhat long but directly informs the user of coverage, and every sentence contributes either usage context, output details, or strategic guidance. No sentences are wasted, though it could be tightened.

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

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

There is no output schema, so the description correctly takes on the burden of explaining return values: it specifies that the result includes names, descriptions, and full input schemas, and that it is immediately callable. The description also covers the broad domain space and usage strategy, making it complete for a discovery tool.

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

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

Schema coverage is 100%, so the schema fully describes all parameters and aliases. The description adds little beyond saying the query is a 'natural language description' and that the tool returns 'top-N' results, which aligns with the limit parameter but does not introduce new semantic detail.

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 begins with 'Find tools by describing the data or task,' using a specific verb and resource. It clearly distinguishes itself from sibling tools by positioning itself as a tool-discovery meta-tool, and it lists numerous domains and explains the output format, leaving no ambiguity about its function.

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

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

The description explicitly states when to use it: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' It also implies a when-not ('not just one answer'), though it does not name specific alternative tools, so it falls short of a 5.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds meaningful behavioral context: fans out across multiple sources, performs parallel calls, returns specific fields, notes the USPTO patents API sunset and soft-fail behavior, and describes GDELT→GNews fallback. This goes well beyond the structured annotations.

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

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

The description is longer than the ideal two-sentence example but is well-structured and packed with necessary details. Trigger phrases are front-loaded, and the return fields are clearly listed using semicolons. Every sentence carries useful information, though it could be tightened.

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

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

For a complex aggregation tool with no output schema, the description fully covers return values (CIK, recent_filings with URIs, fundamentals with sorting, patents, news, LEI). It also documents fallback behavior and limitations (names not supported, patents API sunset). This is complete enough for an agent to invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description repeats the schema's parameter guidance (ticker or zero-padded CIK, names not supported) and adds examples ('AAPL', '0000320193') but does not add meaning beyond what the input schema already contains. It is functionally redundant.

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

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

The description clearly states 'full cross-source profile of a US public company in ONE parallel call' with a specific verb (profile) and resource (US public company). It enumerates the output components (CIK, filings, fundamentals, patents, news, LEI) and explicitly distinguishes itself from sibling tools by advising preference over chaining single-pack SEC/XBRL/news lookups.

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

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

Provides explicit when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also states a clear alternative for name-only inputs: 'use resolve_entity first if you only have a name.' This is strong usage direction beyond what the schema/annotations provide.

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 destructiveHint=true and idempotentHint=true, covering the safety profile. The description's 'Delete' aligns with these annotations but adds no extra behavioral details such as irreversibility or handling of missing keys. It provides minimal added value beyond the annotations.

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

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

The description is two concise sentences that front-load the purpose and then provide usage context. No filler or redundancy.

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

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

For a simple single-parameter destructive tool with no output schema, the description is complete: it states what it does, when to use it, and how it relates to remember and recall. The annotations cover idempotency and destructiveness, so nothing critical is missing.

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

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

The schema provides full coverage of the single 'key' parameter with description 'Memory key to delete.' The description's 'by key' simply reiterates the schema. No additional semantics like case-sensitivity or format are provided, so baseline 3 applies.

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

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

The description clearly states 'Delete a previously stored memory by key.' This provides a specific verb (delete), resource (memory), and mechanism (by key). It distinguishes from siblings like remember and recall by explicitly mentioning them, making its role unambiguous.

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

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

The description offers explicit scenarios for when to use: 'when context is stale, the task is done, or you want to clear sensitive data.' It does not explicitly state when not to use or name alternative tools for retrieval, so it stops short of a 5, but the guidance is strong.

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

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

The annotations already declare readOnlyHint and idempotentHint, but the description adds valuable behavioral context: it explains the process (fetch, extract title/description/links) and the output format (single text blob ready for site-root). This goes beyond the annotations without contradicting them.

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

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

The description is front-loaded with the core purpose, followed by process and output details. The 'Useful for' list extends length but is structured and earns its place by aiding usage guidance. No fluff, though it could be tightened by one less example without loss.

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 two parameters and no output schema, the description covers the input, process, output format, and use cases. It is complete enough for an agent to select and invoke the tool correctly. Minor omissions like error handling or edge cases are not critical for this simple fetch-and-generate operation.

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

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

The schema description coverage is 100%, so the parameters url and max_links are fully explained in the input schema. The description does not add significant additional meaning about the parameters themselves, but it does imply the url is the primary input. Baseline 3 is appropriate given the high schema coverage.

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

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

The description uses a specific verb ('generate') and resource ('llms.txt file') and clearly explains what it does: fetches a URL, extracts metadata, and outputs standard llms.txt format. Sibling tools like 'recall' or 'entity_profile' serve distinct purposes, making this tool's purpose unmistakable.

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

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

The 'Useful for' section provides concrete scenarios (client indexing, personal project drafting, competitor auditing), which clearly implies when to use the tool. It does not explicitly state alternatives or exclusions, but the sibling list contains no competing tool for this task, so the guidance 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 readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds value by listing the exact return fields (title, episode number, director, producer, release date, opening crawl), giving the agent a concrete expectation of the response. 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?

A single, well-structured sentence that front-loads the action and resource, then lists return fields. Every word earns its place with no redundancy or filler.

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

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

For a simple one-parameter read-only tool with full schema coverage, an output schema present, and annotations providing safety hints, the description is complete. It even enumerates return fields, so the agent knows exactly what to expect without any ambiguity.

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

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

The schema already provides full coverage for the single 'id' parameter, including a description and example ('1 for A New Hope'). The description merely echoes 'numeric ID' without adding substantial new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool gets a Star Wars film by numeric ID, specifying both the verb and resource. It distinguishes itself from sibling tools like get_planet and get_starship by naming the exact resource and the fields returned.

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

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

The description provides clear context for when to use the tool: when you have a numeric film ID and need specific film details. It doesn't explicitly discuss alternatives or exclusions, but the resource-specific wording makes the intended use obvious within the sibling family.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering safety and idempotency. The description adds that it returns name, climate, terrain, population, and orbital data, but these are also captured in the output schema. No additional behavioral traits such as error handling or rate limits are disclosed.

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

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

The description is a single, front-loaded sentence that gets straight to the point. It contains no redundant information and is easy to parse.

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

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

For a simple read tool with one parameter, full schema coverage, an output schema, and strong annotations, the description is complete enough. It provides the essential purpose and input requirement, with no significant gaps.

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

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

Schema coverage is 100% with a clear description and example for the id parameter. The description merely repeats that the ID is numeric, adding no significant meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description uses a specific verb 'Get' and clearly identifies the resource as a Star Wars planet, distinguishing it from sibling tools like get_film and get_starship. It also lists the returned data fields, making the tool's purpose unmistakable.

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

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

The description clearly implies the tool is for retrieving a planet by its numeric ID, which is the only parameter. However, it does not explicitly mention when to avoid this tool or recommend alternatives (e.g., searching by name). The context is clear enough for selection without 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 annotations already declare the tool as read-only, idempotent, and non-destructive, so the description doesn't need to repeat that. It adds the list of returned fields, but with an output schema known to exist, this is not a significant behavioral disclosure. No additional traits like error handling or data sourcing are mentioned.

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 short sentences with no redundancy. The first sentence states the core purpose, and the second concisely notes the returned fields, making it appropriately sized and easy to scan.

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

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

Given the tool's simplicity (one parameter, rich annotations, and an output schema), the description covers everything needed for basic selection. It explains what resource is accessed and what data is returned, with no missing critical context for a read-only lookup.

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 'id' parameter, including type (number) and an example (9 for Death Star). The description's 'numeric ID' adds no new meaning beyond the schema, so it meets the baseline for high schema coverage.

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

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

The description uses a specific verb ('Get') and resource ('Star Wars starship') and clarifies the lookup key ('numeric ID'). It clearly distinguishes itself from sibling get_film and get_planet tools, which target different resources.

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

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

The description implies usage when you have a numeric starship ID, but it does not explicitly state when to use this tool over alternatives like get_film or get_planet. No exclusions or alternative tool references are provided.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safe-read nature is covered. The description adds value by specifying return fields and the default behavior of excluding cancelled subscriptions, exceeding what annotations alone 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?

Two sentences, front-loaded with the core action, and no wasted words. The second sentence delivers return field details and usage guidance efficiently.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description fully covers purpose, return values, and use cases. It is complete enough for an agent to invoke correctly.

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

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

The schema description for include_inactive is fully descriptive ('Include cancelled subscriptions in the response (default false)'), with 100% coverage. The tool description adds no additional parameter semantics, so the baseline 3 applies.

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

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

Description clearly states the verb 'List' and the resource 'caller's active subscriptions', and it lists the return fields. This unambiguously distinguishes it from sibling tools like subscribe and unsubscribe.

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

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

Explicit usage context is provided: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' While it doesn't mention alternatives, the use case is clearly scoped and actionable.

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

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

Annotations are all false and provide little signal, but the description compensates richly by disclosing rate limits (5 per identifier per day), the fact that it is free and doesn't count against quota, the daily digest process, and the claim_token mechanism. It also clarifies that no account is needed to file. This goes well beyond the structured annotations.

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

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

Although the description is longer than average, every sentence adds distinct value: purpose, use cases, exclusion, token mechanics, rate limits, and roadmap impact. It is front-loaded with the primary purpose and organized logically, earning 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 has 4 parameters, a nested context object, no output schema, and zero required parameters, the description fully covers when to use, what to report, how to structure feedback, how to use claim_token, rate limits, and which issues are out of scope. The agent can correctly invoke this tool without further clarification.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds extra value by specifying typical message length (1-2 sentences) and elaborating on the claim_token's purpose (read status/resolution later with no other arguments). It also clarifies the intended semantics of type through the use-case framing.

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 ('Tell the Pipeworx team something is broken, missing, or needs to exist') and clearly identifies the resource as feedback for the Pipeworx team. It is immediately distinguishable from sibling research and query tools like ask_pipeworx or deep_research.

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

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

Provides explicit when-to-use guidance by enumerating bug, feature/data_gap, and praise categories. It also gives a clear exclusion: do NOT use for tools from other MCP servers, and directs the agent to file with that server instead. Includes concrete advice on how to use claim_token for follow-up.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds useful behavioral context beyond annotations: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' This explains data provenance, caching, and privacy, which is meaningful and non-contradictory.

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 front-loaded with the main statement. It includes a concise bullet list of use cases and a final sentence on data provenance. It is a bit longer than minimal but every sentence adds value, so it earns 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?

No output schema exists, but the description adequately explains return values: 'top tools, top packs, and total call volume.' It also covers data source, caching behavior, and use cases. For a single-parameter read-only tool, this is complete and leaves no major gaps.

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

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

Schema coverage is 100%, with the 'window' parameter already well-described in the schema ('24h (default) | 7d | 30d...'). The description repeats the enum values but does not add meaningful new semantics beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states what the tool does: 'Returns the top tools, top packs, and total call volume over a recent window.' It uses a specific verb ('Returns') and names the resource ('top tools, top packs, call volume on Pipeworx'). It also distinguishes from siblings like 'discover_tools' by emphasizing it's a self-aggregating signal of what other AI agents are calling.

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

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

The description provides explicit use cases: 'Useful for: (1) discovering what data sources are hot... (2) confirming a popular tool is the canonical choice... (3) seeing whether your use case aligns...' This gives clear when-to-use guidance. It does not explicitly mention alternatives or when not to use, but the context is strong.

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

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

The description goes far beyond annotations by disclosing internal logic: Jaccard similarity threshold of 0.30, partition placeholder filter (>20% returns null), and the fill check against live CLOB depth. It also defines output fields. No contradiction with readOnlyHint.

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

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

The description is front-loaded with a clear purpose and uses labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) for skimmability. Every sentence adds operational value, with no fluff, though it is long — length is justified by tool 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?

The tool has no output schema, so the description compensates by precisely specifying the response structure (opportunities[] fields, partition_check object). It covers both modes, edge cases (null arb signal, thin legs), and the fill-check workflow, making it complete for a complex tool.

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

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

Both params are documented in the schema, but the description adds significant meaning: the 'NO args' default mode, the semantics of event vs topic, examples of each, and how results differ per mode. This far exceeds the baseline.

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

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

The description opens with a specific verb+object+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes three modes (trending_scan, event, topic) and differentiates from sibling polymarket_fill_risk by pointing to it for custom sizing.

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

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

It explicitly tells when to call with no args, when to use `event` (recommended for a specific market) vs `topic` (for cross-event scanning). It also states exclusions: 'do not trade it' when realizable edge is ≤0, and points to polymarket_fill_risk for custom sizing.

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

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

Annotations already mark the tool read-only, idempotent, and non-destructive. The description adds substantial behavioral context: caching behavior ('Cached 1h at the KV level keyed on all knobs'), response diagnostics, the 24h-move warning, Kelly capping, placeholder-slug filters, and the Fed signal unreliability note. 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 well-organized with clear section breaks and front-loaded purpose. Every sentence provides useful detail for an agent deciding whether and how to call the tool, though the sheer volume of model-family specifics makes it denser than strictly necessary.

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

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

With no output schema and 9 parameters, the description goes beyond minimum requirements by detailing the full response structure (by_segment, fed_candidates, _diagnostics), explaining why segments may be empty, and describing how filters affect results. This is comprehensive for a complex tool and leaves little ambiguity about expected return behavior.

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

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

The input schema already provides 100% parameter descriptions, so the baseline is 3. The description adds extra meaning by grouping parameters into 'TRADEABLE-EDGE KNOBS' and explaining how min_partition_leg_kelly interacts with partition-level Kelly behavior, which goes beyond the schema's individual field 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 and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly distinguishes it from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by framing it as a discovery tool for daily betting decisions.

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 intended use case is explicit: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also explains when knobs should be adjusted (e.g., min_liquidity, max_spread_pp) and notes the Fed signal caveat. However, it does not explicitly name alternatives or state when not to use this tool versus 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?

The description goes well beyond the annotations' read-only/idempotent hints, disclosing critical data caveats: snapshot_dates reveal gaps when nobody scanned, history depth is bounded by a 60-day TTL, decay numbers come from daily closes not intraday, and negative values indicate SELL YES. This transparency about data limitations significantly aids an agent in interpreting results correctly.

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

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

The description is structured into clear segments: purpose, args, response, and limits, with all information serving a specific purpose. It is slightly longer than absolutely necessary but front-loads the core question and maintains readability with paragraph breaks.

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 explains the response structure, including tracked[], expired[], and snapshot_dates[], along with field meanings and interpretation. It also covers historical depth limits and data-generation behavior, making it fully self-contained for an agent using this tool.

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

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

Schema coverage is 100%, so the schema already fully documents both parameters. The description adds the clarifying label 'snapshot family' for window and uses 'lookback' for days, but most parameter semantics (defaults, clamps, enum values) are already in the schema. The added context is minimal but helpful.

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 as 'edge persistence and decay telemetry built from daily polymarket_edges snapshots' and specifies 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 rather than current snapshots, making it a unique resource.

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

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

The description provides strong contextual guidance, explaining that the tool serves to differentiate fresh from old edges and warning that a 3-week-old wide edge 'is wide for a reason nobody is willing to take.' However, it doesn't explicitly name alternatives or state when not to use it, so the usage guideline 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?

Annotations declare readOnlyHint, openWorldHint, and idempotentHint, and the description does not contradict these. It adds meaningful behavioral context: it 'walks the ladder', returns verdicts like clean|degraded|cannot_fill, and exposes failure modes like thin_legs and forced_directional_risk. The caution that 'theoretical overround on thin books is not capturable' and that partial basket fills convert an arb into an unhedged directional position provides significant insight beyond the annotations.

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

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

The description is long but justifiably so given two distinct modes and many return fields. It is well-structured with clearly demarcated sections (REQUIRES, SINGLE-MARKET, BASKET, USE THIS) that aid scannability. Every sentence provides necessary information—there is no filler 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 takes full responsibility for explaining return values. It enumerates all key outputs for both modes (top_of_book, vwap_fill_price, slippage_pp, capture_ratio, profit_usd, thin_legs, max_clean_notional_usd, etc.). It also covers edge cases like forced_directional_risk and explicitly warns about the danger of partial basket fills, making the tool's behavior fully comprehensible.

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 elevates this by explaining size_usd differently for single-market ('max spend on buys, target proceeds on sells') and basket modes ('settlement notional S, shares per leg, each share pays $1'). It also clarifies the default behavior for side in basket mode ('auto — sell if partition sum > 1, buy if < 1'), which adds semantic richness 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 opens with a precise definition: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly separates single-market and basket modes, and the specific mention of return values like slippage_pp and capture_ratio leaves no ambiguity about its function. It also differentiates itself from siblings by explicitly positioning itself as a pre-trade risk check for polymarket_arbitrage and polymarket_edges.

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

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

The description gives explicit usage direction: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' This directly names alternative sibling tools and states a threshold, making it clear when this tool is required and when it is likely unnecessary. The warning about partial fills becoming unhedged positions also reinforces the practical context.

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

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

Annotations already declare read-only/idempotent behavior, and the description adds substantial detail: compatibility_warning conditions, temporal_alignment interpretation, and skipped_cross_type/subtype counter semantics. It even explains what matched_pairs:0 with skipped_cross_type>0 means versus the semantically-unrelated case, offering rich behavioral context beyond the annotations.

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

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

The description is lengthy but well-structured with uppercase labels like 'TWO MODES', 'RESPONSE', and 'SAFETY FIELDS', and it front-loads the core purpose. Some repetition occurs (e.g., 'pre-mapped ≠ tradeable' stated twice), but each section carries critical caveats necessary for correct use of a complex tool.

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

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

There is no output schema, yet the description fully describes the return shape: leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, and skipped counters. For a two-venue comparison tool with many edge cases, this level of detail is sufficient for an agent to interpret results and understand limitations.

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 coverage is 100% with descriptions for all three parameters, so the baseline is 3. The description adds semantics by explaining that 'topic' auto-fetches the matching event and that explicit tickers/slugs override the mapped side, plus clarifies what the response will contain. This goes beyond the schema's basic field 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 begins with a specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes this tool from siblings like polymarket_arbitrage by focusing on same-event cross-venue comparison and explicitly enumerates two modes of operation.

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 describes TWO MODES and when each is appropriate: pre-mapped macro shortcuts vs explicit kalshi_event_ticker + polymarket_event_slug. It also warns that 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable,' giving practical guidance for when results may not be trustworthy. It does not directly name alternatives among siblings, but provides clear context for usage.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds meaningful scoping behavior ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') that is not present in annotations. No contradiction.

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

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

Three sentences, each with a distinct purpose: retrieval action, usage rationale, and scoping/pairing. Front-loaded with the main verb and no redundant text.

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

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

For a tool with one optional parameter, rich annotations, and no output schema, the description is complete. It covers operation, usage, scoping, and sibling relationships, leaving no missing context.

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

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

Schema covers the single 'key' parameter at 100%, but the description adds extra meaning: the 'omit the key argument' behavior for listing all keys, plus concrete examples of what keys represent (user's ticker, address, research notes). This goes beyond the schema.

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

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

The description opens with a specific action ('Retrieve a value previously saved via remember') and clearly distinguishes between retrieving a value and listing all keys. It explicitly names sibling tools (remember, forget), removing any ambiguity about its role.

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

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

Provides clear usage context: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also explains the relationship with remember and forget, which is explicit when-to-use guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral details beyond these: it explains that each event carries source and citation_uri, that mark_read:true modifies read state so future calls only show newer events, and that polling is safe. It fully discloses the side-effect of mark_read despite the readOnlyHint, avoiding any contradiction.

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

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

The description is three sentences and front-loaded with the main action ('Pull fired events'). Every sentence adds value: return fields, filtering options, mark_read semantics, and polling/alternative endpoint. There is no verbosity or redundancy, making it easy for an agent to parse quickly.

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

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

For a tool with 5 optional parameters, no output schema, and good annotations, the description is quite complete. It explains the return payload (source, citation_uri, raw event), filtering criteria, state-changing option, and even provides a fallback URL. This covers the essential context an agent needs to invoke the tool correctly without needing to infer behavior.

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

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

The input schema has 100% description coverage, so the baseline is 3. The description adds extra meaning by giving a concrete type example ('sec_8k'), specifying the ISO timestamp format for since, and explaining the effect of mark_read on future calls. It does not explicitly cover limit or unread_only, but the schema already describes them well, and the added context for type and mark_read exceeds the baseline.

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

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

The description clearly states the tool's function: 'Pull fired events from your subscription feed.' It specifies the resource (alerts in the subscription feed) and the exact output (source, citation_uri, raw event payload). It distinguishes this from sibling tools by focusing on reading alert events, not managing subscriptions or performing other actions.

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

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

The description gives clear usage context: filter by type and/or since, use mark_read to advance the feed, and notes that polling works fine. It also mentions an alternative HTTP endpoint for scripts/dashboards, which aids in deciding when to use the tool vs. other access methods. It does not explicitly contrast with sibling tools like recent_changes, but the guidance is sufficient for most use cases.

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

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

Beyond the readOnly/idempotent annotations, the description discloses multi-source fan-out (SEC, GDELT/GNews, USPTO), the GDELT-priority fallback logic, the USPTO sunset soft-fail, and the return structure (changes[] grouped by source, total_changes, citation URIs). This is rich, non-redundant behavioral context.

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

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

The description is dense but well-organized, front-loading examples and then covering multi-source behavior, parameters, and alternatives. Every sentence contributes useful information, though it could be slightly trimmed; it earns a 4 rather than 5.

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

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

The tool is complex (multi-source aggregation, fallbacks, time handling), and the description covers all key aspects: input formats, source behavior, fallback conditions, output structure, and an explicit alternative. Without an output schema, the description still fully informs the agent about return values and edge cases.

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

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

Schema coverage is 100%, so baseline is 3. The description adds practical value by explaining `since` accepts ISO dates or relative shorthand, recommending '30d'/'1m' for monitoring, and clarifying that `value` can be a ticker or CIK—details 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 clearly states the tool provides a time-windowed change feed for a company, backed by concrete example queries ('What's new with X', etc.). It distinguishes itself from the sibling entity_profile by explicitly noting that tool for static profiles, making the purpose and scope unmistakable.

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

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

The description gives explicit usage scenarios with example queries, specifies fallback behavior (GDELT→GNews) and soft-fail conditions, and directly names entity_profile as the alternative for static profiles. This tells the agent exactly when to use this tool versus the sibling.

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 non-read-only, idempotent, and non-destructive. The description adds meaningful context: key-value scope by identifier, persistent memory for authenticated users vs. 24-hour retention for anonymous sessions, and pairing behavior with recall/forget.

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 with no wasted words. Purpose, usage, storage semantics, and related tools are all covered efficiently 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?

For a simple 2-param tool with full schema coverage and annotations, the description is complete. It explains persistence, scoping, and integration with sibling tools. No output schema is needed for this straightforward write operation.

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

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

The input schema already covers both parameters with descriptions (key as memory key, value as text). The description provides illustrative examples for key (e.g., 'subject_property') and notes free-form nature of value, but this is largely redundant with schema. Baseline 3 is appropriate given full schema coverage.

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

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

The description uses a specific verb and resource: 'Save data the agent will need to reuse later.' It clearly distinguishes from siblings by explicitly mentioning recall (retrieve) and forget (delete) as complements.

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 an explicit 'Use when' condition ('when you discover something worth carrying forward... so you don't have to look it up again') and names alternative tools (recall, forget) with their distinct roles.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds significant behavioral context beyond that: it explains fallback behavior ('LEI/FIGI enrichment degrades gracefully'), internal cascading ('each call cascades through several lookup endpoints internally'), and output handling ('an identifier that could NOT be resolved is stated explicitly under `unresolved`'). This is exactly the kind of context an agent needs that annotations do not provide.

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

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

The description is long but information-dense, with no filler. It opens with example queries to make the purpose instantly clear, then organically organizes details under 'SUPPORTED TYPES' and adds important caveats like graceful degradation. While it could be trimmed, the structure is effective and every sentence earns its place.

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

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

With no output schema, the description must explain return values, and it does so thoroughly: it lists the exact identifiers returned for each type, mentions source labels, and explicitly describes the unresolved field. It also covers fallback behavior and the tool's ability to replace multiple lookups, making it complete for an agent to understand expected behavior.

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 full descriptions for both parameters (type and value) with examples and enum values, so baseline is 3. The description adds extra meaning by elaborating on what each type returns (CIK/ticker/LEI/FIGI for company, RxCUI/brand/ingredient for drug) and clarifies accepted input formats, which helps the agent construct valid calls.

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: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It uses a specific verb (resolve) and resource (entity names to identifiers), and distinguishes itself from siblings by positioning it as the first step for name-to-ID lookups, e.g., 'Use FIRST whenever you have a name but need an ID.'

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 context with 'Use FIRST whenever you have a name but need an ID' and includes example queries to illustrate when to invoke it. It does not explicitly mention when not to use it or name alternative tools, but the guidance is clear enough to make the intended use unambiguous.

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

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

Discloses the probing method (probes each entity with ai_visibility_check), ranking behavior, and return fields (score, confidence, signal density). Safety aspects are already covered by annotations (readOnlyHint, idempotentHint, destructiveHint=false), so the description adds meaningful operational context beyond them.

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

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

Four sentences efficiently convey purpose, method, use case, and output. The quoted example is illustrative and not redundant. Slightly more verbose than the minimal two-sentence ideal but still crisp and well-structured.

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

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

For a comparative read-only tool, the description covers purpose, method, use case, and output shape. Since no output schema exists, it compensates by listing return metrics (score, confidence, signal density). It does not discuss latency or failure modes, but these are minor given the annotations and simplicity.

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

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

Schema coverage is 100% with descriptions for all four parameters, including the special rule that the first entity is the 'subject'. The tool description adds no additional parameter-level meaning, so the baseline 3 is appropriate.

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

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

The description clearly states 'Compare AI visibility across multiple entities side-by-side' with a specific verb, resource, and scope. It distinguishes itself from sibling ai_visibility_check by explicitly addressing multiple entities and from compare_entities by focusing on AI presence and ranking.

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

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

Provides a concrete use case ('competitive AI-marketing audits') and an illustrative question ('does Claude know about us as well as our competitors?'). It implies use for multi-entity comparison versus single-entity ai_visibility_check but does not explicitly name alternatives or 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 adds behavioral context beyond the readOnly/idempotent annotations by disclosing partial failure modes: 'Partial failures degrade gracefully — bundlephobia's first measurement on a new version can take 5-30s; sources_failed will list it if it times out, the rest still returns.' It also describes the composite fan-out behavior, which is not derivable from annotations alone.

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

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

The description is dense but well-structured, with the main purpose front-loaded and details about usage, exclusions, and failure modes contained in later clauses. It is longer than typical but every sentence earns its place given the tool's complexity.

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

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

With no output schema, the description fully details the return structure, listing summary block fields, per-advisory detail, links, and alternative versions. It also covers partial failure behavior and timeout expectations, making it complete for invoking and interpreting results.

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

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

The input schema already provides 100% coverage for both parameters, including the scoped-package acceptance and default version behavior. The description does not add any additional parameter semantics beyond the schema, so a baseline of 3 is appropriate.

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

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

The description explicitly states it is a 'Composite "should I add this npm package to my project" check in ONE call' that fans out across deps.dev and bundlephobia, covering license, advisories, version history, bundle size, dependency count, and ESM/tree-shake support. It clearly identifies the tool's function and distinguishes it from sibling tools by specifying the npm ecosystem scope and the composite nature.

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 usage signals: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also defines exclusions: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly,' giving clear when-to-use and alternative guidance.

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

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

Annotations already disclose read-only, non-destructive, open-world, and idempotent behavior. The description adds return fields, but this information is also available in the output schema. It does not disclose additional behavioral traits such as pagination, result limits, or matching rules.

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 with no filler. It states the action, resource, and result fields efficiently.

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 search tool with rich annotations and an output schema, the description is adequate. It covers the core search action and return information without requiring additional detail. Minor gaps like pagination or matching behavior could be addressed but are not critical.

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

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

Schema coverage is 100%, with a clear description and examples for the query parameter. The description's phrase 'by name' simply restates the schema, adding no new semantic detail.

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 searches Star Wars characters by name and lists what it returns. It is distinct from sibling tools like search_within because it specifically targets people characters.

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

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

No explicit when-to-use or alternative guidance is provided. Usage is implied by the tool's purpose: use it when you need to find character data by name. There are no exclusions or mention of siblings that might be more appropriate for other cases.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description reveals the return payload (passages with offsets and similarity scores), the implementation (BGE-base-en embeddings, cosine, 500-char windows), and the 200K character cap with truncation flagging. There is no contradiction with annotations.

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

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

The description is dense but not bloated; four sentences cover purpose, usage, pairing, and technical constraints, all front-loaded with the core concept. Every sentence contributes actionable detail, and there is no redundant restating of the title or schema.

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

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

Since there is no output schema, the description compensates by specifying return values (top-N passages, character offsets, similarity scores) and limitations (200K char cap, truncation flagging). Combined with rich annotations and full parameter descriptions, the tool is fully specified for an agent.

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

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

Schema coverage is 100% with each parameter described, so the baseline is 3. The description adds meaningful context by framing 'text' as 'the text you already pulled' and providing natural-language query examples for 'query,' which clarifies how these parameters should be used in practice.

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

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

The description opens with 'Semantic search INSIDE a fetched record,' which clearly identifies the tool's specific verb, resource, and scope. It distinguishes itself from sibling tools like ask_pipeworx by focusing on searching within already-retrieved text rather than querying the gateway directly.

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

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

'Use when the record is too big to cram into the prompt' gives an explicit usage condition, and the pairing with ask_pipeworx_grounded (fetch with gateway, then ground over passages) provides a concrete alternative workflow. This satisfies the when-to-use and alternative-naming requirements.

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 extensive behavioral details beyond annotations: auth requirements (OAuth only, anonymous/BYO cannot persist), delivery channel specifics (sms phone verification, 10/day cap, webhook HMAC signing with one-time secret, auto-disable after 10 failures), and the always-on feed. Annotations are minimal (readOnly=false, openWorld=true, idempotent=true, destructive=false), and the description provides richer safety and operational context without contradicting them.

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

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

The description is relatively long (~190 words), but the tool is complex with multiple subscription types and delivery channels. It is front-loaded with the core purpose and return value, and every subsequent sentence adds essential details (auth, type-specific params, delivery rules, webhook behavior). While dense, it remains organized and avoids redundant filler, though it could be tightened slightly without losing value.

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

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

Given the tool's complexity, the description is remarkably complete. It covers all subscription types with parameter examples, delivery channels with operational constraints, authentication requirements, and return values (subscription id, webhook secret). No output schema exists, so the description appropriately discloses what the caller receives. It also anticipates edge cases (phone verification, auto-disable, feed availability), making it satisfactory for an agent to invoke correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by providing concrete examples for each subscription type (e.g., 'items:["5.02"] = officer change', 'params:{topic:"fed"}') and clarifying nested param structures. It also elaborates on delivery params with integration details (HMAC signature, verification steps), enriching the schema's concise definitions. This goes beyond mere repetition, warranting a 4.

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

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

The description opens with a clear verb+resource: 'Create a proactive monitoring subscription to a live-data event stream.' It also specifies the return value (new subscription id) and distinguishes itself from siblings like list_subscriptions and unsubscribe by focusing on creation. The supported types (sec_8k, polymarket_edge, fred_series) further clarify its distinct purpose.

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

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

The description provides clear usage context: when to use (proactive monitoring), prerequisites (requires OAuth account), and delivery alternatives (feed vs email vs sms vs webhook). It mentions that the feed can be pulled via recent_alerts or a GET endpoint, which implicitly contrasts with this subscription creation tool. However, it does not explicitly state when not to use this tool or name alternative tools for different scenarios, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the bar is lower. The description adds behavioral context that results are drawn from the live catalog (implying current data) and that the tool returns structured mappings from example questions to tools/arguments. 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 a single dense paragraph that front-loads with example queries and flows logically from purpose to usage to parameter guidance. Every sentence adds value, though it is slightly longer than necessary. Good structure for an onboarding tool.

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

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

With no output schema, the description carries the burden of explaining return values, and it does so thoroughly: category-bucketed example questions, each with the exact tool and argument shape, drawn from the live catalog. It also covers argument behavior and when to use the tool, making it complete for an onboarding meta-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% since the only parameter (topic) is fully described in the schema, including allowed values and omission behavior. The description repeats some of this with examples ('finance', 'pharma', 'betting') but adds little beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly identifies the tool as the onboarding entry point for agents, explicitly stating it returns category-bucketed example questions with exact tool and argument shapes. It distinguishes from siblings by positioning itself as the first tool to use and by naming the meta-tools (ask_pipeworx, entity_profile, compare_entities) it teaches.

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

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

The description gives explicit usage guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains when to omit or pass the topic parameter ('Call with no arguments for the full spread, or pass `topic` to focus'). No explicit exclusions, but the when-to-use is clear.

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

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

Beyond annotations, the description reveals soft-delete behavior (row deactivated not deleted) and ownership enforcement, which are key behavioral traits. This aligns with idempotentHint and destructiveHint annotations without contradiction.

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

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

Three sentences, all informative, starting with the action, then ownership, then the side effect. No redundancy and every sentence adds value.

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

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

For a simple one-parameter tool with no output schema, the description covers the action, parameter, ownership, and persistence of historical data. Annotations handle idempotency, leaving no significant gaps.

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

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

The schema already describes id as a uuid returned by subscribe, but the description adds the semantic constraint that the id must be your own subscription, enriching 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 'Cancel' with the resource 'subscription' and identifies the action by id. It distinguishes from siblings like subscribe and list_subscriptions by emphasizing cancellation and ownership enforcement.

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 context that only own subscriptions can be canceled and mentions that historical events remain available via recent_alerts. However, it does not explicitly name alternatives for cancellation itself, only pointing to recent_alerts for history.

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

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

The description discloses significant behavioral context beyond annotations: the dual-path routing, the complete verdict list, and the crucial distinction between could_not_verify (a pipeline failure, not evidence) and unsupported (no source coverage). It also warns callers not to treat could_not_verify as evidence, which is valuable transparency not captured in the readOnly/openWorld/idempotent flags.

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 earns its place: trigger phrases are front-loaded, the routing and error semantics are organized clearly, and the IMPORTANT callout for could_not_verify is essential. The structure is efficient and easy to scan for a tool with this 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 covers return values (verdict, actual value, citation, reasoning) and edge cases (could_not_verify vs unsupported). It also explains its role as a consolidator of multiple sequential calls, giving the agent complete context for when and how to use it.

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

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

The input schema covers both parameters (claim and tolerance_pct) with full descriptions, so the baseline is 3. The description mentions 'exact percent-delta math' but adds no parameter-specific semantics beyond what the schema already provides, so it stays at 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 identifies the tool as a natural-language claim verification service with trigger phrases like 'fact check' and 'true or false.' It distinguishes it from sibling tools by explaining that it replaces 4–6 sequential calls, making its purpose specific and actionable.

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

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

It explicitly states when to use the tool: whenever the agent needs to check whether a user's statement is factually correct, and it describes the two routing paths (SEC EDGAR for company financials, grounded pipeline for other claims). However, it does not explicitly name sibling alternatives or provide when-not-to-use guidance, 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.