Ukri Gtr

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

The description goes beyond annotations by disclosing the return structure (per-model {score, confidence, signals, raw_response} + combined view), cost implications (free vs. BYO key), and the role of the 'context' parameter. No contradictions with annotations.

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

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

Three sentences that front-load the action and key result. Every sentence adds useful information without redundancy.

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

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

Despite no output schema, the description clearly explains return values and covers model options, cost, and disambiguation. It is complete for the tool's complexity.

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

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

With 100% schema coverage, baseline is 3. The description adds value by explaining default model behavior, the purpose of _apiKey (pass-through to Anthropic), and how 'context' disambiguates entities.

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 ('probe') and resource ('LLMs for what they know about a business / brand / product / topic') and clearly distinguishes the tool's purpose from siblings by focusing on AI visibility scoring rather than Pipeworx-specific queries.

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 states when to use it ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains model selection and API key usage. It does not explicitly mention alternatives or when not to use, but the context 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so safety profile is clear. The description adds meaningful behavioral context: the tool acts as a router that fills arguments automatically, searches many sources, and returns stable pipeworx:// citation URIs. This goes beyond the annotations without contradicting them, though it does not mention rate limits or failure modes.

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

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

The description is long but front-loaded with the most important directive ('PREFER OVER WEB SEARCH') and then logically builds from scope to examples to alternatives. While verbose, every section serves a distinct purpose—no filler or repetition—and the structure makes key guidance scannable.

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

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

For a meta-router tool with no output schema and a single flexible question parameter, the description is remarkably complete. It covers what the tool does, what data domains it serves, how it behaves (routing, auto-fill, citations), when to use alternatives, and provides multiple query examples. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 100% and every parameter is documented as an alias for 'question', so the structured data already explains the parameters. The description adds practical semantics by giving sample questions ('current US unemployment rate', 'Apple's latest 10-K') and clarifying that natural-language queries are accepted, which helps the agent formulate valid input.

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 is explicit: it answers factual questions by routing to the right tool among 5,798 across 1,517 verified sources, and returns structured answers with citation URIs. It clearly distinguishes itself from web search and from siblings like ask_pipeworx_grounded and deep_research, so an agent can tell what this tool is for without ambiguity.

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 when-to-use guidance: prefer over web search for a broad category of data, use for queries starting with 'what is', 'look up', 'find', etc., and includes concrete examples. It also explicitly states when to use alternatives: ask_pipeworx_grounded for verbatim-evidence single answers and deep_research for broad/multi-part questions, leaving no inference to the agent.

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 and idempotent, and the description adds substantial behavioral context: it is an experimental edge with possibly live routing candidates, currently has no active candidate, exactly matches ask_pipeworx today, and is a full working router rather than a stub. This prevents an agent from misjudging it as dangerous or non-functional. 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 front-loaded with identity, followed by current status, usage guidance, and a clarifying note. There is slight redundancy in stating both that it 'currently matches ask_pipeworx exactly' and to 'use it exactly like ask_pipeworx,' but the overall structure is efficient and every detail serves a purpose.

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

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

For a single-question router with no output schema, the description covers what the tool is, how it currently behaves, when to prefer it, and that responses match ask_pipeworx. It does not describe the return value shape directly, but the pointer to ask_pipeworx compensates, and the tool is simple enough that this is not a serious gap.

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

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

Schema description coverage is 100%, and the input schema fully documents the required question parameter along with its five aliases. The description only repeats 'same arguments' and adds no new parameter-level meaning, so the baseline of 3 applies.

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

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

The description clearly identifies the tool as the beta version of ask_pipeworx and an identical universal router over 5,798 tools, making its purpose evident and distinguishing it from the stable sibling. It relies on the noun 'router' rather than an explicit verb like 'answers', but the intent is still unambiguous.

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

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

The description gives an explicit usage condition: 'Use it exactly like ask_pipeworx when you want the newest routing.' It names ask_pipeworx as the stable alternative and explains that results are compared against it. It does not explicitly state when not to use it, but the experimental-versus-stable contrast provides enough guidance.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints, and the description adds significant context beyond them: it discloses that only tool-result content is used, describes the exact success and refusal return shapes, lists refusal reasons, and notes the extra LLM call cost. No contradiction with annotations found.

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

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

The description is dense but every sentence earns its place: purpose, routing behavior, output shape, refusal semantics, usage guidance, and cost tradeoff are all covered without fluff. Key differentiators are front-loaded.

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

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

Given there is no output schema, the description compensates well by fully specifying the return value shape and refusal reasons. It also explains when to prefer this over its sibling, covers cost implications, and provides enough context for correct invocation and interpretation of results.

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

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

Schema description coverage is 100%, so the schema fully documents the 'question' parameter and its aliases. The description does not add parameter-level detail, which is acceptable given high coverage, but it also doesn't need to; the baseline of 3 applies.

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

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

The description states a specific verb and resource ('Hallucination-resistant answer mode') and clearly differentiates from ask_pipeworx by emphasizing extraction only from the tool result. It also explicitly names the sibling it relates to and the key distinction, so an agent can select it correctly without opening schemas.

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

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

The description gives explicit when-to-use guidance ('whenever an answer will be quoted, cited, or acted on') and when-not-to-use guidance ('prefer ask_pipeworx for casual lookups'). It also explains the cost tradeoff, which helps an agent make an informed routing decision.

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 extensively discloses behaviors: fan-out patterns, resolver match confidence, parent_event extraction, news fallback, safety short-circuits, cancellation rules. This adds significant context beyond annotations, which only state readOnlyHint and idempotentHint.

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

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

The description is comprehensive and well-structured, with clear sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). While lengthy, every sentence adds value; it is appropriately detailed for the tool's complexity.

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

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

Given no output schema, the description thoroughly documents response shapes, edge cases (illiquid spread, cancellation rules, news fallbacks), and result inspection guidance. It covers all likely agent questions.

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

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

Schema coverage is 100%, but the description adds crucial context: for 'market' it shows example inputs, for 'depth' explains quick vs thorough, for 'include_raw' clarifies payload sizes and use cases. This goes well beyond the schema definitions.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data, with specific verb ('Research'), resource ('Polymarket bet'), and inputs (slug, URL, question). It distinguishes from siblings by detailing its scope and behavior.

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

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

The description explicitly lists use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and describes blocking conditions (low-confidence, closed markets). However, it does not explicitly name alternatives when not to use.

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

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

The description provides extensive behavioral details beyond annotations: data sources (SEC EDGAR/XBRL for companies, FAERS/FDA/ClinicalTrials for drugs), handling of fiscal year offsets, sorting by primary metric, and return format with citation URIs. No contradictions with annotations.

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

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

The description is efficiently front-loaded with example queries, then provides detailed behavioral information. Every sentence adds value, no redundancy. The structure is clear and easy to parse.

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

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

Despite no output schema, the description fully explains return values (paired data and citation URIs). It covers both entity types, data sources, sorting behavior, and replaces multiple lookups, making it complete for the tool's complexity.

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

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

Schema coverage is 100%, but the description adds context by explaining how each type (company/drug) works and clarifying the values array format (tickers/CIKs for companies, names for drugs). This adds meaning beyond the schema descriptions.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs in one call, using specific verbs like 'compare' and resource types. It distinguishes from siblings like entity_profile which handles single entities.

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

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

The description advises to use this tool over sequential single-entity lookups when comparing entities, providing explicit triggering phrases. However, it does not name alternative tools or specify when not to use it, leaving some room for improvement.

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

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

Annotations already declare readOnly/openWorld/idempotent/destructive=false, but the description goes well beyond: it discloses auth and pricing constraints, parallel decomposition, return-packet structure, gaps[] behavior, contradictions[], citation_uri fetchability, semantic excerpting, and latency. No contradiction with annotations; this is the gold standard for behavioral disclosure.

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

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

Dense and information-rich with no wasted sentences, but not front-loaded: the core purpose appears only in the third sentence after account/auth instructions and the alternative. Still, each sentence earns its place given the tool's complexity and the absence of an output 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?

Complete for a complex tool with no output schema. It explains return value structure (verbatim evidence, confidence, source, fetched_at, citations, gaps[], contradictions[]), operational constraints (auth, pricing, latency), failure modes (empty gaps for non-structured topics), and additional behaviors (semantic excerpting, hop field). Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds semantic guidance for the question parameter with examples ('compare X and Y's regulatory + financial exposure') and clarifies depth behavior in terms of 'hop' and gap recovery. It reinforces the schema rather than adding entirely new meaning, but the examples and 'NOT open-web search' framing do help an agent craft better inputs.

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

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

States a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources... in ONE call.' Distinguishes itself from open-web search and ask_pipeworx, and gives concrete example questions. Clear enough for an agent to route correctly.

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

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

Explicitly says when to use this tool ('Best for broad/multi-part questions over structured data') and when not to ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'). Also provides account-tier routing: use ask_pipeworx if not signed in. Exceptional 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=true and idempotentHint=true, so the description adds value by detailing the return format: 'top-N most relevant tools with names, descriptions, and full input schemas... ready to call directly.' 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 front-loaded and efficient, with each sentence serving a purpose. The list of domains is somewhat lengthy but necessary for clarity. Overall concise for the information conveyed.

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 discovery tool with one required parameter and no output schema, the description fully explains what the tool does and what it returns. No gaps remain.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context by mentioning natural language input and showing example queries, but does not significantly elaborate on parameter behavior beyond what the schema provides.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, FDA drugs, etc.) and distinguishes itself from sibling tools by focusing on discovery rather than domain-specific operations.

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

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

Provides explicit usage context: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' While it implies not to use when a specific tool is known, it does not explicitly name alternative tools.

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

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

With read-only, open-world, and idempotent annotations already present, the description goes well beyond them by disclosing behavior like fan-out across multiple sources, sources_used/sources_failed semantics, empty sections being real no-data results, private-company resolution behavior, and soft-fail behavior for patents. This gives the agent accurate expectations about what the tool will return and how to interpret it.

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 long, but every sentence carries operational value: invocation examples, source list, return fields, resolved/not-resolved behavior, and parameter semantics. It is front-loaded with the core purpose and the ALWAYS PREFER guidance. A bit of restructuring into shorter sentences or bullets would improve readability, but there is no wasted content.

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

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

There is no output schema, so the description carries the full burden of explaining return values, and it does so thoroughly: cik, company_name, recent_filings URIs, fundamentals, sources_used/sources_failed, and resolution behavior. It also covers edge cases like private companies, FDA-licensed biologics showing none, and patent source soft-fails. For a tool of this complexity, the description is complete enough for safe 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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful nuance: ticker, zero-padded CIK, or company name all work; name resolution happens via SEC EDGAR; type accepts company/ticker interchangeably; and private companies produce resolved:false with a notes line. These details go beyond the schema's property descriptions and help the agent construct valid inputs.

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

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

The description states a specific verb and resource: it produces a full cross-source profile of a US public company in one parallel call. It also differentiates itself from chained single-pack SEC/XBRL/news lookups, making the tool's scope unmistakable. Example phrasings like "tell me about X" and "company profile for Microsoft" anchor the purpose concretely.

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

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

The description explicitly says when to use it: whenever the user asks for a holistic view of a company, and it instructs ALWAYS PREFER over chaining single-pack lookups. It stops short of naming specific sibling alternatives like compare_entities or resolve_entity, but the category-level guidance is clear 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?

Description matches annotations (destructiveHint: true, readOnlyHint: false). Adds context about clearing sensitive data but doesn't go substantially beyond what annotations imply. 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?

Two sentences, front-loaded with purpose. Every sentence adds value: first defines action, second provides usage context. No wasted words.

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

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

For a simple tool with one parameter and no output schema, the description fully covers purpose, usage guidelines, and pairing. No 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?

Only one parameter 'key' with schema coverage 100%. Description 'Memory key to delete' adds no new meaning beyond the schema. Baseline score of 3 applies.

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

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

The description clearly states 'Delete a previously stored memory by key', using a specific verb and resource. It distinguishes itself from siblings like 'remember' and 'recall' by focusing on deletion.

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

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

Explicitly states when to use: when context is stale, task is done, or to clear sensitive data. Mentions pairing with remember and recall. Does not include when-not, but positive guidance 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?

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) are consistent with the description, which adds detail about fetching the page, extracting title/description/key links, and emitting markdown format. No contradictions.

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

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

Four sentences with no wasted words: first sentence states purpose and audience, second explains process, third describes output, fourth lists use cases. Perfectly 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?

Tool has only two parameters (no nested objects, no enums), no output schema, but annotations cover safety. Description fully explains input, process, output, and use cases, leaving no gaps 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 descriptions for both parameters. The description adds value by specifying default and max for 'max_links' (default 25, max 50), which is not in the schema.

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

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

The description clearly states it generates a 'production-ready llms.txt file' for any URL, specifying the exact output format and use cases. It differentiates from sibling tools like 'ai_visibility_check' by focusing on file generation.

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?

Describes three explicit use cases (client indexing, personal project drafting, competitor auditing). While it doesn't state when not to use, the contexts are clear and sufficient for an AI agent to decide.

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 annotations by listing the exact returned fields (award value, lead organisation, etc.) and confirming it works with both GUID and human-readable references. This enriches the agent's understanding of what the tool does.

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, concise and front-loaded. The first sentence states the purpose and identifier formats, the second lists returns. 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 lookup tool with one parameter and no output schema, the description adequately covers input and output. It mentions specific return fields, though it doesn't discuss pagination or error handling, which are minimal for this use case.

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

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

The input schema already has 100% coverage with a detailed property description and examples. The description restates the parameter's purpose but does not add new semantic constraints or format details beyond what the schema provides.

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

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

The description explicitly states the tool returns full detail for one UKRI-funded project, using verb 'looked up' and specifying the resource. It distinguishes from sibling tools like gtr_search_projects by emphasizing it returns comprehensive information for a single project.

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

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

The description clearly indicates it is for retrieving full details of a specific project when you have a GtR GUID or grant reference. It doesn't explicitly state when not to use it, but the context of looking up by identifier implies it's for known projects.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds value by detailing the return fields: grant references, project titles, funding councils, departments, statuses, funding periods, and total award count. This goes beyond 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?

The description is concise, with two sentences. The first sentence states purpose and input, the second details returns and filters. No extraneous information.

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

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

Given the tool's moderate complexity (5 params, no output schema), the description covers the return fields and filtering. It lacks mention of pagination (page/limit) but the schema covers that. Overall, it provides sufficient context for an agent to use the tool effectively.

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

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

Schema coverage is 100%, so parameters are well-documented. The description adds meaning by explaining that the 'organisation' parameter accepts a GUID or name, and clarifies the use of 'funder' and 'status' for narrowing results. This provides context beyond the schema.

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

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

The description clearly states the verb 'List', the resource 'UKRI grants held by one institution', and the input method (GtR organisation id or name). It is specific and distinguishes this tool from siblings like gtr_search_projects, which is for searching all projects, not by institution.

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

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

The description explains when to use the tool: to see an institution's research funding portfolio. It mentions filtering by funding council and status, providing clear context. However, it does not explicitly exclude alternatives or mention when not to use it, such as for single project retrieval.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds that results include specific fields (id, name, postcode, region) and that the tool only returns UKRI-funded institutions. This is useful but not extensive; it does not contradict the annotations.

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

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

The description is a single, front-loaded sentence with a clear action verb and a brief usage tip. Every word is essential, and there is no repetition 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?

No output schema exists, so the description must cover return values; it does so by listing the returned fields. It also explains the prerequisite (institution must have received UKRI funding) and suggests the next tool. With only 3 well-documented parameters, this is complete enough for an agent to use correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description mentions 'institution name' for the name parameter, but the schema already provides a clear example and description. No additional semantic value beyond the schema.

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

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

The description starts with 'Find UK universities, research institutes and companies...by institution name.' It uses a specific verb (find) and resource (organisations), and the narrow scope (UKRI-funded institutions) clearly distinguishes it from sibling tools like gtr_search_projects or gtr_organisation_projects.

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

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

The description explicitly tells the agent to use the returned id with gtr_organisation_projects to get funded projects, providing a clear follow-up action. While it doesn't list when not to use this tool versus alternatives, the context is clear enough for typical search scenarios.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, covering safety and idempotency. The description adds that it returns specific fields (output schema), which is useful but not a behavioral trait beyond what annotations provide.

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

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

The description is two sentences: first states action and output, second adds usage context. Every sentence is informative, no wasted words, and front-loaded with key information.

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

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

Given 6 parameters with 100% schema coverage and no output schema, the description adequately explains the tool's purpose, typical use cases, and return fields. It lacks details on pagination or edge cases, but for a search tool with good annotations, this is sufficient.

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

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

Schema coverage is 100%, so baseline is 3. The description adds usage context by mentioning free-text search over titles/abstracts and narrowing by funder/status, but does not elaborate on page, limit, or search_field beyond their schema descriptions.

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

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

The description clearly states it searches UK research grants by free text over titles and abstracts, and lists the specific fields returned (grant reference, project title, etc.). It distinguishes from sibling tools like gtr_get_project (single project) and gtr_search_publications by focusing on grants and free-text search.

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 ('for questions like which UK grants fund a given topic...') and mentions narrowing by funder and status. It does not explicitly say when not to use this tool versus alternatives, but the context of sibling tools implies specialization.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. The description adds context by listing returned fields (title, authors, journal, DOI, etc.) and the GtR project ID, which helps an agent understand the output beyond what annotations cover.

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

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

The description is two sentences: the first clearly states the purpose, the second lists return fields. It is front-loaded, concise, 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?

Despite no output schema, the description sufficiently explains the return values (title, authors, journal, etc.) and the GtR project ID for tracing. Combined with clear input schema and annotations, the description is complete for an agent to use the tool effectively.

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

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

Schema coverage is 100%, with clear descriptions for all parameters. The description does not add new information about parameter usage beyond what the schema already provides, meeting the baseline for high coverage.

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

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

The description clearly states it searches journal articles, books, and conference papers reported as UKRI grant outcomes. The verb 'Search' and resource 'publications' are specific, and it distinguishes itself from sibling tools like gtr_search_projects by focusing on publications linked to funding.

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 for finding UKRI-funded publications and explains the value of the GtR project ID for tracing funding. However, it does not explicitly state when not to use this tool or compare it directly to siblings.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false. Description adds the list of returned fields and mentions 'active subscriptions', but doesn't disclose further behavioral traits beyond the annotations.

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

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

Two sentences, front-loaded with purpose and outputs, followed by usage guidance. No wasted words.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description covers purpose, outputs, and usage guidance completely.

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

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

Schema coverage is 100% for the single parameter. The description mentions 'active' which aligns with the parameter description 'Include cancelled', but adds minimal extra meaning beyond the schema.

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

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

The description clearly states 'List the caller's active subscriptions' and lists the fields returned, distinguishing 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?

Explicitly states when to use: 'review what you're monitoring before adding more or to find an id to cancel', providing clear context and implying alternatives.

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

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

Annotations are all false, so the description carries full burden. It discloses rate-limiting ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), the claim_token behavior for retrieving status, and that the team reads daily digests affecting roadmap. These are meaningful behavioral traits beyond simple read/write hints.

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

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

The description is longer than average but every sentence earns its place: purpose, when/not-to-use, message format, token behavior, impact, and limits. Information is front-loaded with the core purpose and usage, and the rest provides necessary operational 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?

Given the lack of an output schema, the description compensates by explaining the claim_token return and how to use it. It covers all parameter semantics indirectly, provides exclusion conditions, usage context, and operational details like rate limits and quota. The complexity is well addressed without needing additional structured fields.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra value by explicitly demonstrating claim_token usage with an example call, and by guiding message content ('in terms of Pipeworx tools/packs'). It does not add much beyond schema for 'type' or 'context', but the added claim_token detail justifies a 4.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates feedback categories (bug, feature/data_gap, praise) and is distinct from siblings like ask_pipeworx, which are for queries rather than feedback. The verb 'tell' plus resource 'Pipeworx team' is specific.

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

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

Explicit when-to-use guidance: 'Use when a tool returns wrong/stale data... when a tool you wish existed isn't in the catalog... or when something worked surprisingly well.' It also provides explicit exclusions: 'ONLY for tools served by this Pipeworx connection' and instructs to file with another server otherwise. Includes guidance on what to write ('in terms of Pipeworx tools/packs') and what not to write ('don't paste the end-user's prompt').

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds valuable behavioral context: self-aggregating, no PII, cached 5min-1h, derived from CF analytics. This goes well beyond the annotations.

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

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

Two concise sentences plus a clear bullet list, front-loaded with the main result. Every sentence adds value with no fluff or repetition. Ideal length for a simple read-only tool.

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

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

For a simple tool with one optional parameter and no output schema, the description is complete: it covers purpose, usage, behavior, parameters, and return value (top tools, packs, volume). No gaps remain.

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

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

Schema coverage is 100% and the schema description explains the window enum. The tool description adds practical guidance: shorter windows for 'hot right now', longer for steady-state demand. This adds meaning beyond the schema, but the schema itself is already informative.

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

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

The description clearly states the tool returns top tools, packs, and call volume over a window, using specific verbs like 'returns' and 'calling'. It distinguishes itself from siblings by focusing on what other agents are using, which is unique among tools like ask_pipeworx or discover_tools.

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

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

Three explicit use cases are listed: discovering hot data sources, confirming canonical tools, and checking alignment. The description also explains how window choice affects results. It does not explicitly mention alternatives or when not to use, but the guidance is clear 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 declare read-only, idempotent, open-world. Description adds rich behavioral context: monotonicity checks, partition sum, semantic anchor (Jaccard), placeholder filter, fill check against CLOB depth. 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?

Description is fairly long but well-structured: overview, mode-specific details, output format, fill check. Some technical detail could be condensed but is justified by tool complexity. Not perfectly concise but adequate.

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

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

Despite no output schema, the description thoroughly explains return structure (opportunities[], partition_check{}, fill check fields). Covers all three modes, logic, and edge cases (placeholder filter, similarity threshold). Complete for a complex arbitrage 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% and description adds significant value: explains event slugs vs URLs, topic as seed question, clarifies behavior when no args given. Greatly enriches the basic schema descriptions.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks, with three distinct modes (no args, event, topic). It distinguishes from sibling tools like polymarket_edges and polymarket_fill_risk by focusing on arbitrage detection.

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

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

Explicit guidance on when to use each mode: no args for trending scan, event for specific market, topic for cross-event scan. Recommends event mode for known markets and warns against trading when realizable edge is ≤0. References sibling tool 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?

The description extensively discloses behavior beyond annotations, including model details, caching at 1h, response structure with diagnostics, and the treatment of Fed markets. It does not contradict annotations; it adds value by explaining how the tool operates and what limitations exist.

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

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

The description is front-loaded with the main purpose and well-structured in sections. While lengthy, each sentence adds meaningful detail about the tool's outputs and behavior, making it informative without being wasteful.

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

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

Without an output schema, the description fully explains the response structure, including by_segment, fed_candidates, and _diagnostics, as well as per-opportunity fields. It covers caching, knob effects, and edge cases like empty segments, making the tool's behavior completely clear.

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 value by explaining how knobs like min_kelly, min_partition_leg_kelly, and tradeable-edge filters interact, providing context beyond the schema descriptions.

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

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

The description clearly states the tool scans top Polymarket markets to find opportunities where Pipeworx data disagrees with market price, and it is built for discovering opportunities. It distinguishes itself from sibling tools through its specific focus on model-driven and structural arbitrage opportunities, and mentions that Fed bets are excluded from 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?

The description provides context that the tool is for 'what should I bet on today' and mentions tradeable-edge knobs, but it does not explicitly state when to use this tool versus alternatives like polymarket_arbitrage or polymarket_edge_tracker. Usage is implied but not clearly delineated with exclusions or comparisons.

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

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

Annotations already indicate readOnly and idempotent; the description adds valuable behavioral context: data gaps, decay calculation from daily closes (not intraday), and response structure. No contradiction with annotations.

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

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

The description is well-structured with purpose, args, response, and limits sections. It is somewhat verbose but each part adds necessary detail. Front-loaded with purpose.

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

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

Despite no output schema, the description thoroughly explains the response fields (tracked, expired, snapshot_dates) and limitations (60-day TTL, snapshot history). With only 2 simple parameters, the description is complete.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds default values, acceptable values (e.g., '24hr | 1wk | 1mo'), and clamping behavior, enhancing understanding beyond the schema.

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

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

The description clearly states what the tool does: 'Edge persistence and decay telemetry.' It answers a specific question and distinguishes from siblings like polymarket_edges by focusing on historical persistence rather than current snapshots.

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 (assessing edge persistence and decay) and hints at when not to use it (e.g., for current edges), but does not explicitly list 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?

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds behavioral context such as walking the ladder, returning specific fields like forced_directional_risk, and warning about partial fill risks. 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?

Description is somewhat lengthy but well-structured with clear headers (REQUIRES, SINGLE-MARKET, BASKET) and front-loaded purpose. Every sentence adds value, though minor trimming could improve conciseness.

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 complexity (two modes, 4 params, no output schema), description is very complete. It details both modes, parameter interpretations, return fields, and usage advice. Without output schema, it fully covers return fields.

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% (baseline 3). Description adds meaning beyond schema by explaining single-market vs basket modes, default side logic, and how size_usd is interpreted per mode (max spend on buys vs target proceeds vs settlement notional).

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

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

Description clearly states it performs a realizable-vs-theoretical edge check against live order-book depth, and distinguishes between single-market and basket modes with specific return fields. It differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by stating this tool should be used before acting on those signals.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Provides reasoning about un-capturable theoretical overround and risk of partial fills converting arb to directional position.

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 readOnly/idempotent/openWorld annotations by disclosing fees, gross-vs-net spread semantics, compatibility warning codes, temporal-alignment null semantics, and the rule that unknown-leg types are never paired. It also explains that returned pairs can still carry warnings and that temporal_alignment:null does not mean aligned. No statement contradicts 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 and dense, but it is well-structured with capitalized labels such as TWO MODES, RESPONSE, SAFETY FIELDS, and Codes, and it front-loads the core purpose and mode choice. Some redundancy exists — for example temporal_mismatch and temporal_alignment_unknown appear in multiple places — but the additional context is generally operational and necessary for safe use.

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

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

This is a complex tool with no output schema, so the description must carry the burden of explaining response shape, safety codes, edge cases, and limitations. It covers leg-by-leg prices, top_spreads_pp, per-entry flags, skipped classifications, fee disclosure, and the rare reality of real spreads. The agent has nearly everything needed to decide when and how to call it correctly.

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

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

The input schema already documents all three parameters with 100% coverage, including the topic list and override behavior. The description adds useful nuance by explaining that topic mode auto-fetches the matching event, explicit mode supports custom pairings, and both modes produce identical safety disclosures. This exceeds the baseline for schema-covered parameters.

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

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

The description opens with a clear statement that the tool computes a cross-venue spread between Kalshi and Polymarket for the same resolving question, and it explains the output as price deltas in percentage points. It is easy to tell this tool compares two prediction-market venues, though it does not explicitly name sibling alternatives such as polymarket_arbitrage or polymarket_edges, so sibling differentiation is implicit rather than direct.

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 explains the two modes — topic shortcuts for pre-mapped macro events and explicit tickers/slugs for custom pairings — and notes that both modes run the same matcher. It also warns that pre-mapped topics may return compatibility warnings and are not necessarily tradeable, giving practical guidance. It does not explicitly contrast the tool with alternatives, but the mode-level usage instructions are strong.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds scoping to identifier (anonymous IP, key hash, account ID) and clarifies retrieval source. No mention of rate limits or errors, but safety traits are covered.

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 main action, no fluff. Every sentence adds value: retrieval, usage examples, scope, and pairing with siblings.

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 retrieval tool with one optional parameter and no output schema, the description covers purpose, usage, scope, and pairing with related tools completely.

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

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

Schema coverage is 100%, and schema property description already says 'omit to list all keys'. Description repeats this and adds examples but does not add meaningful new detail beyond what schema provides.

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

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

Specifies verb 'retrieve' or 'list' and resource 'value previously saved via remember' or 'all saved keys'. Distinguishes from siblings 'remember' and 'forget' by naming them in pairing instructions.

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

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

Explicitly states when to use: 'look up context the agent stored earlier'. Provides examples (ticker, address, notes) and instructions for listing keys. Lacks explicit when-not-to-use, but context 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?

Annotations already indicate read-only, idempotent, non-destructive. Description adds behavioral detail: mark_read affects future calls, feed also accessible via GET endpoint. No contradictions.

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

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

Four sentences, front-loaded with the main purpose, then key details. No wasted words – every sentence adds value.

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

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

Describes return payload (source, citation_uri, raw event), filtering, and mark_read behavior. No output schema, but description sufficiently covers return values. Offers alternative endpoint for scripting. Complete for 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 covers all 5 parameters with descriptions. Description adds examples (e.g., 'sec_8k' for type), clarifies ISO timestamp for since, and explains mark_read effects. Provides useful extra context.

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

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

Starts with 'Pull fired events from your subscription feed' – clear verb and resource. Distinguishes from siblings like list_subscriptions by specifying it returns alerts/events, not subscription lists.

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?

Gives context: returns most recent alerts, provides filtering options (type, since, mark_read, unread_only), mentions polling works and an alternative endpoint. Lacks explicit 'when not to use' but clearly implies use for reading subscription events.

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

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

Annotations declare readOnly, openWorld, idempotent, non-destructive; description adds behavioral details: fans out to SEC, GDELT/GNews, USPTO; structured response with sources and citations. 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?

Single compact paragraph that efficiently front-loads use cases, then explains functionality and parameters, ending with alternative tool. No unnecessary content.

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

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

Covers all aspects: input parameters, behavior, fallback, soft-fail, output structure, and alternatives. Despite no output schema, description adequately describes return format.

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

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

Schema coverage is 100%, but description adds crucial context: since parameter formats (ISO date or relative shorthand like '30d'), type only supports 'company', value accepts ticker or CIK with examples.

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 explicitly states it provides a change feed for queries like "What's new with X" by aggregating from multiple sources in a single parallel call. It distinguishes itself from sibling entity_profile for static profiles.

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

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

Provides explicit guidance on when to use (dynamic change feed) vs when to use entity_profile (static profile). Also explains fallback from GDELT to GNews and soft-fail on USPTO.

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

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

Annotations already indicate idempotent and non-destructive behavior. The description adds valuable context beyond annotations: scoping by identifier, persistence differences for authenticated vs anonymous users, and retention period (24 hours for anonymous).

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

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

The description is three sentences long, front-loaded with the primary purpose, and every sentence adds value. No unnecessary words.

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

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

For a simple tool with 2 parameters and no output schema, the description covers usage context, behavior, and pairing with sibling tools. It is fully complete given the tool's complexity.

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

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

Schema coverage is 100% with descriptions for both 'key' and 'value'. The description does not add significant new parameter semantics beyond what the schema provides, though it reinforces the purpose with examples in context.

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

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

The description clearly states that the tool saves data for later reuse, using a specific verb ('Save data') and resource ('key-value pair'). It distinguishes itself from siblings like 'recall' and 'forget' by explicitly mentioning them.

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

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

The description provides explicit guidance on when to use: 'when you discover something worth carrying forward'. It also mentions when not to use by referencing alternatives: 'Pair with recall to retrieve later, forget to delete'.

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, open-world, and non-destructive; the description adds substantial behavioral detail: identifiers are labelled by source, unresolved identifiers appear under 'unresolved' rather than being omitted, ambiguous names return 'figi_candidates' without asserting a single answer, and GLEIF/OpenFIGI failures degrade gracefully while EDGAR identifiers still return.

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 purpose is front-loaded, but the body is a dense, run-on paragraph with nested parentheticals and a duplicated sentence: 'Each call cascades through several lookup endpoints internally — using resolve_entity replaces 2-3 manual lookups' appears twice. The phrase 'more than one instrument it asserts nothing...' is also truncated and awkward, making the structure harder for an agent to parse than it should be.

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?

Although there is no output schema, the description enumerates the returned identifiers (CIK, ticker, LEI, ownership, FIGI, RxCUI, ingredient, brand, citation), names the backing sources, explains how ambiguity and unresolved results are handled, and states fallback behavior. An agent has enough information to call the tool correctly and interpret its 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 schema covers both parameters, so the baseline is 3, but the description adds real value: it explains what 'value' means per type, warns to pass only the entity name, not the question's full noun phrase, gives a concrete bond-issuer example ('NEW YORK ST DORM AUTH' vs 'NEW YORK ST DORM AUTH revenue bonds'), and explains why trailing security-class words fail to match.

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

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

The description opens with concrete user queries ('What's the ticker for…', 'find the CIK for…', 'what's the LEI for…') and states the action: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It names supported entity types (company, drug) and specific identifier outputs (CIK, LEI, FIGI, RxCUI), making the tool's role unmistakable and distinct from downstream lookup tools.

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

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

'Use FIRST whenever you have a name but need an ID' is an explicit selection condition, and the description clarifies accepted input forms (ticker, CIK, ISIN, company name, drug brand/generic name). It does not explicitly discuss when-not-to-use or name sibling alternatives, but the 'other tools require as input' framing gives clear routing 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 provide readOnlyHint, idempotentHint, and openWorldHint, which align with the description. The description adds value by disclosing that it probes each entity with ai_visibility_check and returns a ranked list with score, confidence, and signal density, providing behavioral context beyond annotations.

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

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

The description is three sentences, front-loaded with the core action, no redundant or extraneous information. Every sentence contributes essential detail—what it does, how it works, and when to use it.

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

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

Without an output schema, the description specifies the return format (ranked list with score, confidence, signal density). It also explains the probing process and parameter roles (subject vs. competitors). It could include limitations or error handling, but given it composes ai_visibility_check, it is 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 coverage is 100% (all parameters described). The description adds extra meaning: entities parameter's first entry is treated as the 'subject' for narrative, rest as competitors. It also implies default model behavior (workers-ai) and the conditional need for _apiKey. This goes beyond the schema descriptions.

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

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

The description clearly states the tool compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks them, and surfaces the most/least recognized. It distinguishes itself from sibling tools like ai_visibility_check (single-entity) and compare_entities (generic) by specifying its focus on AI presence and competitive audits.

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

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

The description explicitly states it is 'useful for competitive AI-marketing audits' and gives a concrete use case question. While it doesn't explicitly say when not to use it, the context implies it's for comparing multiple brands' AI recognition, leaving single-entity checks to ai_visibility_check.

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. The description adds behavioral traits: composite fan-out across two sources, partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts. No contradictions.

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

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

The description is relatively long but front-loaded with main purpose and efficiently structured. Every sentence adds value (e.g., partial failures, ecosystem scope). Minor redundancy could be trimmed, but overall effective.

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

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

No output schema exists, but the description provides a thorough summary of the return value: a summary block with fields (is_latest, license, published_at, advisory_count, etc.), per-advisory detail, links, and recent alternative versions. It also explains partial failures. This is comprehensive for a tool with 2 parameters.

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

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

Schema coverage is 100% with descriptions. The description adds context beyond the schema: scoped packages are accepted, version defaults to latest, and the composite nature of the tool. This enriches parameter understanding beyond the schema alone.

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

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

The description clearly states it's a composite check for evaluating whether to add an npm package, using deps.dev and bundlephobia. It uses specific verbs ('scan', 'check') and distinguishes itself from sibling tools like 'deep_research' or 'validate_claim'.

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

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

Explicitly states 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also notes NPM ecosystem only and directs users to deps.dev:version directly for other ecosystems, providing clear when-to-use and alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds significant behavioral details beyond annotations: uses BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag, and returns character offsets. No contradictions.

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

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

Description is front-loaded with key action and purpose. Each sentence adds value, but it is somewhat long (several sentences). Still well-structured and efficient, with no redundancy.

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

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

Despite no output schema, the description explains return format: top-N passages with character offsets and similarity scores. Covers limitations (200K char cap, truncation flag). Pairs with sibling tool and provides sufficient context for the agent to understand behavior and output.

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

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

Schema description coverage is 100%, so baseline is 3. The description provides example inputs for 'query' (e.g., 'supply-chain risk') and notes 'text' is previously fetched, but these add minimal meaning beyond the schema's existing descriptions. Does not significantly enhance parameter understanding.

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 'semantic search INSIDE a fetched record', uses specific verb 'search', resource 'record', and distinguishes from siblings like ask_pipeworx_grounded by specifying it works on already fetched text. Provides example use cases (SEC 10-K, article).

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and explains benefit: saves context, returns only relevant passages. Also mentions pairing with ask_pipeworx_grounded for grounding over passages instead of whole document, giving clear when-not and alternative.

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

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

While annotations provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, the description adds behavioral details like requiring OAuth account, returning subscription ID, SMS cap, and webhook auto-disable. However, the idempotentHint annotation conflicts with the 'creates a new subscription' phrasing, which is a 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 detailed but well-structured, with clear sections for type examples and delivery options. It is front-loaded with the main purpose, though slightly verbose in the delivery part.

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 complexity (3 params, nested objects, no output schema), the description covers prerequisites, types, delivery mechanisms, rate limits, and return value. It provides enough context for an agent to use the tool effectively.

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

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

Schema coverage is 100%, but the description adds significant value by providing concrete examples for each subscription type and detailed explanations of delivery fields, including webhook HMAC signing and phone verification requirements.

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

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

The description clearly states the tool creates a proactive monitoring subscription for live-data event streams. It uses specific verbs ('Create') and defines the resource clearly, distinguishing it from sibling tools like list_subscriptions and unsubscribe.

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

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

The description explains when to use the tool (to set up monitoring), lists prerequisites (Pipeworx OAuth account), and implies when not to use (anonymous/BYO cannot persist). It also differentiates by mentioning alternative delivery channels and rate limits.

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. Description adds valuable context: returns category-bucketed example questions with tool+argument shape, and behavior with no arguments vs. topic parameter. 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?

Description is front-loaded with common user questions and well-structured, listing categories in parentheses. It is relatively long but every sentence adds value. Minor improvement possible for conciseness.

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 only one optional parameter and no output schema, the description fully explains purpose, usage, parameters, and expected output. No gaps left for an agent to misunderstand.

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. The description adds further meaning by listing possible topic values (e.g., 'finance', 'pharma') and explaining the effect of omitting the parameter, going beyond the schema.

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

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

Description clearly states the tool's purpose as an onboarding entry point that returns category-bucketed example questions about Pipeworx's capabilities. It starts with common user queries and distinguishes itself from siblings by being the 'first' tool to use when learning what Pipeworx can do.

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

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

Explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Provides guidance on using the optional topic parameter. Does not explicitly mention when not to use, but context is clear enough.

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

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

Beyond annotations, the description discloses ownership enforcement, deactivation vs deletion, and the effect on historical events via recent_alerts. This adds significant value over annotations.

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

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

Two sentences, no fluff, front-loaded with the action. Every sentence provides essential information.

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

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

For a simple cancellation tool with one parameter, the description covers purpose, constraints, and side effects completely. No output schema needed.

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

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

The single parameter 'id' has 100% schema coverage with a clear description. The tool description adds 'by id' but does not add new semantics beyond what the schema provides.

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

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

The description clearly states the action ('Cancel a subscription by id'), specifies the resource ('subscription'), and distinguishes it from sibling tools like 'subscribe' and 'list_subscriptions'. It also adds unique behavioral details like ownership enforcement and deactivation.

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 mentions ownership enforcement ('you can only cancel your own subscriptions'), implying when to use it. It lacks explicit alternatives but the sibling context makes the purpose clear.

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

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

The description adds significant behavioral context beyond the annotations. The crucial disclosure about could_not_verify (that it means the check did not happen, is not evidence, and must not be presented as one) is exactly the kind of nuance an agent needs. It also explains the two internal pipelines (SEC EDGAR/XBRL fast path and grounded fall-through) and the return verdicts.

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

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

The description is longer than average but information-dense, with every section earning its place. It is front-loaded with the most common user intents, and the structure clearly separates purpose, paths, return values, and caveats. Slightly verbose but justified by the tool's complexity.

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

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

Despite lacking an output schema, the description fully specifies expected return values (verdicts, actual value, citation, reasoning) and error semantics. It accounts for the two claim types and provides clear fallback behavior. The description is complete enough for an agent to invoke the tool correctly in a variety of scenarios.

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 enriches the tolerance_pct parameter by explaining its override semantics and hallucination-detection use case, which the schema's generic description does not provide. This added context justifies a 4.

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

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

The description clearly states the tool's purpose: natural-language claim verification. It provides specific example intents ("fact check", "verify the claim that…"), names the resource (authoritative sources), and distinguishes the tool from siblings by explaining its scope (company-financial claims vs. all other factual claims).

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

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

Explicit guidance is given: "Use whenever the agent needs to check whether something a user said is factually correct." It also distinguishes between company-financial claims and other factual claims, and notes that it replaces multi-step sequential calls. However, it does not explicitly name alternative tools or state when not to use it, so it falls slightly 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.