Arcgis Dc

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

Beyond the readOnly/idempotent annotations, the description discloses the free default model, the BYO key arrangement for Anthropic ('you pay Anthropic directly'), and a return-structure preview. 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?

Three focused sentences cover purpose, auth/cost behavior, return format, and use cases. Every sentence earns its place without fluff.

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

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

For a read-only probe tool with rich annotations and full schema coverage, the description is near-complete. It covers the return shape and use context; a minor omission is error/limit behavior, but overall sufficient.

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

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

Schema covers 100% of parameters, so baseline is 3. The description adds the specific model name 'Workers AI Llama-3.3-70b' and cost implications, but most parameter details (free default, _apiKey requirement) are already in the schema, so added value is marginal.

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

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

The description opens with a specific action ('Probe one or more LLMs...') and clearly defines the output (visibility score 0-100 per model). It clearly differentiates the tool's focus on AI visibility, though it doesn't explicitly contrast with sibling tools like scan_competitor_ai_presence.

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

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

Provides explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') that signal when to deploy. It does not mention alternatives or when not to use it, so no exclusions are given.

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

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

With readOnly/openWorld/idempotent annotations already present, the description adds useful router behavior: it fans out to 5,710 tools, fills arguments automatically, and returns citations as stable pipeworx:// URIs. It also claims preference over web search even when web search could answer, which is a meaningful behavioral trait. Nothing in the description 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 genuinely useful content is front-loaded in the first paragraph: preference over web search, sources, routing behavior, citations, and examples. However, the identical 'START HERE...' block with the same six examples is repeated dozens of times, so the description massively violates the 'every sentence earns its place' standard.

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-free-text-param router with no output schema, the description supplies the essential invocation context: domains, trigger phrases, examples, routing behavior, and return format. It is complete enough to call, though the sibling-tool relationship and a concise editing pass would make it better.

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

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

The schema already covers the question parameter and all aliases at 100%, so the baseline is a 3. The description adds value by enumerating query phrasings ('what is', 'get the latest', 'how much') and domain examples that clarify acceptable free-text input beyond the schema's three examples.

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

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

The first sentences name a concrete action ('Routes the question to the right one of 5,710 tools...') and a concrete result ('returns the structured answer with stable pipeworx:// citation URIs'). It clearly distinguishes itself from web search, but it does not explicitly distinguish itself from sibling tools like ask_pipeworx_beta or ask_pipeworx_grounded.

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

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

It explicitly says 'PREFER OVER WEB SEARCH' and 'Use whenever the user asks...', with trigger phrases and six concrete examples, so an agent knows when to invoke it. It lacks explicit when-not-to-use conditions and does not contrast against sibling tools, so it falls short of a top 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 cover readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds useful behavioral context: it is a live experimental router whose behavior may change when a candidate is under test, results are compared against the stable router, and currently it matches ask_pipeworx exactly. It stops short of describing routing mechanics or what 'candidate routing improvements' concretely change, but for a router with no output schema the core behavioral disclosure is present.

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 tightly packed sentences, each earning its place: what it is, what is different now, when to use it, and what it is not. The key qualifier (no candidate active) 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 simple single-required-parameter router with annotations declaring it read-only and safe, the description adequately explains identity, current parity with ask_pipeworx, and experimental nature. It lacks detail on what the routing improvements are or how responses might differ from ask_pipeworx, but the tool's simple contract makes those gaps acceptable.

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%; each alias is documented and the question parameter says it accepts natural language. The description adds nothing about parameter meaning beyond the schema, so baseline 3 is appropriate.

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

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

States specific verb+resource: a beta version of ask_pipeworx, a universal router with same 5,710 tools, same arguments, same response shape. Distinguishes from sibling ask_pipeworx by explaining it is the experimental edge with candidate routing improvements, and explicitly says no candidate is active so it currently matches ask_pipeworx exactly.

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 it exactly like ask_pipeworx when you want the newest routing; contrasts with stable router ask_pipeworx; and clarifies it is a full working router, not a fallback stub. That gives an agent a clear selection criterion.

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

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

Annotations already cover safety (read-only, idempotent, non-destructive), and the description adds substantial behavior beyond that: the full refusal contract with all five enumerated refusal_reason values, the success return shape including 'evidence (verbatim quote)' and 'confidence', and the cost profile of one extra LLM call. 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 logically ordered: mode definition, routing explanation, success/refusal return shapes, use cases, and cost trade-off — every major element earns its place. The one trimmable detail is 'from 5,710 across 1494 sources,' which adds scale context but is not essential to selecting or invoking the tool.

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

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

With no output schema present, the description fully carries the return-value burden and specifies both the success shape ({answer, evidence, confidence, source, fetched_at, refusal_reason:null}) and the complete refusal shape with all five reasons. Combined with 100% schema coverage on parameters and safety-carrying annotations, nothing needed to call or interpret this tool 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%, so the schema already documents the required 'question' parameter with its aliases and the optional context, beam_size, language, max_tokens, and refund parameters. The description explains the overall pipeline ('picks the right tool... fills arguments, fetches the data') but adds no param-level syntax or format detail, so the baseline 3 applies.

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

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

The description names a specific mode — 'Hallucination-resistant answer mode for high-stakes reads' — with a clear verb (answers via grounded extraction, not just fetches). It differentiates from its sibling ask_pipeworx by stating it 'EXTRACTS the answer using ONLY what the tool result contains,' which pins down its unique purpose among the many sibling tools.

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

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

It gives an explicit when-to-use directive: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' plus concrete domains (financial verdicts, legal claims, medical lookups, public statements). It also names the alternative and the selecting condition: 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups.'

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, so the bar is lower, but the description goes far beyond: it details resolver contracts, status values, suppression of analysis fields on low-confidence matches, market_closed_or_inactive blocking, wide-spread illiquidity warnings, and resolution-rule risk (refund_50_50 etc.). It also explains news fallback behavior. 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 extremely well-structured with clear section labels (RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, SAFETY, RESOLUTION-RULE RISK) and each section adds necessary invocation-relevant detail. It is front-loaded with purpose and use cases. A small amount of redundancy exists (schema examples repeated), so not a perfect 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?

There is no output schema, so the description must explain return values and error/edge behaviors itself. It does this exhaustively: response shapes for result.market/analysis/evidence, resolver fields, parent-event structure, news fallback fields, and blocking statuses. The coverage is comprehensive for the tool's complexity.

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

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

Schema description coverage is 100%, and the schema already explains market, depth, and include_raw with examples. The tool description reinforces these (e.g., accepted market formats, quick vs thorough) and adds fan-out examples, but does not meaningfully expand parameter meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly states the tool's scope (resolving markets, classifying bets, fanning out to data packs, returning evidence + comparison) and differentiates it from siblings like polymarket_edges and polymarket_arbitrage by focusing on full research/evidence gathering rather than just pricing or edge calculation.

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

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

The description provides explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also explains blocking behaviors for low-confidence matches and closed markets. However, it does not name alternative tools or state when NOT to use this tool, so it misses the exclusion part of a 5.

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

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

Annotations already declare readOnly/openWorld/idempotent, but the description adds substantial behavioral detail: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and output format with citation URIs. This far exceeds what annotations alone provide with no contradiction.

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

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

The description is a single dense paragraph but every sentence contributes value: trigger phrases, usage preference, data source details, sorting behavior, and output. It is slightly long (~180 words) for a tool description, but there is no fluff; the structure front-loads the most important 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?

Despite no output schema, the description fully explains what the tool returns (paired data + citation URIs), how results are sorted, and key edge cases (off-calendar fiscal years). It covers type-specific behavior and limits (2–5 entities), making the tool's behavior clear even in complex scenarios.

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

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

Schema coverage is 100% with descriptions for both parameters, giving a baseline of 3. The description goes further by explaining the meaning of each type ('company' pulls latest 10-K figures, 'drug' pulls FAERS/trial counts) and providing concrete examples for values (['AAPL','MSFT'], ['ozempic','mounjaro']). This adds contextual semantics beyond the schema.

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

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

The description uses a specific verb+resource ('side-by-side comparison of 2–5 companies or drugs') and immediately distinguishes itself from sibling tools like entity_profile by emphasizing a single parallel call. It also lists trigger phrases ('which is bigger', 'rank these companies') that make 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 explicitly states when to use it: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It provides clear alternatives (sequential lookups) and even quantifies the benefit ('Replaces 8–15 sequential lookups'). The type-specific behavior further guides selection between company and drug comparison.

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

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

Annotations already cover read-only, idempotent, open-world, and non-destructive traits. The description goes well beyond this by disclosing account/paid-tier requirements, latency expectations (15-60s, thorough ~90s), gaps[] behavior per depth, contradictions[] on standard/thorough, the hop field, citation_uri fetchability conditions, and semantic excerpting of large records. No contradiction with annotations.

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

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

The description is long but dense and front-loaded with the critical account requirement and alternative tool. Some redundancy exists—'this is NOT open-web search' and 'use ask_pipeworx' appear multiple times—but each section adds necessary operational detail. A bulleted structure would improve scannability, yet every sentence contributes meaningful 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?

With no output schema, the description fully explains the return packet: findings with confidence/source/fetched_at, pipeworx:// citations, gaps[], contradictions[], hop field, citation_uri rules, and semantic excerpting. It also covers auth, alternatives, and latency. Nothing an agent needs to call or interpret this tool 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%, so baseline is 3. The description adds meaningful context beyond the schema: depth:'thorough' requires a paid plan, latency varies by depth, and the re-ask-with-deeper-depth pattern. Most depth mechanics are already in the schema enum descriptions, so the added parameter value is moderate but real.

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

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

The description states a specific verb and resource: it performs 'grounded multi-source research across Pipeworx's 1494 STRUCTURED data sources', decomposes questions into facets, routes to tools in parallel, and returns a findings packet. It explicitly distinguishes itself from open-web search and names sibling tools like ask_pipeworx, so an agent can tell it apart without opening schemas.

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

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

The description gives explicit when-to-use guidance: best for broad/multi-part questions over structured data, and clearly routes alternatives—use ask_pipeworx if not signed in, for single lookups, for open-web search, and for non-catalog/current-events topics; use ask_pipeworx_grounded for grounded open-web answers. It also explains depth-tier trade-offs and re-asking with deeper depth.

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 context: returns top-N relevant tools with full schemas and examples, and results are ready to call directly without a second lookup. This goes beyond the annotations by describing output format and the convenience of pre-populated schemas. No contradiction.

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

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

The description is two sentences, around 60 words, with front-loaded purpose and concise usage guidance. Every sentence adds value: what it does, when to use it, what it returns, and the 'call first' recommendation. No redundancy or filler.

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

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

Despite having no output schema, the description fully explains the return format: top-N tools with names, descriptions, and full input schemas, ready to call. It covers use cases, domain scope, and the meta-tool nature. Given the tool's moderate complexity, this description is complete.

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

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

Schema description coverage is 100% (all six parameters are described in the schema). The description does not add much beyond what the schema already provides, such as the 'limit' parameter meaning top-N. It slightly reinforces the purpose of 'query' as natural language, but the schema handles the heavy lifting, so the baseline 3 is appropriate.

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

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

The description uses a specific verb+resource: 'Find tools by describing the data or task.' It clearly distinguishes this tool from siblings like search_datasets or deep_research by focusing on discovering tools rather than answering or searching data directly. It covers a broad domain list, making its scope 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?

Explicitly states when to use it: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' It also hints at when not to use it ('not just one answer'), implying more specialized tools are better for direct answers. This is strong guidance.

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

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

The annotations declare readOnly/openWorld/idempotent, and the description adds rich behavioral context far beyond that: it fans out across multiple sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), returns specific fields (cik, recent_filings with URIs, latest 10-K fundamentals sorted by period_end DESC), describes a fallback chain (GDELT→GNews), and discloses the USPTO API sunset with soft-fail behavior. This gives the agent realistic expectations about data availability and format.

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

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

The description is long but structured heavily with semicolons, parentheses, and a clear enumeration of return fields. It starts with relatable example queries, then the core function, then output details. Every sentence adds useful information; no filler or repetition. It earns a 4 because it's dense but maybe slightly longer than strictly necessary, though the complexity justifies 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?

With no output schema, the description fully carries the burden of explaining return values. It lists all major output groups (cik + company_name, recent_filings with URIs and count, fundamentals with specific metrics and sorting, patents with sunset/soft-fail, news via fallback, LEI via GLEIF). It also states input constraints and gives a fallback for unsupported names, making the tool's behavior complete and predictable.

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 documents both parameters and covers 100% of them, so baseline is 3. The description adds value by providing concrete examples ('AAPL', '0000320193'), emphasizing the zero-padded CIK requirement, and restating the no-names constraint with a pointer to resolve_entity. This reinforces parameter formatting and constraints beyond the schema.

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

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

The description opens with concrete user intents ('Tell me about X', 'research Acme') and then states the core function: 'full cross-source profile of a US public company in ONE parallel call.' It explicitly contrasts with sibling tools by saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and references resolve_entity for unsupported name inputs, distinguishing it clearly.

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 via example phrasings, an emphatic preference directive ('ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view'), and a clear exclusion: 'names not supported (use resolve_entity first if you only have a name).' It also notes the patents API sunset and soft-fail behavior, further clarifying expected usage.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the destructive nature is disclosed. The description adds the specific context of deleting by key and the use-cases, but does not disclose additional behavioral traits beyond what annotations provide, like irreversible effects or required existence of the key.

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

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

The description is two sentences, front-loaded with the action, and every sentence carries useful meaning. It avoids redundancy and includes actionable guidance in a compact form.

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

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

Given a single parameter, no output schema, and annotations covering safety, the description sufficiently covers purpose and usage. It lacks details on return values or error behavior, but these are not critical for a simple deletion tool, making it almost 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% and the parameter 'key' is already described as 'Memory key to delete.' The description's 'by key' adds no new semantic detail beyond the schema, so the baseline of 3 applies.

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

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

The description starts with a specific verb and resource: 'Delete a previously stored memory by key.' This clearly distinguishes it from sibling tools like remember (store) and recall (retrieve), making the purpose unambiguous.

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

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

It provides explicit when-to-use guidance: 'when context is stale, the task is done, or you want to clear sensitive data.' It also names alternatives by saying 'Pair with remember and recall.' However, it lacks explicit when-not-to-use conditions, hence a 4 rather than 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 provide readOnly, idempotent, and non-destructive hints, so the safety profile is already set. The description adds behavioral details like 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format', giving a clear picture of the tool's workflow beyond the annotations. No contradiction.

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

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

The description is concise and front-loaded, with the main action stated in the first sentence. It includes only relevant details (what it does, output format, use cases) and avoids unnecessary fluff.

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

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

For a simple tool with a single required parameter and no output schema, the description covers the key aspects: purpose, output format, and use cases. It does not discuss edge cases like inaccessible URLs, but given the tool's simplicity and good annotations, it is reasonably 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 schema already documents both parameters with 100% coverage, including default and max values for max_links. The description does not add additional meaning beyond what the schema provides, so it meets the baseline but doesn't 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 uses a specific verb 'Generate' with a clear resource 'llms.txt file for any URL', and distinguishes itself from siblings like ai_visibility_check or scan_competitor_ai_presence by focusing on producing the file itself. It also specifies the output format and target audience.

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 use cases starting with 'Useful for:' and names specific scenarios. It does not mention exclusions or alternatives, but the context is clear enough. No conflicting 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, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the return payload details (fields, geometry type, record count, capabilities) but does not disclose additional behavioral traits such as authentication requirements or rate limits. With annotations present, the added context is useful but not extensive.

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

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

The description is a single, front-loaded sentence with no redundant words. It efficiently conveys the action, target, and outputs, making it easy to parse.

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

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

For a simple, read-only tool with one well-documented parameter and strong annotations, the description fully conveys what the tool returns and the type of resource it operates on. No output schema exists, so the explicit listing of return items is essential and provided.

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

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

The input schema provides 100% coverage for the single 'url' parameter, including its own description and an example. The tool description adds no further parameter-level detail beyond 'by url', so the baseline score of 3 applies.

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

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

The description uses the specific verb 'Get' and clearly identifies the resource (ArcGIS Feature/Map Service layer schema) and the specific return contents: fields (name + type), geometry type, total record count, and capabilities. This clearly distinguishes it from sibling tools like query_layer, which presumably retrieves actual data rather than schema.

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 retrieving layer schema but does not explicitly state when to use this tool versus alternatives. No exclusions or references to sibling tools are provided, so the guidance is only implicit.

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

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

Annotations already cover read-only and safe nature; description adds the specific return fields and the scope of 'caller's' subscriptions, offering behavioral detail beyond annotations. No pagination or rate limit info, but acceptable for a simple list.

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

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

Three concise sentences: purpose, return fields, usage guidance. No wasted words, well structured.

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

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

Given the simple optional parameter and lack of output schema, the description lists the return fields and provides usage context. It's complete for this tool.

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

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

Schema description covers include_inactive fully at 100% coverage. Description does not add parameter details, but the schema handles it, hitting 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?

States clearly it lists the caller's active subscriptions with a specific resource and scope. Differentiated from sibling subscribe/unsubscribe tools by focusing on listing.

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 it: before adding more subscriptions or to find an id to cancel. Provides clear context but does not name alternative tools explicitly or state 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 are all false, so the description carries the full burden, and it excels: it discloses rate limiting (5 per identifier per day), the account-free claim_token follow-up mechanism, that it's free and doesn't count against quota, and that the team reads digests daily. No annotation contradiction.

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

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

The description is dense but every sentence earns its place. It front-loads the core purpose, then gives usage cases, exclusions, follow-up mechanics, and operational constraints in a logical order. No redundant or filler content.

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

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

Despite having no output schema, the description fully explains return behavior (claim_token when no account), the follow-up workflow, rate limits, and the audience (Pipeworx team). For a feedback tool with 4 parameters and nested objects, this is complete and self-sufficient.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds valuable semantic guidance beyond the schema: it instructs users to describe issues in terms of Pipeworx tools/packs rather than pasting end-user prompts, and clarifies the claim_token usage pattern for reading past feedback status. This exceeds the baseline but is not exhaustive since the schema already covers parameter details.

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

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

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' using a specific verb and resource that clearly distinguishes it from sibling tools like ask_pipeworx. It also lists concrete feedback categories (bug, feature, data_gap, praise), which uniquely identifies this as the feedback channel.

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

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

The description explicitly states when to use the tool ('Use when a tool returns wrong/stale data...'), enumerates all feedback types, and provides a clear exclusion: ONLY for tools served by this Pipeworx connection, with instructions to file elsewhere for other MCP servers. It even gives decision guidance for uncertain cases ('Not sure? Pipeworx tool names are the ones this connection lists.').

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, open-world behavior. The description adds meaningful context: it is self-aggregating from CF analytics-engine, contains no PII, and is cached 5min-1h depending on window. This goes beyond the annotations but doesn't fully describe edge cases like empty results or rate limits.

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 result, followed by three numbered use cases and a brief note on data source/privacy. It is a bit longer than strictly necessary, but each sentence adds value and the structure is clear.

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

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

For a simple read-only stats tool with one optional parameter and strong annotations, the description covers the essential return content (top tools, top packs, call volume), caching behavior, and privacy characteristics. It lacks an explicit output schema but provides enough for an agent to understand expected results.

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

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

Schema description coverage is 100%, and the 'window' parameter is fully documented in the schema with enum values and meaning. The tool description merely echoes the schema's note about shorter vs. longer windows without adding novel semantic insight, 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's function with a specific verb and resource: it 'Returns the top tools, top packs, and total call volume' from Pipeworx. It also lists concrete use cases, distinguishing it from siblings like ask_pipeworx or discover_tools by focusing on aggregate popularity 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?

Explicit use cases are provided (e.g., discovering hot data sources, confirming canonical tools, aligning with agent needs). However, it does not mention when not to use or explicitly name alternative tools, so it falls short of a 5.

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

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

Beyond the readOnlyHint/idempotentHint annotations, the description discloses critical behavioral details: the 3pp partition deviation threshold, the placeholder-slug filtering and >20% placeholder fraction null behavior, the Jaccard similarity anchor (≥0.30), and the fill-check logic that uses live CLOB depth to determine whether an edge is realizable. It also explicitly warns against executing trades on non-realizable edges.

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 clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loads the core purpose. Every section contributes actionable guidance—no filler or tautology. The length is justified by the tool's complexity and the absence of an output schema, which makes the response description necessary.

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

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

Given the tool has two optional parameters, no output schema, and a complex multi-mode behavior, the description is exceptionally complete. It describes the response shape (opportunities[], partition_check fields), the fill check pricing, failure conditions (realizable_edge_pp <= 0), and points to polymarket_fill_risk for custom sizing. Nothing essential 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?

Although the schema already describes the event and topic parameters at 100% coverage, the description adds substantial meaning: it gives concrete slug examples, explains the mechanics each parameter triggers ('walks child markets', 'searches related events across the platform'), clarifies that no arguments performs a trending scan, and introduces semantic/partition filtering behavior. This goes well beyond the schema's basic descriptions.

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

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

The description opens with a specific verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes three operational modes (trending_scan, event, topic) and differentiates itself from sibling tools like polymarket_edges or polymarket_fill_risk by the unique arbitrage detection mechanism.

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

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

Explicit instructions are given for when to use which mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It also provides an alternative for sizing: 'For custom sizing use polymarket_fill_risk', and warns when not to trade ('do not trade it' when realizable_edge_pp <= 0).

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. It discloses caching behavior ('Cached 1h at the KV level keyed on all knobs'), explains the internal model families and response segments, details the edge fields (edge_pp_net, kelly_fraction, etc.), and warns about the 24h-move signal. It also explains the purpose of diagnostics and why Fed bets are excluded. This is rich behavioral context that the annotations (readOnlyHint, idempotentHint) do not cover.

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

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

The description is long but densely packed with relevant information. It uses clear structure (uppercase section headers, numbered model families, explicit knob lists) to organize the content. Every sentence contributes value, although the sheer volume of detail might overwhelm some agents. It is appropriately sized for a complex tool with 9 parameters and rich output.

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

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

Despite having no output schema, the description thoroughly defines the response top-level structure (by_segment, fed_candidates/fed_note, _diagnostics) and explains the data fields within opportunities. It covers the main user-facing behaviors, edge-case handling (e.g., placeholder-slug filter, partition >20% placeholder skip), and even the reasoning behind excluding Fed bets. This is as complete as a text description can be for a complex tool.

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

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

The schema already provides 100% parameter coverage, giving a baseline of 3. The description adds meaningful context for several knobs: it explicitly explains min_liquidity / max_spread_pp as 'tradeable-edge filters' and min_partition_leg_kelly as a per-leg filter with rationale. It also clarifies slippage_pp's effect on edge_pp_net. Not every parameter is re-explained, but the added semantics elevate the score above baseline.

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

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

The description opens with a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly defines the tool's purpose and adds a distinctive use case ('what should I bet on today'), which sets it apart from generic market search tools. The detailed segmentation into MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, and CONCENTRATED_LONGSHOT further clarifies the scope.

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

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

The description clearly states the intended use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' This provides clear context for when to use the tool. However, it does not explicitly mention alternative sibling tools (e.g., polymarket_arbitrage, polymarket_edge_tracker) or give exclusion criteria, so it stops short of a 5.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description adds significant behavioral detail: data gaps explained via 'snapshots are written when polymarket_edges runs on a cache-miss', history depth limited by '60-day snapshot TTL', and decay computed 'from daily closes of edge_pp_net (net of default slippage), not intraday'. This exceeds the value of annotations and fully discloses limitations.

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

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

Though the description is relatively long, it is highly structured with clear sections for purpose, arguments, response, and limits. Every sentence provides necessary information, especially given the absence of an output schema. It is front-loaded with the core purpose and avoids 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?

Without an output schema, the description fully explains the response structure (tracked[], expired[], snapshot_dates[]), including field meanings and lifecycle semantics (e.g., 'GONE from the latest'). It also covers critical limitations (TTL, snapshot gaps) and the source of decay numbers, making the tool's behavior and output sufficiently clear for an agent to invoke and interpret correctly.

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

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

The schema already provides descriptions for both parameters with 100% coverage, so the baseline is 3. The description adds semantic nuance by defining 'window' as a 'snapshot family' and clarifying the role of 'days' as a lookback with a max of 30. This enriches understanding beyond the schema's simple defaults and enums.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and directly answers the question 'how long has this edge existed and is it shrinking?' It distinguishes itself from sibling tools by focusing on historical edge analysis rather than raw edge data or other functionality.

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

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

The description provides context about when the tool is relevant (e.g., 'a fresh wide edge and a 3-week-old wide edge are different trades') and implies that it is used for analyzing edge persistence/decay. However, it does not explicitly state 'use this when...' or name alternatives, such as polymarket_edges for current edges. Usage is implied rather than explicitly guided.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description discloses rich behavioral details: it walks the order book ladder, returns specific metrics (top_of_book, vwap_fill_price, slippage_pp, shares_filled, verdict), and highlights risks such as partial basket fills converting an arb into an unhedged directional position. It also explains how size_usd is interpreted differently for buys vs sells and in basket mode, giving the agent a clear expectation of side effects and 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 long but every sentence contributes critical information for a complex tool with two operating modes. It is front-loaded with the core purpose, then structured by mode (SINGLE-MARKET, BASKET) and usage guidance. Each return field and behavioral nuance is mentioned once, with no repetition or filler. 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?

Given the tool's complexity (4 parameters, two modes, no output schema, and nuanced risk semantics), the description is remarkably complete. It lists all expected return values (e.g., vwap_fill_price, max_fillable_usd, thin_legs[], forced_directional_risk) and explains the verdict categories. It also integrates with sibling tools by naming when to use it, making it fully contextual for an AI 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?

Although schema description coverage is 100%, the description adds substantial meaning beyond the schema. It clarifies that `market` and `event` are mutually exclusive modes, interprets `side` for each mode (including auto-detection for basket), and explains that `size_usd` means 'max spend on buys, target proceeds on sells' in single-market mode and 'settlement notional' in basket mode. This is far more than the schema's basic field descriptions, fully compensating for any gaps.

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

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

The description opens with a precise definition: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' This names the exact action (check edge realizability), the resource (CLOB order book), and immediately distinguishes the tool from siblings like polymarket_arbitrage and polymarket_edges by focusing on fill risk. The two modes (single-market and basket) are explicitly laid out, leaving no ambiguity about the tool's 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 explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround on thin books is not capturable) and how to choose between single-market and basket modes. This clearly positions the tool relative to its siblings and gives concrete criteria for when to invoke it.

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 far beyond the annotations: safety fields that can be non-empty even on successful matches, the full machine-readable compatibility code list, the NEVER-paired rule for unknown metric_type/match_subtype legs, the skipped_cross_type/cross_subtype counters, temporal_alignment semantics, and the behavioral caveat that most pre-mapped topics return warnings. Given readOnlyHint/idempotentHint already cover the safety profile, this adds genuinely non-redundant behavioral context.

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

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

The description is long but every sentence earns its place — mode selection, response shape, safety fields, edge-case rules, and a cautionary note, none of which are available elsewhere since there is no output schema. It is front-loaded with the core purpose and scope. The middle section enumerating codes is dense and could be tightened, but it is necessary given the absence of structured output documentation.

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 high-complexity tool with 3 params, two modes, and a rich output object but NO output schema, the description carries the full burden of explaining return values and edge cases — and it does: response shape, spread direction, compatibility fields, per-entry flags, skip counters, and alignment info are all documented. An agent has everything needed to invoke either mode and correctly interpret a non-obvious 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, but the description adds real semantics: it explains that `topic` auto-fetches the matching event on each venue, that explicit params create 'custom pairings', and how the two modes interact. It also clarifies what the topic values map to conceptually (macro shortcuts). This goes beyond the schema's bare enum list and examples.

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

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

The opening sentence states a specific resource and operation: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. The 'cross-venue' framing clearly differentiates it from Polymarket-only siblings like polymarket_arbitrage and polymarket_edges, and the delta direction (Kalshi − Polymarket) is pinned down. Not a tautology; it names a concrete analytical task.

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 guidance is explicit and structured: two modes are spelled out ('topic' pre-mapped shortcuts vs explicit ticker/slug pairings), with the override relationship between them implied. The closing caveat (pre-mapped ≠ tradeable; most topics return compatibility_warning today) functions as a when-not signal. However, no sibling tool is named for routing — an agent is never told 'use X instead when you only need one venue' — so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is fully covered. The description adds that it returns attribute rows and geometry, which is useful behavioral context beyond the annotations. There is no contradiction between the description and the annotations.

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

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

The description is two sentences: the first states the purpose and lists the parameters, and the second gives a useful tip. It is front-loaded, concise, and contains no filler or redundancy. 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?

Given the tool's moderate complexity (6 params, 1 required) and rich annotations, the description covers the essentials: what it does, the source of the URL, and return type. Without an output schema, it could specify the output format in more detail, but it is still complete enough for an agent to select and invoke the tool correctly.

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

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

The schema provides 100% coverage of the 6 parameters with descriptions, so the baseline is 3. The description adds a cohesive usage pattern (e.g., the sampling example) that ties the parameters together, and it lists the key parameters in the first sentence. This goes slightly beyond the schema alone, earning a 4.

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

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

The description clearly states the tool queries an ArcGIS Feature Service / Map Service layer via URL, with the specific verb 'Query' and a clear resource. It distinguishes from siblings like layer_info by specifying it returns attribute rows and geometry, and it connects to search_datasets as the source for URLs.

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 mentions the URL comes from search_datasets, providing a clear workflow context. It also gives a practical sampling tip (where='1=1' + out_fields='*') that guides when to use it for exploration. However, it does not explicitly exclude alternatives or state when not to use it, so it is slightly below a perfect 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?

The description adds valuable behavioral context beyond the annotations, including scoping ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the mode-switch behavior (omitting the key argument lists all saved keys). This goes beyond the readOnly/idempotent hints and helps the agent understand privacy and output variations.

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

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

The description is three sentences long, front-loaded with the primary action, and every sentence adds value. It covers functionality, use cases, and scoping without any redundancy or fluff.

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

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

For a simple 1-parameter tool with no output schema, the description is sufficiently complete. It covers what the tool does, when to use it, its scoping rules, and its relationship to remember/forget. No additional context is necessary for correct invocation.

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

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

The input schema already provides 100% coverage of the single key parameter with the note 'omit to list all keys', and the description essentially repeats this semantics. Per the rubric, when schema coverage is high, a baseline of 3 is appropriate; the description does not add significant new parameter information.

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 with a specific verb ('Retrieve') and resource ('a value previously saved via remember'), and explicitly distinguishes it from siblings by describing its dual behavior (get a value or list all keys). The mention of 'remember' and 'forget' as companion tools further clarifies its role.

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

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

The description provides clear when-to-use guidance with concrete examples ('the user's target ticker, an address, prior research notes') and explains the benefit ('without re-deriving it from scratch'). It does not explicitly name alternative tools or state when not to use it, but the context is sufficiently clear.

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

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

The description discloses that setting mark_read:true flags returned events as read and affects subsequent calls, which implies a state change. This directly contradicts the annotation readOnlyHint=true and also challenges idempotentHint=true, as repeated calls may return different results after marking events read. This is a clear annotation contradiction, so the score is 1.

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, well-structured paragraph of four sentences, each serving a distinct purpose: what the tool does, what it returns, how to filter, and a note on polling/alternate access. It is concise, front-loaded with the main verb, and contains no filler, though it could be slightly more organized with bullet points for the details.

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

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

Given the tool has no output schema and 5 parameters, the description covers key contextual points: return fields (source, citation_uri, raw payload), filtering options, mark_read behavior, and an alternative access URL. It does not explicitly describe unread_only, but the schema covers that. The description is sufficiently complete for an agent to understand the tool's role and data flow.

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 all 5 parameters with descriptions, so the baseline is 3. The description adds meaningful semantics beyond the schema: it provides a concrete example for type ('sec_8k'), clarifies that since is an ISO timestamp, and explains the behavioral consequence of mark_read ('the next call only shows newer ones'). This added value justifies a score of 4.

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

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

The description clearly states the tool's specific function with verb+resource: 'Pull fired events from your subscription feed.' It goes beyond a generic statement by describing the returned data (source, citation_uri, raw event payload) and distinguishing itself from sibling tools like list_subscriptions and subscribe/unsubscribe, which focus on subscription management.

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 practical usage context: 'Polls work fine' indicates this is suitable for polling workflows, and it mentions an alternative access method (GET registry.pipeworx.io/alerts.json) for scripts/dashboards. It does not explicitly exclude or compare to sibling tools, but the context is clear enough for selecting this tool for reading subscription alerts.

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, idempotentHint) are consistent; description adds context about multi-source fan-out, GDELT→GNews fallback on rate limits/5xx, API sunset soft-fail, and returns citations. This goes beyond annotations to disclose 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?

Dense but well-packed; front-loaded with natural-language triggers, then sources, then input formats, then output and alternative. No wasted sentences, though a single long paragraph could benefit from structural breakers; still highly scannable.

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

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

No output schema, so description explains return shape ('structured changes[] grouped by source + total_changes count + citation URIs'). Also covers multi-source behavior and fallback. Could mention pagination or empty-result behavior, but for complexity this is strong.

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

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

Schema already describes all 3 parameters with examples and typical values ('Use 30d or 1m'). Description repeats this, adding only the conceptual context of the window and entity but no new syntax beyond schema. Since coverage is 100%, baseline 3.

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

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

Description clearly states it's a change feed for a company over a time window, explicitly listing sources (SEC EDGAR, GDELT/GNews, USPTO) and distinguishing from entity_profile. The verb 'fans out' and action of returning structured changes make the tool's purpose unambiguous.

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

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

Provides explicit query examples ('What's new with X', 'latest on Y'), describes when to use, and directly says 'Use entity_profile instead when you want the static profile' — a clear alternative. Also notes fallback behavior and limitations (USPTO soft-fail), guiding when to expect results.

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

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

Annotations already indicate idempotent and non-destructive write, but the description adds scoping ('scoped by your identifier') and retention policies (persistent for authenticated, 24 hours for anonymous). This is substantive behavioral context beyond the annotation 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 deliver a clear purpose, usage guidance, storage model, persistence behavior, and sibling pairings. Every sentence contributes unique information, and the description is front-loaded with the verb.

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 write operation with no output schema, the description covers what to store, when to use it, how persistence works, and related tools. The absence of return-value details is acceptable. This is complete for its complexity.

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

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

Schema covers both parameters with clear descriptions and examples. The description adds only the phrase 'key-value pair' which mirrors the schema, providing no additional semantic detail. With 100% schema coverage, baseline 3 is appropriate.

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

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

The description opens with a specific verb ('Save') and resource ('data... to reuse later'), and distinguishes this from siblings by mentioning recall and forget as complementary operations. It also specifies the key-value storage model, making the tool's purpose unmistakable.

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

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

Explicitly states when to use: 'when you discover something worth carrying forward' with concrete examples. It also pairs with recall and forget, giving clear context for when to use this vs alternatives. The persistence details (authenticated vs anonymous) guide usage expectations.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the description's job is to add context beyond these. It does so admirably: it discloses graceful degradation ('LEI/FIGI enrichment degrades gracefully'), the composite cascading nature ('each call cascades through several lookup endpoints internally'), and output structure ('every identifier is labelled with the source…unresolved is stated explicitly'). 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 lengthy (~250 words) and includes a lot of detail. While it is well-structured (front-loaded with examples and usage, then type details), it could be more concise. For example, the inline examples and nested explanations of identifier sources add value but sacrifice conciseness. It earns its place but is not minimal.

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 entity types, multiple identifier sources, cascading lookups, graceful degradation, no output schema), the description is remarkably complete. It covers input semantics, output structure (including the unresolved field), source labeling, and fallback behavior. The agent can confidently infer what to expect from a call, making it fully adequate for selection and invocation.

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

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

Schema coverage is 100% with both parameters described. The description adds significant extra meaning: it explains what identifiers are returned per type (e.g., company yields CIK, ticker, LEI, FIGI) and provides an example with ISIN. It also clarifies input flexibility (ticker, CIK, ISIN, name). This goes well beyond the schema's enum and string descriptions, justifying a 4.

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

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

The description opens with concrete example queries ('What's the ticker for…', 'find the CIK for…') and clearly states the tool's purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It distinguishes itself from sibling tools like entity_profile by positioning itself as the first step when you have a name but need an ID. The verb 'resolve' is specific and the resource (identifiers) is well-defined, avoiding tautology.

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 advises 'Use FIRST whenever you have a name but need an ID,' which is a strong usage guideline. It also implies that if you already have an ID, you might use other tools. However, it does not explicitly enumerate when not to use it or list alternative tools for post-resolution steps. The mention that it replaces 2-3 manual lookups helps the agent understand its composite nature.

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, so the description only needs to add context. It discloses that the tool calls ai_visibility_check per entity, ranks by score, and returns a ranked list with score, confidence, and signal density—valuable behavioral detail beyond the annotations.

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

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

The description is two sentences long, front-loads the action, and avoids redundancy. Every clause adds information, from the probing mechanism to the output format.

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

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

For a tool with no output schema, the description explains the return value (ranked list with score, confidence, signal density) well. It also gives a clear use case and mentions the underlying ai_visibility_check dependency, making the tool's function and context sufficiently clear.

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

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

The input schema has 100% parameter description coverage, so the description adds little extra meaning for parameters. It does mention entities as 'your brand + N competitors' and 'first entry treated as subject', which partially reinforces the schema, but does not add new semantics beyond what the schema already provides.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, with a specific verb and resource. It differentiates from sibling tools like ai_visibility_check (which likely checks a single entity) by emphasizing multiple entities and ranking.

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

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

The description includes a concrete use case—competitive AI-marketing audits—with an example question. However, it does not explicitly state when not to use this tool or name alternatives, though the context implies ai_visibility_check for single entities.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses important behavioral traits: composite fan-out across two services, graceful partial-failure degradation, the 5-30s latency for first bundlephobia measurement, and the sources_failed field. This adds valuable context 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 dense but every sentence adds value. It is front-loaded with the core purpose, then lists return fields, scope limitations, and failure behavior. The use of em-dashes and semicolons keeps it readable 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?

With no output schema, the description thoroughly explains return values (summary block, advisories, links, recent versions), covers ecosystem limitations, and addresses failure modes. For a multi-source composite tool, this level of detail is complete and well-suited 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 coverage is 100% and both parameters are already described in the schema (package name, optional version). The description does not add new parameter-level semantics beyond what the schema provides, so the 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 a specific purpose: a composite 'should I add this npm package to my project' check that fans out to deps.dev and bundlephobia. It explicitly differentiates this tool from siblings by naming the data sources and the exact question it answers, making it easy to select.

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 for common agent questions ('is X safe / popular / small' or 'what does adding lodash cost me'). It also gives an explicit alternative: non-npm ecosystems like PyPI/Maven/Cargo/Go should fall under deps.dev:version directly, preventing mis-selection.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds useful context by specifying the return fields (name, summary, record_count, owner/org, url) and chaining to query_layer/layer_info. It does not contradict annotations. No extra behavioral traits like rate limits are mentioned, but the safety profile is covered.

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

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

The description is two sentences that are clear and front-loaded. The first sentence states the action and scope; the second details outputs and integration. No unnecessary information, every word earns its place.

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

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

For a simple tool with 3 optional parameters, no required parameters, and no output schema, the description fully explains what it does, what it returns, and how the output connects to other tools. The absence of an output schema is compensated by listing the specific return fields. Complete for its complexity.

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

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

Schema description coverage is 100%, with each parameter (query, limit, org_id) already well-documented. The description adds no additional parameter-specific meaning beyond referring to 'keyword' search, which aligns with the query parameter. Baseline 3 per rubric is appropriate.

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

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

The description uses a specific verb ('Search') and identifies the exact resource ('Washington DC GIS open geospatial datasets') with examples (parcels, zoning, etc.). It also distinguishes from sibling tools by stating the output URL is meant for query_layer / layer_info, making the tool's role in a pipeline clear.

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

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

The description implies when to use this tool (to find datasets by keyword) and provides guidance for downstream usage ('pass that url to query_layer / layer_info'). However, it does not explicitly state when not to use it or name alternatives for dataset discovery, so it misses the full 'when-not' clarity.

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

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

Annotations already mark it read-only and idempotent, but the description adds critical behavioral details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap, and truncation flag. It also discloses that offsets enable verbatim quote verification, which is useful for the agent.

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

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

The description is front-loaded with the main verb and resource, then adds use-case, pairing, and technical detail in a logical order. Every sentence contributes new information—no filler or repetition of the schema.

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

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

The description covers the return format (passages, offsets, scores), the truncation behavior, the pairing with a sibling tool, and the algorithmic details. Without an output schema, this is sufficient for an agent to understand what to expect from the tool and when to invoke it.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond property names: it clarifies that 'text' must be a previously fetched record, gives query examples, and explicitly ties the char cap to the 'text' parameter. This extra context helps the agent construct correct calls.

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

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

The description opens with 'Semantic search INSIDE a fetched record', a specific verb+resource that clearly distinguishes it from siblings like ask_pipeworx_grounded. It also states the return values (top-N passages with offsets and similarity scores), making the tool's purpose unambiguous.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and pairs with ask_pipeworx_grounded, explaining the workflow: fetch with the gateway, then ground over relevant passages. This gives clear when-to-use context and an alternative for broader grounding.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true), the description adds important behavioral traits: requiring a Pipeworx OAuth account (anonymous + BYO cannot persist), the always-on feed with retrieval methods, SMS phone verification with a 10/day cap, and the return of a new subscription id. These details help the agent understand side effects and constraints beyond the basic mutability flag.

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 ('Create a proactive monitoring subscription'), then efficiently packs requirements, types, and delivery channels into a few dense sentences. It avoids fluff and every sentence carries information. A more structured bullet format could improve scannability, but the text is reasonably concise for the complexity.

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

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

Given the tool's moderate-high complexity (3 parameters, nested objects, multiple subscription types, no output schema), the description covers essential aspects: purpose, return value, auth requirement, supported types with examples, delivery channels, and specific constraints. It omits the webhook delivery channel (though the schema describes it in detail) and does not explain the return object beyond the id, but the rich schema compensates. Overall, it is nearly complete but with a few gaps.

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

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

The schema has 100% description coverage, so the baseline is 3. The main description largely restates the schema's parameter details but adds a useful semantic example ('items:["5.02"] = officer change') that clarifies the meaning of a specific value. Overall, the description contributes marginal extra meaning beyond the schema, so a 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 specific action: 'Create a proactive monitoring subscription to a live-data event stream.' It names the return value (new subscription id) and lists supported types, making the tool's purpose unmistakable and distinguishing it from sibling tools like list_subscriptions and unsubscribe.

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

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

The description provides clear context for when to use the tool: to set up proactive monitoring. It also notes prerequisites (OAuth account) and explains that the feed channel is always on and can be pulled via recent_alerts or a direct endpoint, implying these are alternatives for reading data rather than subscribing. However, it does not explicitly mention sibling tools or when not to use it, 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 disclose read-only, idempotent, non-destructive behavior, so the bar is lower. The description adds useful context about the return format (category-bucketed example questions drawn from the live catalog) and the onboarding purpose, going beyond what annotations convey.

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

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

The description is relatively long but well-structured, front-loaded with natural-language example queries, then explaining purpose, return value, and usage. Each sentence contributes context; while it could be trimmed, the onboarding nature justifies the detail.

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

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

Given the simple parameter schema, strong annotations, and no output schema, the description is complete enough. It explains what the tool returns, how to call it with or without arguments, and when to use it. No critical gaps for an agent to select and invoke it correctly.

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

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

The schema already provides 100% coverage for the single optional `topic` parameter, including its meaning and examples. The description essentially repeats the same information ('pass topic to focus', examples like 'finance', 'pharma'), adding no new semantics beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly identifies the tool as an onboarding entry point that returns category-bucketed example questions with exact tool + argument shape. It distinguishes itself from siblings by explicitly telling the agent to 'Use this FIRST when you do not yet know what Pipeworx can do for you' and names the meta-tools it teaches.

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

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

The description provides clear when-to-use guidance ('Use this FIRST when you do not yet know what Pipeworx can do') and mentions alternatives (ask_pipeworx, entity_profile, compare_entities) to learn about. However, it does not explicitly state when NOT to use it, making this a strong 4 but not 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?

The description adds important behavioral details beyond annotations: ownership enforcement ensures only the user's own subscriptions can be canceled, and the row is deactivated rather than deleted, preserving historical events. This complements the idempotentHint and destructiveHint=false annotations, providing concrete context about the mutation's impact.

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

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

The description is two concise sentences with a clear action-first structure. Every sentence provides meaningful information without redundancy, making it easy for the agent to parse.

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

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

For a single-parameter tool with no output schema, the description covers the main behavior, ownership rules, and the side effect on historical data. It lacks explicit error handling details, but the given context is sufficient for a simple cancel operation.

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

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

The schema already fully describes the 'id' parameter as the subscription id returned by subscribe, with 100% coverage. The description does not add further parameter-specific details, so it remains at the baseline for high schema coverage.

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

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

The description clearly states the action ('Cancel a subscription') and the object ('by id'), which differentiates it from sibling tools like 'subscribe' and 'list_subscriptions'. It also specifies the ownership constraint and the soft-deactivation behavior, adding further clarity.

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 context that this tool cancels subscriptions and enforces ownership, implying it is the appropriate tool for unsubscribing from alerts. However, it does not explicitly mention alternatives or when not to use it, such as a hard-delete scenario. The reference to recent_alerts clarifies the side effect, but no explicit when/when-not 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?

Beyond the readOnly/openWorld/idempotent annotations, the description discloses the internal dual-path behavior (SEC EDGAR XBRL vs grounded pipeline), enumerates the possible verdicts, and explicitly warns that could_not_verify carries verification_error and 'is NOT evidence for or against the claim, and must not be shown as one.' This is valuable behavioral context not inferable 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 long but every sentence serves a purpose: trigger phrases, use case, routing logic, return values, error caveat, and efficiency note. It is well-structured and front-loaded with the tool's identity.

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

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

Despite lacking an output schema, the description enumerates all verdict variants, describes the return value ('grounded or structured actual value with pipeworx:// citation'), and explains error cases. It covers enough for an agent to confidently invoke and interpret results.

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

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

Schema already provides thorough descriptions for both parameters (claim with examples, tolerance_pct with its override behavior and default). The description does not add parameter-specific details beyond the schema, but it reinforces the concept of percent-delta grading. With 100% schema coverage, baseline 3 is appropriate.

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

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

The description opens with explicit trigger phrases ('Is it true that…' / 'fact check' / 'verify the claim that…') followed by a clear verb+resource: 'natural-language claim verification against authoritative sources.' It distinguishes from siblings by framing itself as a specialized fact-checking tool rather than a generic search or Q&A tool.

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

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

States 'Use whenever the agent needs to check whether something a user said is factually correct.' It also clarifies routing for company-financial claims vs other facts, and notes it replaces 4–6 sequential calls, giving a clear deployment signal.

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