Arcgis Houston

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

Annotations already declare read-only and idempotent behavior, and the description adds valuable context: default free model, external API key pass-through with direct billing, and the return structure of per-model results. It clarifies that Anthropic calls are user-billed, which is critical side-effect information beyond the schema.

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

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

The description is dense but efficient: core purpose first, then model options/cost, output shape, and use cases. Every sentence carries distinct information with no redundancy or fluff.

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

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

Given 100% schema parameter coverage, full annotations, and no output schema, the description covers the essential contract: what it returns, which models are supported, the default behavior, and the external cost implication. No critical gaps for an agent to misuse the tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes further by explaining that omitting 'models' defaults to workers-ai and that supplying an _apiKey incurs direct Anthropic charges — details not fully captured in the schema and valuable for correct invocation.

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

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

The opening sentence uses a specific verb ('Probe') and clear resource (LLMs), defines the output (visibility score 0-100 per model), and distinguishes itself from sibling tools like ask_pipeworx or scan_competitor_ai_presence by focusing on cross-model visibility scoring rather than Q&A or targeted competitor scans.

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 concrete use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and practical instructions on model selection and API key handling. However, it does not explicitly name alternative tools or state when not to use it, so it stops short of full when/when-not guidance.

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

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

Annotations already indicate a non-destructive, read-only, idempotent operation. The description adds meaningful context beyond that: it explicitly states the tool routes questions, fills arguments, and returns answers with stable pipeworx:// citation URIs. This discloses the underlying orchestration behavior without contradicting the annotations.

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

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

The description is moderately long and mostly front-loaded with the most important guidance, but it contains redundancy between 'PREFER OVER WEB SEARCH' and 'even if web search could also answer it.' The final sentence is incomplete ('but if you need...'), which is a structural defect that reduces clarity despite the otherwise organized layout.

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

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

The description adequately covers what the tool does, when to use it, and the general output shape (structured answer with citation URIs). However, with no output schema, more detail about the exact return format would help, and the missing tail referencing alternate tools leaves an open gap about boundaries and fallback behavior.

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

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

Schema coverage is 100%: every parameter is documented with aliases and example values. The description adds example questions that illustrate parameter usage, but these largely mirror the schema's own examples and do not explain any semantics beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly identifies the tool as a question-answering router that forwards queries to 5,710 tools across 1,494 sources and returns cited structured answers. It lists concrete domains and example queries, making the core function unmistakable. However, it does not differentiate from similarly named siblings like ask_pipeworx_grounded or deep_research, leaving potential 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 gives explicit positive guidance: 'PREFER OVER WEB SEARCH' plus trigger phrases ('what is', 'look up', 'find', 'get the latest') and rich examples. It tells the agent when to reach for this tool in most factual queries. But it stops short of exclusions or named alternatives, and the final 'but if you need...' is truncated, so no negative guidance is provided.

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

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

The annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds meaningful behavioral context by disclosing that candidate routing improvements are enabled live when under test, that no candidate is currently active, and that it currently matches ask_pipeworx exactly. This goes beyond what annotations provide.

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

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

The description is front-loaded with the tool's identity and status, and each sentence contributes useful context. The date and tool count add precision, though slightly verbose, but no sentence is wasted.

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

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

For a complex universal router with no output schema, the description provides essential context: identical behavior to ask_pipeworx, same response shape, current experimental status, and usage guidance. It is sufficiently complete, though an agent unfamiliar with ask_pipeworx would still need to inspect that sibling for full output details.

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

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

Schema description coverage is 100%, with the question parameter and all aliases fully described. The description mentions 'same arguments as ask_pipeworx' but does not add new parameter-level meaning beyond the schema, which already carries the load.

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 this as 'Beta version of ask_pipeworx', an identical universal router with the same 5,710 tools, arguments, and response shape. It also distinguishes it from the stable ask_pipeworx by its role as the experimental edge, so an agent can tell what this tool is and how it differs from its sibling.

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

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

It explicitly says to 'Use it exactly like ask_pipeworx when you want the newest routing' and clarifies that this is a full working router with no fallback. However, it does not explicitly state when not to use it versus stable ask_pipeworx or ask_pipeworx_grounded, leaving some 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?

The description adds substantial behavioral context beyond the annotations: it contracts to only use tool-result content, returns a refusal with specific reasons when no direct answer exists, and documents an extra LLM-call cost. This is exactly the kind of disclosure that helps an agent predict behavior. No contradiction with readOnlyHint/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 dense and front-loaded with the core purpose. Every sentence contributes: behavior, return contract, use cases, and cost tradeoff. The 'same routing' enumeration is slightly redundant with the named sibling, but it does clarify scope. Slightly longer than necessary, yet all content is useful.

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 documents the success return shape and all refusal reasons. It covers when to use, when not to use, cost implications, and behavioral guarantees. Parameters are fully covered by the schema, so nothing critical is missing.

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

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

Schema description coverage is 100%, and the schema already documents mode and question including aliases. The tool description does not add parameter-level guidance, which is acceptable given full schema coverage. This meets the baseline but does not exceed it.

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

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

The description clearly identifies a specific verb and resource: a hallucination-resistant grounded answer mode for high-stakes reads. It distinguishes itself from the sibling ask_pipeworx by stating that answers are extracted only from tool results and that it returns evidence/refusals. This makes the tool's purpose and its difference from siblings explicit.

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

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

Usage is explicitly scoped: use when answers will be quoted, cited, or acted on, with concrete domains (financial, legal, medical, public statements). It also states the tradeoff — costs one extra LLM call — and advises preferring ask_pipeworx for casual lookups. This is model-ready routing guidance.

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

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

Beyond the readOnlyHint/idempotentHint annotations, the description discloses behavioral details like parallel fan-out, low-confidence short-circuiting, blocked statuses for closed markets, illiquid spread warnings, and the resolution-rule risk with flat-50¢ settlements. No contradiction with annotations.

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

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

The description is long but well-structured with labeled sections (RESPONSE SHAPES, RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, NEWS FIELDS, SAFETY, RESOLUTION-RULE RISK). Each section provides necessary operational detail absent an output schema, and the description is front-loaded with the core purpose and usage.

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 must carry the full burden of return-value semantics. It defines result.market fields, result.analysis fields, evidence keys, resolver contract fields, parent_event object, news fallback flags, status strings, and cancellation-rule parsing—covering all essential contexts for safe and effective 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?

With 100% schema coverage, the schema already defines all parameters. The description adds meaningful context for 'market' (slug/URL/question variants) and include_raw (summary vs 50KB-500KB payloads), but does not elaborate on the 'depth' parameter beyond the schema, so it is above baseline but not maximal.

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

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

The description opens with a specific verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly differentiates from sibling tools like polymarket_arbitrage or polymarket_edges by focusing on research and evidence gathering rather than arbitrage or edge scanning.

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 use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also covers blocking paths and when to inspect resolver fields, but it does not explicitly name alternative sibling tools or state when not to use this tool.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) already indicate a safe, non-destructive operation, and the description adds rich behavioral context: parallel execution, data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, metric-based sorting, and citation URI returns. No contradiction with annotations exists.

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

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

The description is long but every clause serves a purpose: trigger examples, use-case priority, type-specific data details, sorting behavior, and return format. It is front-loaded with the most critical usage cues, though slightly dense; trimming repetitive examples could improve efficiency without losing value.

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

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

With no output schema present, the description sufficiently explains what the tool returns (paired data + citation URIs) and covers all key behavioral aspects: scope, data sources, sorting, and efficiency gains. Given the 2-parameter simplicity and robust annotation support, the description is complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100% for the two parameters, and the description enriches both: it explains 'company' pulls financial data and 'drug' pulls adverse-event/trial data, and specifies value formats (tickers/CIKs for company, names for drug). This goes beyond the schema's basic descriptions and ensures correct invocation.

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

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

The description explicitly states the tool performs side-by-side comparisons of 2–5 companies or drugs in one parallel call, using clear verbs like 'compare' and providing trigger phrases. It distinguishes itself from single-entity lookups by emphasizing it replaces 8–15 sequential queries, making its purpose and scope unmistakable.

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

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

The description provides explicit when-to-use guidance with concrete user phrasings (e.g., 'X vs Y', 'which is bigger', 'rank these companies') and instructs to always prefer this tool over sequential single-pack lookups when comparing entities. It also clarifies the two type-specific data sources, aiding correct selection.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds materially: requires sign-in, has rate limits, 'never invented' answers with explicit gaps[], stable pipeworx:// citations, and structured-data-only scope. 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 but front-loaded with the most important requirement (ACCOUNT REQUIRED) and packed with useful detail; almost every sentence earns its place. It loses a point for ending with an incomplete 'and…' clause and for slightly repeating the ask_pipeworx fallback.

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, and the description compensates by spelling out the findings packet (verbatim evidence, confidence, source, fetched_at, citation, gaps[]) and the no-invention guarantee. Coverage of auth, limits, alternatives, and use cases is strong, though the truncated final sentence leaves a small 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 coverage is 100%, and both `question` and `depth` are clearly described in the input schema, so the description does not need to repeat parameter syntax. It adds plan-level context (thorough requires paid; free limited to quick/standard), which is useful but not a semantic explanation of the parameters themselves. Baseline 3 applies.

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

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

The description names a specific operation ('Grounded multi-source research... in ONE call') and resource ('Pipeworx's 1494 STRUCTURED data sources'), and explicitly contrasts itself with open-web search. It also differentiates from siblings by saying 'For a single lookup use ask_pipeworx instead', so an agent can tell when this tool applies.

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

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

It gives explicit when-to-use conditions: 'Best for broad/multi-part questions over structured data' with concrete examples, and gives two exclusion rules for ask_pipeworx (not signed in, single lookup). It also states account/plan limits (free quick+standard only, paid thorough), which prevents selecting the wrong depth before calling.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds valuable behavioral context beyond that by disclosing the return format ('top-N most relevant tools with names, descriptions, and full input schemas') and the promise that results are 'ready to call directly, no second schema lookup needed.' This is credible and goes beyond the structured annotations.

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

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

The description is front-loaded with the core purpose and is wrapped in two sentences. The long list of domains is somewhat verbose but earns its place by indicating the tool's breadth. No redundancy with the schema; all sentences contribute meaning.

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

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

For a tool-discovery tool with no output schema, the description fully covers the return contract (tools with names, descriptions, full schemas, curated examples) and instructs the agent to use it as a first step in multi-tool environments. It explains the key guarantee ('ready to call directly') which is essential for agent decision-making.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces that the primary input is a natural-language query ('describing the data or task') and mentions 'top-N' but does not elaborate on the 'limit' parameter beyond what the schema already specifies. The description adds marginal semantic value over 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 uses a specific verb+resource construction ('Find tools by describing the data or task') immediately clarifying this is a tool-discovery utility. It also enumerates a broad domain list (SEC filings, FDA drugs, FRED, etc.), distinguishing it from sibling tools like search_datasets which operate on data rather than the tools themselves.

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 when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear context and implies contrast with tools that return direct answers, covering both usage and exclusion guidance.

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

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

Annotations already declare readOnlyHint true and destructiveHint false, but the description adds substantial behavioral context: it fans out across multiple named sources, returns specific fields, soft-fails for patents after API sunset, and uses a GDELT→GNews fallback. This far exceeds the structured annotations and prepares the agent for 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?

Despite being long, every sentence earns its place: it first lists user intents, then the core action, then the preferential use case, then the detailed output components, and finally the parameter constraint. There is no filler or redundancy beyond the slight repetition of the parameter rule, which itself is concise and useful.

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 multi-source tool with no output schema, but the description compensates by enumerating exactly what is returned (cik, recent_filings with URIs, fundamentals, patents, news, LEI). It also covers edge cases like patent API sunset and name-based requests, making the tool fully usable without additional investigation.

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

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

The input schema already provides 100% description coverage for both parameters, including the exact instruction that value accepts a ticker or zero-padded CIK and that names are unsupported. The description repeats this same information in its final sentence, adding no new meaning beyond what the schema already documents.

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 intents and explicitly states 'full cross-source profile of a US public company in ONE parallel call', making the tool's purpose unmistakable. It distinguishes itself from siblings like compare_entities and resolve_entity by focusing on a holistic single-entity view.

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

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

It provides explicit when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also names the alternative for name-only inputs: 'use resolve_entity first if you only have a name', which effectively excludes inappropriate uses.

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

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

Annotations already declare destructiveHint and idempotentHint; description adds context about clearing sensitive data but doesn't disclose behavior for missing keys or side effects beyond what annotations imply.

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

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

Two sentences with no waste; the first states the core action, the second provides usage guidance.

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

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

Simple tool with one param, clear annotations, and description covers purpose and use cases; 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?

Schema coverage is 100% with clear description ('Memory key to delete'); tool description adds no additional parameter meaning beyond that baseline.

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

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

Description uses a specific verb 'Delete' and resource 'previously stored memory by key,' clearly distinguishing from sibling tools like remember and recall.

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

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

Explicitly states when to use ('context is stale, task is done, or clear sensitive data') and pairs with remember and recall, though it doesn't explicitly exclude alternatives.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the description adds value by disclosing the internal process: fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. It also clarifies the output form ('single text blob'), though it omits failure modes or edge cases.

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

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

The description is tightly written: a single opening sentence, a brief process sentence, and a succinct 'Useful for' list. Every sentence contributes meaning, and the structure front-loads the core action.

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 two-parameter, no-output-schema tool, the description covers purpose, process, output format, and typical use cases. It lacks details on error behavior or site accessibility, but given the simplicity and strong annotations, this is adequate and close to complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minimal parameter-specific meaning beyond the schema, only indirectly referencing 'key links' and output format. It does not elaborate on 'max_links' beyond what the schema already says.

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

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

The description uses a specific verb ('Generate') and resource ('llms.txt file for any URL'), clearly stating what the tool does. It distinguishes itself from sibling tools like 'ai_visibility_check' and 'scan_competitor_ai_presence' by focusing on file generation rather than analysis, and its 'Useful for' list reinforces its distinct purpose.

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

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

The description provides clear usage context with a 'Useful for' list (client indexing, own project drafting, competitor auditing), which covers when to use it. It does not explicitly mention exclusions or alternatives, but the tool's unique niche among siblings makes the guidance largely sufficient.

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

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

Annotations already disclose readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context about what is retrieved (fields, geometry, record count, capabilities) and that it operates 'by url', but it does not go beyond that. 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 a single sentence that front-loads the verb and resource, and each word adds value. No filler or redundant information.

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

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

For a simple tool with one parameter and no output schema, the description adequately lists all return components (fields, geometry type, record count, capabilities). It is missing potential caveats like URL format validation or error behavior, but these are not critical for the core 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?

Schema description coverage is 100%, so the baseline is 3. The description reinforces that the url parameter is for the layer endpoint and clarifies the output that depends on it, but does not add extra syntax or format details beyond the existing parameter description.

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

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

The description uses a specific verb ('Get') and resource ('ArcGIS Feature/Map Service layer's schema'), and lists exact outputs: fields (name + type), geometry type, total record count, and capabilities. This clearly distinguishes it from sibling tools like query_layer or search_within.

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 schema inspection ('Get an ArcGIS layer's schema'), but it does not explicitly mention when to use this tool versus alternatives (e.g., query_layer). No exclusions or when-not-to-use guidance are given, so it remains at an implied level.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable context that it scopes to the caller's subscriptions and returns specific fields, which are not conveyed by 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: the first states what the tool does and returns, the second provides practical usage guidance. Every word earns its place 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?

For a simple read-only list tool with a single optional parameter, the description covers purpose, return fields, and usage scenarios. Annotations and schema fill in the remaining details, making the tool fully understood.

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

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

Schema coverage is 100% for the single parameter 'include_inactive', so the description does not need to explain it further. The description adds no additional parameter meaning, but the schema already provides sufficient detail.

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

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

The description clearly states the action ('List') and specific resource ('the caller's active subscriptions'), and enumerates the returned fields. It is unambiguous and distinct from sibling tools like subscribe/unsubscribe.

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

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

Provides explicit use cases ('review what you're monitoring before adding more' and 'find an id to cancel'), giving clear context for when to use the tool. However, it does not explicitly name alternatives or exclusionary conditions.

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

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

The description discloses behaviors beyond annotations: rate limiting (5 per identifier per day), that it's free and doesn't count against quota, and the claim_token flow for status checks. It also notes that the team reads digests daily and signal affects roadmap. No contradiction with the provided annotations.

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

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

The description is long but every sentence earns its place, covering purpose, usage boundaries, content guidance, token mechanics, and rate limits. It is logically organized and front-loaded with the core purpose. No fluff or repetition.

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

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

For a feedback tool with no output schema, the description covers all necessary context: what to report, what not to report, how to follow up, rate limits, and roadmap impact. The claim_token workflow is fully explained, making the tool self-contained for an agent.

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

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

Schema coverage is 100%, but the description adds significant meaning to parameters: it explains how to use claim_token (pass it back with no other arguments), what message should contain (specific, 1-2 sentences, max 2000 chars), and that context should reference Pipeworx tools/packs. This goes well beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: to tell the Pipeworx team about broken, missing, or desired functionality. It distinguishes itself from siblings by specifying it is only for tools served by this Pipeworx connection, not other MCP servers. The use cases (bug, feature, data_gap, praise) are explicitly listed.

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

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

The description provides explicit when-to-use guidance (bug, feature, praise) and when-not-to-use (tools from other MCP servers), including an alternative action (file with that server). It also explains how to frame feedback (in terms of Pipeworx tools/packs, not end-user prompts) and how to follow up with a claim_token.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context: data provenance ('derived from CF analytics-engine'), privacy ('no PII'), and caching ('Cached 5min-1h depending on window'), which are not evident from annotations.

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

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

The description is well-structured with a one-sentence summary followed by a concise use-case list and a technical note. It is front-loaded with the core purpose and every sentence adds value without redundancy.

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

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

For a simple one-parameter tool with no output schema, the description provides enough detail: what is returned, the data shape ((pack, tool, count)), the caching behavior, and the intended use cases. It fully covers the tool's operation and limitations.

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

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

The schema fully covers the 'window' parameter with an enum and description. The description further explains that shorter windows surface 'what's hot right now' while longer windows show 'steady-state demand', adding semantic nuance beyond the basic 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 tool returns top tools, top packs, and total call volume over a recent window, using specific verbs and resources. It distinguishes itself from siblings like discover_tools and ask_pipeworx by focusing on aggregated trending usage 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?

The description provides three explicit use cases (discovering hot data sources, confirming canonical choices, checking alignment with agent needs), giving clear context for when to use it. It stops short of naming alternatives or stating when not to use it, so it doesn't quite reach a 5.

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

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

Annotations already declare the tool read-only, idempotent, and non-destructive, and the description adds substantial context: partition filters, semantic similarity thresholds, placeholder filtering, and the fill check warning not to trade when realizable edge ≤ 0. 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 dense but well-structured, with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded core purpose and mode selection. Every sentence contributes value, and the length is justified by the tool's complexity.

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

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

With no output schema, the description compensates by thoroughly explaining the response structure (opportunities[] and partition_check fields), covering request modes, filters, thresholds, and the fill check. It even points to a related tool for custom sizing, making it remarkably complete.

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

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

The input schema already has 100% description coverage for event and topic, but the tool description goes further by providing concrete slug examples and explaining how each parameter changes the scan behavior. This adds significant 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 explicitly states the tool finds arbitrage opportunities on Polymarket using monotonicity violations and partition-sum checks, with a clear verb and resource. It further distinguishes three modes (no-arg trending_scan, event, topic), setting it apart from sibling tools like polymarket_edges.

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

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

It provides explicit when-to-use guidance for each mode, including no-args for a trending scan, event for a specific market, and topic for cross-event scanning. It also gives a clear alternative by directing users to polymarket_fill_risk for custom sizing, making both when and when-not-to-use explicit.

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

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

The description goes far beyond the annotations, detailing response structure (by_segment, fed_candidates, _diagnostics), per-opportunity fields (edge_pp_net, kelly_fraction, etc.), the 24h-move warning, gate thresholds, and even caching behavior ('Cached 1h at the KV level keyed on all knobs'). This gives an agent a thorough understanding of what the tool does and what to expect.

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

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

The description is one long, dense block of text with extensive details (per-sport α values, gate thresholds, funnel counters). While the information is valuable, it is not concise and is difficult to parse quickly. The lack of paragraphs or bullet points makes it overwhelming; a more structured layout would be far more 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?

Since there is no output schema, the description carries the full burden of explaining return values. It thoroughly covers the response structure (by_segment, fed_candidates, _diagnostics) and per-opportunity fields, and explains how parameters affect the output. The detail is sufficient for an agent to understand what the tool returns and how to use it.

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

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

With 100% schema coverage, the baseline is 3. The description adds meaningful parameter semantics by explaining how knobs interact (e.g., 'min_liquidity / max_spread_pp drop opportunities where edge isn't realizable') and clarifying exceptions (e.g., 'min_kelly never filters partition arbs; min_partition_leg_kelly applies per-leg instead'). This extra context raises the score.

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

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

The description opens with a specific verb-resource pair: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also states the intended use case ('Built for "what should I bet on today"'), making the tool's purpose unmistakable and distinguishing it from generic market data tools. The scope is clear without needing to reference siblings.

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

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

The description provides clear use context: 'agents discover opportunities without paging hundreds of markets' and explains what the tool is for. However, it does not explicitly name alternative tools or state when not to use this tool, so it falls short of a 5.

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

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

Annotations already mark it as read-only and idempotent, and the description adds substantial detail: snapshot source, TTL limits, data gaps when snapshots aren't written, computation basis (daily closes, not intraday), and the signed/directional meaning of edge_pp_net. 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-organized into purpose, arguments, response format, and limitations. Despite its length, every sentence provides unique value, especially the detailed breakdown of the response fields. It is front-loaded with the core question it answers, making it efficient.

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

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

For a tool with no output schema, this description fully documents the response structure (tracked[], expired[], snapshot_dates[]), including the meaning of fields and edge cases like snapshot gaps and TTL limits. No significant gaps remain, making it complete for an agent to invoke and interpret results correctly.

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

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

The schema covers both parameters 100%, so the baseline is 3. The description adds defaults and clarifies days is lookback and window is snapshot family, but these details already exist in the schema. No additional semantics or interaction details are provided beyond the schema's own descriptions.

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

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

The description clearly states the tool's role: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question ('how long has this edge existed and is it shrinking?') and distinguishes itself from siblings like polymarket_edges by focusing on historical persistence rather than current edges.

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

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

It provides clear context for when to use the tool (when you need edge persistence/decay history) and explains why fresh vs old edges matter in decision-making. However, it does not explicitly name alternative tools for other cases, such as 'use polymarket_edges for current edges,' so it lacks explicit exclusions.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, and the description adds materially by explaining that it 'walks the ladder', returns a clean/degraded/cannot_fill verdict, and is a pre-trade simulation rather than an execution. No contradiction exists between annotations and description, and the description gives meaningful context about live order-book depth and basket-fill pitfalls.

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 front-loaded with purpose and every clause adds mode-specific behavior, output fields, or usage caveats. It loses one point for being a single run-on paragraph that could benefit from short bullet-style separation, but it is not wasteful.

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

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

There is no output schema, yet the description enumerates all returned values for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, plus basket-specific fields like capture_ratio, profit_usd, thin_legs, max_clean_notional_usd, forced_directional_risk). It also covers defaults, constraints, and risk rationale, so an agent has enough context to invoke and interpret the tool correctly.

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

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

Schema coverage is 100%, and the description goes beyond it by explaining the mutually exclusive market/event modes, the meaning of side in each mode, and the different interpretation of size_usd (spend/proceeds for single-market vs settlement notional for basket). It also clarifies defaults and clamps, so parameter semantics are fully enriched.

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

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

The description opens with a specific verb-and-resource statement ('Realizable-vs-theoretical edge check against live CLOB order-book depth') and then distinguishes two modes (single-market vs basket), clearly separating this fill-risk checker from sibling polymarket tools. It states exactly what it returns (top_of_book, vwap_fill_price, slippage_pp, verdict) and even names the intended usage before acting on arbitrage/edge 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?

The description explicitly tells the agent when to use it: before any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or polymarket_edges trade above ~$500. It also gives mode-selection guidance (market vs event) and explains why (theoretical overround on thin books is not capturable; partial basket fills create unhedged directional risk).

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

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

Annotations already mark this as read-only, idempotent, open-world, and non-destructive. Beyond that, the description discloses rich behavioral details: compatibility codes, skipped unclassified legs, low-confidence pairs, temporal alignment, per-spread flags, and the fact that topic-mode pairings are keyword-matched rather than resolution-source matched. This materially improves trust calibration.

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

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

The description is long, but it is organized into labeled sections and front-loaded with purpose. Given the complexity of the response fields, safety codes, and edge cases, most sentences justify their place; a slightly tighter presentation would improve 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?

There is no output schema, so the description carries the full burden of explaining response shape and quality caveats. It covers response fields, compatibility codes, skipped comparisons, temporal alignment, counters, and the rare reliability of pre-mapped spreads. An agent has enough information to call the tool correctly and interpret results cautiously.

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

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

Schema description coverage is 100%, so the schema already documents the three parameters. The description adds value by explaining that topic auto-fetches matching events on both venues, that explicit ticker/slug values override the topic-mapped side, and by providing concrete examples. This is more than the schema alone 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 names a precise resource: a cross-venue spread between Kalshi and Polymarket for the same resolving question, and clearly distinguishes two modes of invocation. It is specific enough that an agent can tell what the tool computes, though it does not explicitly differentiate itself from sibling tools like polymarket_arbitrage or compare_entities.

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

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

It clearly explains when to use the topic shortcuts versus explicit ticker/slug pairs, and provides crucial cautions: most pre-mapped topics return compatibility_warning today, and pre-mapped does not mean tradeable. It does not explicitly state when to prefer a sibling tool, so it falls just short of a perfect usage-guideline score.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral context by stating that it returns attribute rows and geometry, and the sampling hint clarifies how to make safe exploratory queries. No contradiction with annotations.

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

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

Two sentences, front-loaded with the core purpose and parameter list, followed by a practical usage tip. Every clause adds value; 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 no output schema, the description still communicates the return shape (attribute rows and geometry), covers pagination via offset/limit, filtering via where, and field selection via out_fields. Combined with the rich schema examples, it provides enough context to invoke correctly.

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

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

The input schema covers all six parameters with descriptions and examples (100% coverage). The description reinforces the SQL-like semantics and the out_fields concept but adds little beyond the schema's own parameter explanations, so a baseline of 3 is appropriate.

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

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

The description clearly states it queries an ArcGIS Feature/Map Service layer by URL, with a specific list of SQL-like query parameters. This distinguishes it from sibling tools like layer_info (likely metadata) and search_within (searching data) by naming the exact resource and operation.

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

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

It explicitly references that the URL comes from search_datasets and gives a concrete sampling pattern ('where=1=1 + out_fields="*"'). This provides clear usage context, though it does not explicitly contrast with sibling tools like layer_info.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false. The description adds the scoping detail ('Scoped to your identifier') and the dual-mode behavior based on optional key, which are useful beyond annotations. It doesn't mention return format or missing-key behavior, but that's minor given the simple read-only nature.

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

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

Two sentences, front-loaded with the action, no redundant words. Each sentence adds value: the first explains the operation, the second provides context and related tools.

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 optional-key read tool with strong annotations, the description covers purpose, scoping, and related tools. No output schema is needed because the return value is implied. Complete enough for an agent to select and invoke correctly.

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

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

Schema coverage is 100% (the only param `key` is described as 'Memory key to retrieve (omit to list all keys)'). The description repeats this same info and adds no new parameter-level detail, so baseline 3 applies.

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

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

The description opens with 'Retrieve a value previously saved via remember, or list all saved keys' — a specific verb with a clear resource, and explicitly distinguishes the listing mode. It also names sibling tools remember and forget, making scope clear and distinguishing from alternatives.

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

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

Explicitly says 'Use to look up context the agent stored earlier... without re-deriving it from scratch', and pairs with remember to save and forget to delete, which guides when to use this vs alternatives. This is clear usage guidance with explicit sibling references.

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

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

The description discloses that setting mark_read:true will flag events as read, which is a state mutation, contradicting the readOnlyHint annotation. The annotation suggests the tool is read-only, but the description reveals an optional write side effect. This is a direct contradiction, so the score is 1 with annotation_contradiction flagged.

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

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

The description is four sentences, front-loaded with the core purpose. It includes useful details like polling and the HTTP endpoint without excessive verbosity. The structure flows logically from main function to return format to filtering to side-effect behavior.

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

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

With no output schema, the description adequately covers return values. It mentions the source of alerts (evaluator), the persisted feed, filtering options, mark_read side effects, and an alternative access point. Combined with annotations indicating read-only/idempotent behavior, it is reasonably complete, though it could clarify unread_only semantics more.

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

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

Although schema coverage is 100%, the description adds semantic value by explaining return fields (source, citation_uri, raw event payload), illustrating the type filter with an example ('sec_8k'), and clarifying mark_read behavior ('next call only shows newer ones'). This goes beyond the schema's bare 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 pulls fired events from the subscription feed, with a specific verb ('Pull') and resource ('fired events from your subscription feed'). It distinguishes itself from siblings like list_subscriptions and recent_changes by focusing on alert events with source, citation_uri, and payload details.

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

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

The description provides clear usage context: it mentions filtering by type and since, polling behavior, and an alternative access method (GET registry.pipeworx.io/alerts.json) for scripts/dashboards. It doesn't explicitly state when NOT to use this tool versus alternatives, but the context is sufficient for a basic understanding.

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 beyond the readOnly/openWorld/idempotent annotations by revealing the internal fan-out behavior: the GDELT→GNews fallback when rate-limited or 5xx, and the USPTO/PatentsView API sunset causing a soft-fail. It also describes the return structure (changes[], total_changes, pipeworx:// citation URIs), adding significant behavioral context.

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

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

The description is a dense single paragraph that packs in query triggers, source fallbacks, parameter syntax, return format, and an alternative tool. Every sentence earns its place, though it would benefit from line breaks or bullets for easier scanning. Still, the length is appropriate for the tool's complexity.

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

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

With no output schema, the description carries the burden of explaining return values, which it does ('structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs'). It also covers failure modes (PatentsView sunset), fallback behavior, and the alternative tool, making it highly complete for an agent to select and invoke correctly.

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

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

The schema provides 100% coverage of the three parameters, so the baseline is 3. The description adds meaning by explaining the `since` format (ISO date or relative shorthand) and recommending a typical window ('30d' or '1m'). It also clarifies that `value` accepts a ticker or CIK, reinforcing the schema. This extra usage guidance nudges the score to 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 defines the tool as a 'change feed for a company in the last N days/weeks/months' and enumerates specific sources (SEC EDGAR, GDELT/GNews, USPTO). It also distinguishes itself from the sibling tool entity_profile, which retrieves static profiles, making the purpose unmistakable.

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

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

The description opens with natural-language query examples ('What's new with X', 'latest on Y', 'what happened to Z this week / month / quarter') and explicitly states when to use entity_profile instead. It also gives parameter usage guidance (e.g., 'Use "30d" or "1m" for typical monitoring'), providing clear contextual instructions.

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 a write operation (readOnlyHint=false) and idempotent behavior. The description adds valuable context about memory scoping (by identifier) and persistence (persistent for authenticated users, 24 hours for anonymous), which goes beyond the structured fields.

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 purpose, and every sentence provides useful information. No fluff or repetition of schema details.

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

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

For a simple two-parameter save tool, the description covers purpose, usage, persistence, and pairing with sibling tools. No output schema is needed for a write operation, and the context is complete.

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

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

Schema coverage is 100% with clear descriptions and examples for both key and value. The description adds general examples of what to store but doesn't substantially extend the schema's parameter meanings, so baseline 3 is appropriate.

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

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

The description clearly states the tool saves data for reuse across conversations or sessions, using specific verbs and resources. It distinguishes itself from siblings like recall and forget by explicitly naming 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?

Provides explicit when-to-use guidance with concrete examples (resolved ticker, target address, user preference) and names alternatives (recall, forget). This helps the agent select the correct tool.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds significant behavioral detail: internal cascading through multiple lookup endpoints, graceful degradation (if GLEIF/OpenFIGI unavailable, EDGAR identifiers still return), explicit handling of unresolved identifiers (listed under 'unresolved'), and labeling of identifiers with their source. 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 long (three paragraphs) but every sentence adds unique value. It is front-loaded with query examples and usage guidance, then details each entity type. While it could be slightly more concise, the density of information justifies the length. 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?

There is no output schema, so the description must cover return values and behavior. It clearly explains what identifiers are returned for each type (company: CIK, ticker, LEI, FIGI, unresolved; drug: RxCUI, ingredient, brand, citation). It covers edge cases (unresolved identifiers, graceful degradation, ISIN-to-LEI mapping). Given the complexity, this is highly 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. The description adds substantial meaning: for 'type' it elaborates on the company identity spine (CIK, ticker, LEI, FIGI, with sources) and drug type (RxNorn mapping). For 'value' it provides concrete examples (AAPL, 0000320193, ozempic) and explains acceptable formats (ticker, CIK, ISIN, name). This goes well beyond the schema.

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

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

The description clearly states the tool resolves user-spoken names to canonical/official identifiers, gives multiple query examples (ticker, CIK, LEI, RxCUI), and explicitly advises 'Use FIRST whenever you have a name but need an ID.' This distinguishes it from siblings like entity_profile or compare_entities by focusing on name-to-ID conversion.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' providing strong usage context. It gives concrete query patterns and supported entity types (company, drug). However, it does not explicitly list when not to use this tool or mention alternative tools for other 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, idempotentHint, etc. The description adds beyond this by explaining the probe mechanism ('Probes each entity... with ai_visibility_check') and the return format ('ranked list with score, confidence, signal density per entity'). This provides useful context beyond the structured flags.

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

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

Three sentences, front-loaded with the core action, followed by method and use case. No redundant phrases; every sentence earns its place.

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

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

No output schema exists, but the description compensates by detailing the return structure (score, confidence, signal density). It also covers the use case and algorithm. Minor gaps like configurable models are addressed in the schema, so the description 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 description coverage is 100% for all parameters, so baseline is 3. The description reinforces the first-entity-as-subject concept but adds little beyond the schema's parameter descriptions. It does not introduce new parameter-specific meaning.

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

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

The description clearly states the tool's function: 'Compare AI visibility across multiple entities side-by-side' and 'ranks by score, surfaces which is most/least recognized.' It differentiates from sibling ai_visibility_check by emphasizing multiple entities and side-by-side comparison.

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

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

Provides clear context: 'Useful for competitive AI-marketing audits' with an example. It names the underlying tool (ai_visibility_check) and implies when to use this wrapper, but does not explicitly state when not to use alternatives or name exclusion 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 declare readOnly/idempotent, and the description adds substantial behavior: it fans out to two external services, explains partial failures with a 5-30s window for bundlephobia's first measurement, and notes sources_failed reporting. No contradiction with annotations.

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

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

The description is dense but well-structured, starting with the composite purpose, then usage, return fields, ecosystem constraint, and failure behavior. The list of return field names is necessary since there's no output schema, but the length is slightly above the ideal minimal; still, every sentence earns its place.

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

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

For a complex composite tool with no output schema, the description fully covers return values, failure modes, latency expectations, and ecosystem limitations. It even names the alternative tool for non-NPM cases, making the description self-contained.

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 has 100% coverage with clear descriptions for both 'package' and 'version', so the description doesn't need to add parameter details. The main description adds context about the return behavior but not new parameter semantics, fitting the baseline of 3 for high schema coverage.

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

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

The description clearly defines the tool as a composite check for 'should I add this npm package to my project' that fans out across deps.dev and bundlephobia. It distinguishes from siblings by specifying NPM-only scope and naming deps.dev:version as the alternative for other ecosystems.

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

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

It explicitly states when to use: 'Use whenever an agent asks is X safe / popular / small' or 'what does adding lodash cost me'. It also provides an exclusion: non-NPM ecosystems fall under deps.dev:version directly, guiding the agent to an 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering safety. The description adds value by detailing the return contents (name, summary, record_count, owner/org, url) and how to use the url with other tools. This goes beyond what annotations provide and does not contradict them.

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

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

Two sentences: the first sets scope and action, the second lists return fields and downstream usage. Every sentence earns its place with no wasted words.

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

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

With no output schema, the description compensates by explicitly listing return fields and pointing to query_layer/layer_info for next steps. Annotations cover safety and schema covers parameters, so this description is complete enough for an agent to decide when to use it and what to do with the result.

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 does not add parameter-level details beyond the schema, but it does contextualize 'query' as a keyword search and the overall purpose. Since the schema already documents query, limit, and org_id fully, the description's contribution here is minimal.

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

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

The description clearly states a specific action ('Search') and resource ('City of Houston GIS open geospatial datasets'), with examples of dataset types. It also distinguishes itself from siblings by explaining that the output includes a Feature Service url to be passed to query_layer/layer_info.

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 when to use this tool: to discover datasets by keyword before querying them. It explicitly mentions downstream tools query_layer and layer_info, giving context on how to use the result. However, it doesn't explicitly state when not to use it or alternative search methods, so it's not a full 5.

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

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

The description adds rich behavioral details beyond annotations: BGE-base-en embeddings, 500-character overlapping windows, 200K character cap with truncation flag, and that every passage includes character offsets and similarity scores. No contradictions with readOnly/openWorld/idempotent hints.

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

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

The description is information-dense but every sentence adds value: core functionality, use case, pairing with sibling, implementation details, and limitations. It is well-structured, front-loaded with the action, and not overly verbose.

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

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

With no output schema, the description explains return values (passages with offsets and similarity scores), limitations (truncation), and pairing with sibling tools. It gives enough context for an agent to decide when and how to invoke the tool.

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

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

Input schema already provides 100% coverage with descriptions for text (incl. max length), limit (1-20, default 5), and query (with examples). The description mostly reinforces schema semantics and adds minimal extra meaning, so baseline 3 is appropriate.

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

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

Description clearly states the tool performs semantic search inside a fetched record, distinguishing it from siblings by emphasizing it works on text already pulled, with passages and offsets. It also differentiates from ask_pipeworx_grounded by its focus on local search within a single document.

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 the record is too big for the prompt. It also explains how it pairs with ask_pipeworx_grounded and why this is better than grounding over the whole document, giving clear context and an 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?

Annotations state readOnlyHint=false, idempotentHint=true, and destructiveHint=false, and the description adds substantial context without contradiction. It discloses side effects (returns subscription id, auto-disables webhook after 10 failures), prerequisites (verified phone, OAuth account), and delivery behavior (feed always on).

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

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

The description is long but densely packed with necessary details, examples, and constraints. It is front-loaded with the core purpose and returns value, though it could be broken into clearer sections for scannability.

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 covers the return value (new subscription id, webhook secret), prerequisites, all parameter variants, delivery options, and fallback behavior. It is complete for a moderately complex subscription tool with nested 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%, and the description adds rich meaning beyond the schema: concrete examples for each type (e.g., sec_8k with items:['5.02']), delivery constraints (E.164, verified phone, 10/day cap), and webhook signing details. This far exceeds the baseline.

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

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

The description opens with a specific verb and resource: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly distinguishes itself from siblings like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation and including explicit subscription types.

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

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

The description gives clear context for use, including supported subscription types, required OAuth account, and delivery channels. It names an alternative for consuming alerts ('pull via recent_alerts') but does not explicitly state when *not* to use subscribe; still, the guidance is strong.

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

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

Annotations already indicate a safe, read-only, idempotent operation. The description goes beyond by detailing the return structure (category-bucketed example questions with exact tool + argument shape), the 'live catalog' aspect, and the effect of optional topic filtering, giving a clear mental model of tool behavior.

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

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

The description is dense but organized: it opens with illustrative queries, then explains the output, parameter behavior, and usage priority. While lengthy, each sentence contributes unique information; only the long category list could be trimmed without losing much.

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

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

With no output schema, the description adequately explains what is returned (category-bucketed example questions with tool/argument shapes). It covers invocation modes, parameter semantics, and the intended use case, making the tool self-sufficient 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 a thorough description of the optional `topic` parameter. The tool description adds example values ('finance', 'pharma', 'betting') and clarifies the omit behavior ('full spread'), reinforcing the schema without duplicating it entirely.

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

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

The description clearly identifies the tool as the onboarding entry point for discovering what Pipeworx can do, distinguishing it from siblings like discover_tools and ask_pipeworx. It specifies the verb (suggest questions), the target resource (Pipeworx capabilities), and the output (category-bucketed example questions with tool/argument shapes).

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 instructions: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Also gives concrete example queries and explains when to omit or pass the `topic` parameter, offering clear context for selection.

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

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

Beyond the annotations, the description discloses that ownership is enforced, the row is deactivated (soft delete) rather than deleted, and historical events remain available via recent_alerts. These details are not present in the annotations and give important behavioral context for a mutation tool.

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

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

Three sentences, each contributing unique value: core action, ownership rule, and post-cancellation behavior. No superfluous wording, and the most important information is front-loaded.

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

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

For a single-parameter mutation tool with rich annotations and full schema coverage, this description is complete. It states what happens to the data and where historical events can be accessed, leaving no essential ambiguity for an agent invoking the tool.

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

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

The schema already fully describes id as a subscription uuid returned by subscribe. The description adds behavioral context—ownership enforcement and soft-delete—which enriches the meaning of the parameter beyond a simple identifier.

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 'Cancel a subscription by id,' a specific verb and resource, clearly distinguishing it from siblings like subscribe and list_subscriptions. It also specifies the ownership constraint, which clarifies the exact scope of the operation.

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

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

The description provides clear context: you can cancel only your own subscriptions, implying you shouldn't use it for others' subscriptions. It indirectly signals using recent_alerts for historical events, but it does not explicitly name alternatives or provide a when-not-to-use clause beyond the ownership rule.

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, but the description goes well beyond these by explaining the return verdict types, the critical distinction between 'could_not_verify' (check did not happen, not evidence) and 'unsupported' (no source covers it), the SEC vs. grounded fallback behavior, and that it replaces 4-6 sequential calls. It also clarifies the meaning of tolerance_pct overrides, adding significant behavioral context.

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

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

The description is dense but well-structured, front-loading with trigger phrases and usage context before technical details. Every sentence contributes: purpose, usage, pipeline routing, output format, error semantics, and efficiency. Despite its length, it is efficient and avoids redundancy, earning a 5.

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

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

Given the tool's complexity (two pipelines, multiple verdicts, error cases, no output schema), the description is remarkably complete. It explains return values (verdict, actual value, citation, reasoning), the meaning of each verdict, the fallback behavior, and the tolerance override. The only minor gap is lack of latency/limitation notes, but for a fact-check tool with robust 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% for both parameters, so the baseline is 3. The description adds value by explaining how tolerance_pct overrides the claim's implied tolerance, gives a default behavior (capped at 5), and provides concrete examples for the claim parameter, elevating it above the schema's minimal documentation.

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

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

The description clearly identifies the tool as natural-language claim verification with a specific verb and resource: 'natural-language claim verification against authoritative sources.' It distinguishes itself from siblings by focusing on fact-checking (verdicts like confirmed/refuted) and explicitly stating it handles both company-financial claims via SEC EDGAR and any other factual claim via a grounded pipeline. This is a specific, well-scoped purpose that stands apart from other research/query tools.

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

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

The description gives clear context on when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the auto-routing between the structured SEC path and the grounded pipeline. However, it does not explicitly name alternative tools or provide when-not-to-use exclusions beyond 'could_not_verify' semantics, so it stops short of a 5.

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