Arcgis Eastbatonrouge

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

Beyond annotations, the description adds key behavioral details: the default model is free, probing Anthropic requires a BYO key with direct costs, and the return structure includes per-model fields plus a combined view. These complement the readOnlyHint and idempotentHint without contradiction.

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

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

Three sentences, front-loaded with the primary function, efficient and information-dense. Every sentence earns its place: what it does, default behavior and key parameter nuance, plus return and use cases.

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

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

The description is complete for a tool with rich annotations and full schema coverage: it explains the purpose, default behavior, BYO key cost nuance, return shape (since no output schema exists), and relevant use cases. Minor gap: doesn't mention any limitations or model count variability, but adequate.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra meaning by naming the default model (Workers AI Llama-3.3-70b) and clarifying the cost implication of _apiKey, which goes slightly beyond the schema's technical notes.

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 verb (probe), resource (LLMs), and outcome (visibility score per model 0-100). It distinguishes itself from sibling tools like ask_pipeworx by focusing on what models know and scoring it, rather than just querying.

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: AI-marketing audits, pre-launch brand checks, competitive monitoring. However, it does not mention when not to use it or name specific alternatives, 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 provide readOnlyHint=true, openWorldHint=true, idempotentHint=true. The description adds valuable context beyond annotations: routes to 5,347 tools across 1,393 sources, fills arguments automatically, returns pipeworx:// citation URIs, works on every tier in one fast call, and notes it handles news/breaking coverage. Minor omission: no mention of rate limits or latency variance across the routed tools.

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 front-loaded with the most important guidance (PREFER OVER WEB SEARCH) in the opening line. Examples are concrete and useful. Slightly long with the trailing news-feed note, but every sentence earns its place given the tool's broad routing responsibilities — nothing is redundant.

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?

Comprehensive for a single-string-parameter router tool. With 100% schema coverage, six alias params all documented, no output schema needed (returns structured answers with citations as described), and strong annotations, the description fully covers use cases, exclusions, escalation paths, and behavioral characteristics. No output schema means the description's mention of 'structured answer with citation URIs' 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?

Schema coverage is 100% and every parameter is an alias for 'question'. The description contributes the core semantic guidance: explaining that the single question string is a natural-language query and that the tool auto-fills other arguments ('fills arguments'). However, since all six params are identical aliases, the schema already conveys this; the description adds the auto-argument-filling behavior which is genuinely useful context beyond the schema.

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

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

Verb+resource+scope is explicit: 'routes the question to the right one of 5,347 tools' and returns structured answers with citations. It clearly states the tool covers authoritative data (SEC, FDA, FRED, USPTO, etc.) and distinguishes itself from web search and siblings like ask_pipeworx_grounded and deep_research.

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

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

Exceptionally explicit. States 'PREFER OVER WEB SEARCH', provides trigger phrases ('what is', 'look up', 'find'), gives concrete examples, declares 'START HERE for most questions', and names alternatives (ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for multi-part fan-out) with clear when-to-use conditions.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the read-only safety profile is already covered. The description adds meaningful context: that behavior may change when a candidate routing is under test, that it currently matches ask_pipeworx exactly, and the semantics of the beta status (no fallback, fully functional). This is strong value beyond annotations.

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

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

Three sentences conveying the beta status, current equivalence to the stable tool, usage instruction, and non-fallback clarification. Slightly wordy with the date and tool-count detail, but every sentence earns its place. Efficient and front-loaded.

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

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

For a beta variant of a known universal router with full schema coverage and read-only annotations, the description covers the key gaps: what beta means here, current state (no active candidate), and how to use it. It could mention versioning or when candidates activate, but the provided context is adequate for correct selection and use.

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% — the schema documents all 6 parameters and aliases (question accepts query, q, prompt, text, input). The description adds no parameter-specific semantics beyond pointing at the question input, which is the only functional parameter. Baseline 3 is appropriate since the schema carries the load.

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

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

The description clearly states this is the beta version of ask_pipeworx, an identical universal router with the same tools, arguments, and response shape. It names the resource (universal router) and distinguishes it from the stable sibling ask_pipeworx, though the distinction is momentarily absent (no candidate active).

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

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

The description explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and explains the evaluation context (results compared against stable router to decide merges). It also clarifies it's a full working router, not a fallback or stub, which prevents misuse.

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

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

Annotations already declare readOnlyHint=true, openWorldHint, idempotentHint, destructiveHint=false, so the safety profile is covered. The description adds substantial behavioral value: the refusal mechanism with enumerated refusal_reason values, the verbatim-evidence guarantee, the extra-cost warning, and the deterministic 'only what the tool result contains' constraint. This is rich disclosure beyond the annotation baseline.

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

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

Well-structured: front-loads the core value proposition, explains the mechanism, provides the refusal contract, lists use cases, and closes with the cost trade-off. Slightly dense — the parenthesized refusal_reason enum inside the success path paragraph adds complexity — but every sentence earns its place and the flow is logical.

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 question tool with rich annotations and full schema coverage, the description is complete: it covers success/refusal return shapes, when to prefer this vs the sibling, cost implications, and the anti-hallucination contract. No output schema exists, but the description compensates by explicitly documenting both return variants. Effectively complete for its complexity class.

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

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

Schema coverage is 100%, so all 6 params are documented as aliases for question, giving the schema heavy lifting. The description additionally clarifies that the parameter is a natural-language question and references the accepted aliases (query, q, prompt, text, input), which confirms and reinforces the alias semantics. Small incremental value over schema but coherent.

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 a specific verb+resource ('hallucination-resistant answer mode...extracts the answer using ONLY what the tool result contains') and explicitly distinguishes it from its sibling ask_pipeworx. It names the exact behavior (grounded extraction with refusal mechanism) and return structure. The scope, mode nature, and relationship to the sibling are all unambiguous.

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

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

Explicitly states when to use ('whenever an answer will be quoted, cited, or acted on') with concrete example domains (financial verdicts, legal claims, medical lookups, public statements). Clearly names the alternative (ask_pipeworx) and gives the trade-off ('costs one extra LLM call — prefer ask_pipeworx for casual lookups'). This is model usage guidance.

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

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

Annotations already declare readOnly/openWorld/idempotent, and the description adds extensive context: resolver contract with market_match_confidence, low-confidence short-circuit suppressing analysis, closed-market handling, news fallback behavior, and cancellation-rule risk. This far exceeds what annotations provide and includes safety caveats to prevent misuse.

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 long, every section earns its place: classifiers, fan-out examples, response shapes, resolver contract, parent_event, news fields, safety, and resolution-rule risk. The use of headers and concrete examples makes it highly structured and information-dense, not verbose.

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

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

With no output schema, the description must explain return values, and it does comprehensively: result.market fields, result.analysis with model probability/edge warnings, result.evidence, parent_event, status codes, and cancellation rules. It also covers failure/edge cases, making it complete for a complex tool.

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

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

Schema coverage is 100%, but the description adds real value: it explains that 'market' accepts slug, URL, or question text; 'depth' quick vs thorough is detailed ('quick = 2-3 evidence sources, thorough = full fan-out'); and 'include_raw' describes size trade-offs and use cases. This goes beyond the schema's field descriptions.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes from sibling tools by focusing on data aggregation for bet analysis, with explicit classifiers and fan-out examples.

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: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also gives depth parameter guidance. However, it does not explicitly name alternative tools or provide a 'when-not' directive, so it falls short of a 5.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) already establish safety, but the description adds non-obvious behavior: it pulls specific metrics (10-K revenue/net income/cash/debt for companies; FAERS/approval/trial counts for drugs), sorts results by primary metric, and returns paired data with citation URIs. 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 concise given the tool's complexity, front-loaded with trigger phrases and usage guidance. Every sentence adds value (trigger phrases, preference directive, data sources, sorting behavior, return shape, efficiency claim). No 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?

The description covers both entity types, their data sources, fiscal year nuances, sorting behavior, and return value format (paired data + citation URIs). Given no output schema, this sufficiently explains what to expect. It addresses edge cases (off-calendar fiscal years) and performance (replaces 8–15 lookups), making it complete for an agent to select and invoke.

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

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

Schema descriptions are thorough, giving full coverage (100%) of type and values. The description enriches these by specifying what each type retrieves (e.g., 'type="company" pulls LATEST 10-K revenue + net income + cash + long-term debt') and clarifies the values format (tickers/CIKs vs drug names). This goes beyond the schema, though the core parameter names are already well-described.

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

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

The description explicitly states the tool performs side-by-side comparisons of 2–5 companies or drugs in one parallel call, using specific trigger phrases like 'X vs Y' and 'which is bigger'. It clearly distinguishes itself from sequential single-pack lookups and mentions it replaces 8–15 sequential calls, setting it apart from sibling tools like entity_profile.

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 guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also clarifies when to use company vs drug types and notes off-calendar fiscal year handling. This gives clear context for selection and excludes alternatives.

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

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

Extremely rich behavioral disclosure beyond annotations: explains the hop/gap-recovery iteration, contradictions[] scan, semantic excerpting behavior (not head-truncated), timing expectations (15-60s, up to 90s for thorough), the gaps[] honesty mechanism, and citation format (pipeworx:// with hop field). Annotations already declare readOnlyHint and this substantially extends them.

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

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

The description is very long (a full paragraph block) and packs a large amount of information, but it's front-loaded with the critical account requirement first and organized by topic. While dense, every sentence carries unique information — no filler. Slightly loses points for length making it harder to scan quickly.

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

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

For a complex 2-parameter tool with no output schema, the description compensates fully: covers account requirements, pricing, fallbacks, timing, iteration behavior, output format details (gaps[], contradictions[], hop field, citation_uri), and source types. The completeness is exceptional given the tool's complexity and the absence of an output schema.

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

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

Schema coverage is 100% so baseline is 3, but the description adds significant value on the depth parameter by explaining what each enum value does (quick=3 facets single hop, standard=5 adds gap-recovery + contradictions, thorough=8 paid adds iterative lead-chasing) beyond the schema's field descriptions. The question parameter is self-evident.

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 this is grounded multi-source research across 1,393 structured data sources, routing to 5,347 tools in parallel. It's distinguished from siblings by explicitly contrasting with ask_pipeworx (single lookup) and naming the alternatives. The verb+resource+scope is highly specific.

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

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

Excellent guidance: explicitly states when to use (broad/multi-part questions over structured data), when NOT to use (breaking/colloquial current-news topics should go to ask_pipeworx), notes account requirements with paid-tier caveats, and provides the exact fallback tool (ask_pipeworx) when not signed in.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral details: returns top-N most relevant tools with names, descriptions, full input schemas, curated examples, and results ready to call directly with no second schema lookup. This goes beyond the annotations, though it omits rate limits or edge cases.

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

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

The description is moderately sized but front-loaded with the core purpose. It efficiently covers what the tool does, when to use it, and what it returns. The domain list, while exhaustive, serves to illustrate scope and each sentence adds value.

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

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

Given the tool's complexity (6 params, all aliases) and no output schema, the description is reasonably complete: it explains the return format, usage scenarios, and provides concrete examples of queries via the schema. It doesn't explain relevance ranking, but that's not necessary for usability.

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 and alias clearly documented in the input schema. The description does not add significant parameter-specific meaning beyond what the schema already provides; it only aligns with the query concept and mentions top-N which corresponds to the limit parameter. 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 finds tools by describing the data or task, with a specific verb and resource. It distinguishes itself from sibling domain-specific tools by positioning itself as a meta-search tool for discovering which tools exist, reinforced by 'Call this FIRST'.

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

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

Explicit usage guidance is provided: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This clearly indicates when to use this tool versus alternatives.

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

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

The description adds substantial behavioral context beyond the read-only/idempotent annotations: it fans out across multiple sources, uses a parallel call pattern, describes fallback behavior (GDELT→GNews), and discloses the patents API sunset and soft-fail behavior. This goes well above the basic annotation signal.

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

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

Although it is a long paragraph, every clause carries useful information: example user phrasings, an explicit preference rule, the fan-out source list, and the exact fields returned. It is dense but not wasteful, and it is front-loaded with the most actionable 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?

There is no output schema, so the description takes on the burden of explaining return values—and it does so explicitly, listing CIK, company name, recent filings with URIs, fundamentals, patents, news, and LEI. It also covers edge cases like unsupported names and soft-fail behavior, making it complete for an agent.

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

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

The input schema already covers both parameters with 100% description coverage, including examples and the note that names are not supported. The description reinforces this but does not add significant new parameter-level semantics 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 is highly specific: 'full cross-source profile of a US public company in ONE parallel call' clearly names the resource and action. It also distinguishes itself from chaining single-source lookups and explicitly references sibling 'resolve_entity' for name resolution.

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 directive: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also states the alternative for name-only inputs: 'use resolve_entity first if you only have a name.'

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 readOnlyHint=false, so the destructive nature is known. The description adds context about clearing sensitive data and pairing with remember/recall, but does not go beyond annotations to describe irreversibility, error behavior, or side effects. It does not contradict annotations.

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

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

The description is three short sentences, each serving a distinct purpose: stating the function, giving usage conditions, and naming related tools. It is front-loaded with the primary action and contains no 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?

The tool has a single parameter, a complete input schema, and annotations covering safety. The description covers purpose, when to use, and related tools. No output schema is provided, so no return value details are needed. It is fully sufficient for an agent to select and invoke the tool.

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

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

Schema coverage is 100%: the only parameter 'key' has a description ('Memory key to delete'). The tool description itself does not add any additional semantic detail 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 opens with 'Delete a previously stored memory by key,' which clearly states the action (delete) and the target (previously stored memory by key). It distinguishes the tool from siblings by mentioning 'Pair with remember and recall,' placing it within the memory management family.

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: 'when context is stale, the task is done, or you want to clear sensitive data.' It also references companion tools ('Pair with remember and recall'), giving context for alternatives, though it does not explicitly state when not to use the tool or name direct alternatives.

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

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

With strong annotations (read-only, idempotent, non-destructive), the description adds valuable process details: it fetches the page, extracts title/description/key links, and emits standard markdown. It does not mention limits like rate limits or error handling, but the annotations cover safety.

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

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

Two sentences, front-loaded with the core purpose, followed by process and use cases. Every sentence adds value with no redundant 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?

The description explains the output format (single text blob, llms.txt markdown) despite lacking an output schema. It covers intended usage and behavior adequately for a relatively simple tool, but could mention internet access requirements or failure handling.

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

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

Both parameters are fully documented in the schema (URL and max_links). The description adds context about 'any URL' and production-ready output, but does not provide new semantic details 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?

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the action, resource, and outcome. It distinguishes itself from sibling tools by focusing on file generation rather than visibility checking or research.

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

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

The description provides explicit use cases (indexing a client's site, drafting for own project, auditing competitors) that signal when to use it. However, it does not mention alternatives or when not to use it, leaving a small gap.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds value by detailing exactly what the tool returns (fields, geometry type, record count, capabilities). It does not mention network/auth/error behavior, but the annotations lower the burden and the read-only nature is well 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 a single, information-dense sentence that front-loads the action ('Get') and resource ('ArcGIS Feature/Map Service layer's schema'). Every word contributes meaning; no filler or redundancy.

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

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

For a simple one-parameter, read-only tool, the description fully covers what it does and what it returns. The input schema covers the parameter, annotations cover safety, and the description explains the output components since there is no output schema. 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?

The input schema has 100% description coverage for the single 'url' parameter, including an example. The tool description adds no additional parameter-level semantics beyond restating that it is a URL. With high 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 clearly states the tool's purpose: 'Get an ArcGIS Feature/Map Service layer's schema by url' and enumerates the specific output fields (fields, geometry type, total record count, capabilities). This is a specific verb+resource combination that distinguishes it from siblings like query_layer which would fetch 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 provides clear context: use this when you need schema information for a layer URL. It does not explicitly name alternatives or exclusions, but the mention of 'schema' makes it distinct from data-querying tools. No explicit when-not-to-use guidance is given, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is known. The description adds behavioral context by specifying it returns only the caller's own subscriptions and the exact fields included, without contradicting the annotations.

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

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

The description is two sentences, front-loaded with the core purpose, followed by return fields and usage guidance. Every sentence adds value with no redundancy.

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

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

The description covers purpose, scope, return fields, and usage recommendations. With a simple schema and robust annotations, it is sufficient for correct invocation, even though pagination or ordering details are not mentioned.

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

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

Schema coverage is 100% with the include_inactive parameter fully described in the input schema. The description does not add new parameter-specific meaning but aligns with the schema, 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 the tool lists the caller's active subscriptions with a specific verb and resource. It distinguishes itself from sibling tools like subscribe and unsubscribe by focusing on listing, and enumerates the exact return fields.

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

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

The description explicitly recommends using the tool to review current monitoring before adding more, and to find an id to cancel. This gives clear context for when to use it, though it does not directly name alternative tools.

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

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

The description discloses rate-limiting ('Rate-limited to 5 per identifier per day') and quota behavior ('doesn't count against your tool-call quota'), which are not captured in the annotations. It also notes that feedback is reviewed daily and affects the roadmap, adding behavioral context beyond what the schema/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 four sentences, each with a distinct purpose: what it does, when to use it, how to write feedback, and cost/rate limits. No redundant information, and it is front-loaded with the core purpose.

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

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

The tool has a nested context object and no output schema, but the description covers the essential use cases, message formatting, and constraints. It could mention what happens after submission, but for a simple feedback tool the description is sufficiently complete.

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

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

With 100% schema coverage, the schema already describes all parameters. The description adds value by instructing how to frame the message ('Describe the issue in terms of Pipeworx tools/packs') and implying that context fields should reference specific tools/packs, complementing the schema's definitions.

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

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

The description clearly states the tool's function: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses a specific verb ('tell') and resource ('Pipeworx team'), and the use-case examples (bug, feature/data_gap, praise) distinguish it from sibling research/query tools.

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

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

The description explicitly says when to use it: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides exclusions ('don't paste the end-user's prompt') and practical context (rate limit, free, doesn't count against quota).

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 and idempotent hints, but the description adds substantial context: data source (CF analytics-engine), no PII, caching (5min-1h), and the self-aggregating nature. This goes beyond the annotation metadata and helps the agent understand response characteristics and 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?

The description is concise and well-structured: a lead sentence stating the purpose, a list of use cases, and a compact note on data provenance/caching. Every sentence adds information without repeating schema or annotations.

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

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

For a simple single-parameter read-only tool, the description covers output (top tools, packs, counts), usage context, caching behavior, privacy, and data source. This is complete enough for an agent to decide when to call the tool and what to expect in the response, even without an output schema.

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

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

The schema fully documents the window parameter with an enum and description (100% coverage). The description adds interpretive value by explaining that shorter windows surface hot trends while longer windows show steady-state demand, which is beyond the schema's literal definition.

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

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

The description clearly states what the tool does: it returns trending tools, packs, and call volume on Pipeworx. This distinguishes it from query/research tools like ask_pipeworx or discover_tools, 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?

The description lists three explicit use cases (hot data sources, canonical tool confirmation, alignment with agent needs) and explains window trade-offs. However, it does not explicitly mention when not to use the tool or name alternative tools, so it falls just 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?

The description is highly transparent, disclosing internal filters (SEMANTIC ANCHOR, PARTITION FILTER), the fill check against live CLOB depth, and the response fields. It even warns 'realizable_edge_pp ≤ 0 ... do not trade it', which goes far beyond the annotations that only state read-only/idempotent.

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

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

The description is long but front-loaded and well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every section adds operational detail, though the all-caps headings and dense paragraphs could be slightly more 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?

Even without an output schema, the description explicitly lists the response structure: opportunities[] with gap_pp, suggested_trade, reasoning, and the partition_check object in event mode. It covers edge cases, filters, fill-check logic, and references companion tools, making it contextually 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?

Both schema properties have descriptions, but the tool description adds concrete examples ('fed-decision-may-2026'), notes that full Polymarket URLs are accepted, and explains the behavioral differences between passing event and topic, plus the no-arg behavior. This significantly supplements the schema.

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

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

The description opens with a precise verb and resource: 'Find arbitrage opportunities on Polymarket' and specifies the method (monotonicity violations + partition-sum checks). It clearly distinguishes the two modes (event vs topic) and the no-arg trending_scan, setting it apart from sibling tools like polymarket_edges.

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

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

The description explicitly prescribes when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It also names an alternative: 'For custom sizing use polymarket_fill_risk.'

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

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

Beyond the annotations (readOnly, idempotent, openWorld), the description discloses extensive behavioral details: the response segmentation under by_segment, edge calculation net of slippage, Kelly fractions capped at 0.25, the 24h-move warning, partition overround design with placeholder-slug filters, the 'rare-by-design' nature of concentrated_longshot, and the 1h caching keyed on knobs. It even explains why partition arbs return kelly_fraction_half=0 at the parent level, giving callers essential internal knowledge.

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 highly detailed and systematically structured with all-caps section headers (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL), making it scannable. However, it is very long and includes some duplication of schema parameter descriptions. While every sentence adds useful information, the sheer length makes it less concise than ideal for an agent to parse quickly.

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

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

Given the tool's complexity (9 optional parameters, no output schema), the description is remarkably complete. It thoroughly explains the response structure (by_segment, fed_candidates/fed_note, _diagnostics), the reasoning behind filters, and even the caching behavior. Callers would have a clear mental model of what to expect and why certain segments might be empty, making this a fully self-contained description.

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

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

The input schema already provides 100% parameter coverage with detailed descriptions, so the baseline is 3. The tool description adds meaningful context beyond the schema, such as the 'TRADEABLE-EDGE KNOBS' overview and the critical explanation for min_partition_leg_kelly (that partition arbs always return parent-level kelly=0, so this knob filters per-leg instead). This extra context justifies a 4.

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

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

The description opens with a specific verb+resource+outcome: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It further clarifies the intended use case ('Built for "what should I bet on today"'), clearly distinguishing it from sibling tools like polymarket_arbitrage or polymarket_edge_tracker by focusing on edge discovery from Pipeworx data.

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

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

The description provides clear context for when to use the tool: for daily discovery of betting opportunities without paging hundreds of markets. It also gives detailed guidance on knobs (e.g., min_liquidity/max_spread_pp to drop unrealizable edges) and a caveat about Fed bets being unreliable. However, it does not explicitly name alternative tools or state when NOT to use this tool in favor of a sibling, 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?

The description adds substantial behavioral detail beyond the annotations: history is bounded by a 60-day snapshot TTL, snapshots have gaps when polymarket_edges doesn't run, and decay is computed from daily closes rather than intraday. This discloses important limitations and data characteristics that are not visible from annotations alone.

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

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

The description is well-structured with explicit 'Args' and 'RESPONSE' sections, front-loading the core purpose. Every sentence adds meaningful detail, and the formatting improves scannability despite the length.

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

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

Given the complexity of the tool and lack of an output schema, the description is remarkably complete. It details the full response structure (tracked, expired, snapshot_dates), explains edge cases (gaps, TTL limits), and clarifies calculation methods, leaving little ambiguity for the agent.

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

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

Schema coverage is 100% with parameter descriptions, but the tool description adds extra context: days has a default of 14 and max 30 (schema says clamp 2-30), and window is explained as the snapshot family with examples. This enhances understanding of how the parameters affect the query.

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.' It answers specific questions ('how long has this edge existed and is it shrinking?') and contrasts fresh vs. old edges, distinguishing it from sibling tools like polymarket_edges which likely focuses on current edges.

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

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

The description provides strong usage context by explaining when this tool is valuable: to assess edge persistence and decay, noting that 'a fresh wide edge and a 3-week-old wide edge are different trades.' While it doesn't explicitly name alternatives or exclusions, the context makes it clear when to use it relative to other Polymarket tools.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description goes far beyond no-ops by detailing exact operational behavior: it 'walks the ladder,' returns specific fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd), and warns about the critical risk that 'partial basket fills convert an arb into an unhedged directional position.' This adds substantial context about execution mechanics and failure modes.

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

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

The description is long and dense, but every sentence contributes necessary detail for two distinct modes. It is logically structured: starts with core purpose, then REQUIRES, then single-market details, then basket details, then usage guidance. While not as concise as a two-liner, the complexity of the tool justifies the length. A minor deduction for lack of formatting (single paragraph block) that makes it harder to scan.

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

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

There is no output schema, so the description carries the full burden of explaining return values. It enumerates all key output fields for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict; theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs[], max_clean_notional_usd, forced_directional_risk). It also covers edge cases like thin books and forced directional risk, making it complete for agent decision-making.

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

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

Schema description coverage is 100%, so baseline is 3, but the description adds significant meaning beyond the schema. For example, it clarifies that size_usd means 'max spend on buys, target proceeds on sells' in single-market mode, and 'settlement notional S (shares per leg)' in basket mode. It also explains side defaults per mode ('auto from partition sum') and the dual meaning of market vs event as mode selectors.

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 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' which is a specific verb+resource+scope. It clearly distinguishes itself from siblings like polymarket_arbitrage and polymarket_edges by focusing on execution/fill risk rather than theoretical edge discovery. The usage directive 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' further differentiates 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 explicitly states when to use this tool ('USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500') and provides mode-specific guidance (SINGLE-MARKET vs BASKET). It also explains prerequisites ('REQUIRES one of market or event') and default behaviors, giving the agent clear actionable context for selecting it over alternatives.

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

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

While annotations already indicate read-only, open-world, idempotent, and non-destructive behavior, the description goes much further by disclosing specific safety fields like compatibility_warning, temporal_alignment, and skipped_cross_type/subtype counters. It elaborates on failure conditions and the meaning of each warning, which is far beyond basic structured hints.

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

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

The description is long but exceptionally well-structured: it front-loads the core purpose, then organizes modes, response fields, safety fields, and a final caution. Every sentence adds operational or safety-relevant detail, and there is no repetition of schema content or filler. The use of capitalization and headings aids quick scanning.

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

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

For a complex tool with no output schema, the description provides a thorough account of the response format (leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters) and all edge-case behaviors. It also includes caveats about pre-mapped topics, giving an agent everything needed to correctly 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?

The schema already covers 100% of parameter descriptions, so the bar is baseline 3. The description adds meaningful context by explaining that topic shortcuts 'auto-fetch the matching event on each venue,' that explicit tickers 'override the topic-mapped side,' and by listing exact allowed topic values. This enriches the schema's dry property definitions.

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

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

The description opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' which is a specific verb-resource combination that immediately distinguishes it from siblings like polymarket_arbitrage or polymarket_edges. It also details two modes (topic shortcuts vs explicit tickers) and the response structure, leaving no ambiguity about the tool's function.

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

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

The description explicitly states when the tool is meaningful ('when the bet shapes are equivalent') and when it is not ('when they aren't the tool says so'), backed by the warning that 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable.' It also explains the two usage modes, serving as a practical usage guide.

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=true, idempotent=true, and destructive=false, so the safety profile is covered. The description adds that it returns attribute rows and geometry, plus hints on how to sample, which is beyond the structured annotations.

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

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

Two sentences, no wasted words. The first sentence packs in the resource, the operation, and the key parameters; the second sentence provides a concrete usage tip. Ideal length and front-loading.

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 6 parameters with full schema coverage and no output schema, the description covers the essential usage. It mentions return type (attribute rows and geometry) and a sampling strategy, leaving no major gaps for a query tool.

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

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

Schema description coverage is 100%, so parameters are fully documented in the schema. The description mentions SQL-like where, comma-separated out_fields, order_by, limit, and offset, but this only repeats schema details without adding new meaning beyond what is already present.

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/Map Service layer by URL, which is a specific verb and resource. It also ties usage to search_datasets, distinguishing it from sibling tools like layer_info or search_within.

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

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

The description implies this tool is used after search_datasets ('by its url (from search_datasets)'), providing a clear usage context. It also gives a practical sampling tip ('where="1=1" + out_fields="*"'), but does not explicitly exclude alternatives.

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

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

Annotations already declare read-only and non-destructive behavior. The description adds important scoping details ('Scoped to your identifier') and lifecycle information ('Pair with remember to save, forget to delete'), which go beyond the structured annotations.

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

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

Three sentences, each serving a distinct purpose: function, use case, and operational context. No redundant or filler content. Information is front-loaded with the primary action in the first sentence.

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 optional parameter, the description fully covers purpose, usage, scoping, and relationships to sibling tools. Return behavior is implied (value vs. list of keys). No output schema is present, but the description handles the necessary context.

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

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

Schema coverage is 100% for the single key parameter. The description reinforces the parameter's meaning by explaining the behavior when omitted and providing concrete examples of key values (target ticker, address, research notes), adding richness 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 states a specific action: 'Retrieve a value previously saved via remember, or list all saved keys.' It clearly identifies the resource (memory store) and distinguishes from sibling tools by mentioning remember and forget explicitly.

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: 'Use to look up context the agent stored earlier' and mentions pairing with remember/forget. However, it does not explicitly state when not to use the tool or list specific alternative tools beyond the direct siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds the significant behavioral detail that setting mark_read:true flags events as read, affecting subsequent calls. It also discloses the output fields (source, citation_uri, raw event payload) and that the same feed exists at an external URL. These go beyond the annotations and provide valuable behavioral transparency.

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

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

The description is compact and front-loaded with the core action. It covers retrieval, return fields, filters, mark_read behavior, polling suitability, and an alternative endpoint without any redundant or filler sentences. 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 no output schema and all-optional parameters, the description covers all essential aspects: what the tool returns, how to filter, the read-marker side effect, and the alternative HTTP access. Combined with annotations, this gives an agent a complete picture 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 describes all 5 parameters with 100% coverage. The description adds a concrete example for type ("sec_8k"), clarifies that type and since can be combined, and explains the effect of mark_read on future calls. This provides modest additional meaning beyond the schema.

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

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

The description opens with 'Pull fired events from your subscription feed', a specific verb and resource, and goes on to define the return content. It clearly distinguishes itself from sibling tools like list_subscriptions or recent_changes by focusing on fired alerts with optional filtering and mark_read semantics.

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

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

Provides clear context that this is for retrieving recent alerts and states 'Polls work fine', implying it is suitable for polling. It also points to an alternative REST endpoint for scripts/dashboards. However, it does not explicitly compare with sibling MCP tools, so it lacks exclusionary guidance but gives enough context for typical use.

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

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

Beyond the safe read-only annotations, the description discloses fan-out behavior to SEC EDGAR, GDELT→GNews fallback logic, USPTO sunset soft-fail, and the return structure (changes[] grouped by source + total_changes + citation URIs). This is rich behavioral context that annotations 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 dense with useful information and front-loaded with user intent examples. While somewhat long, every sentence earns its place by conveying functional details or alternatives.

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

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

Given the tool's complexity (multiple data sources, fallback, failure modes) and lack of output schema, the description fully explains return value shape, source-specific behavior, and the appropriate alternative tool, leaving no critical gaps.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by providing concrete examples for 'since' (ISO date vs '7d','30d','3m','1y') and clarifying that 'value' accepts ticker or zero-padded CIK, and 'type' is restricted to 'company'.

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

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

The description clearly states the tool provides a 'change feed for a company in the last N days/weeks/months' with specific verbs and resources, and explicitly distinguishes itself from sibling tools like entity_profile. The trigger examples ('What's new with X') make the purpose immediately graspable.

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

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

It provides clear when-to-use guidance through natural language trigger phrases and explicitly names the alternative ('Use entity_profile instead when you want the static profile...'), making the usage boundary unambiguous.

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

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

Annotations indicate idempotent, non-destructive write; description adds important behavioral context: key-value storage, identifier scoping, and 24-hour retention for anonymous sessions. This goes beyond the structured annotations to clarify real-world behavior.

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

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

Four sentences, front-loaded with the core action, then usage guidance, storage details, and sibling relationships. No unnecessary words.

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

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

For a two-parameter write tool with no output schema, the description covers all critical aspects: purpose, usage timing, persistence behavior, and pairing with recall/forget. The schema covers parameter syntax, so the description is fully 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 both parameters with examples (100% coverage), and the description adds the key-value storage context and identifier scoping. The examples in the description largely mirror the schema descriptions, so it adds modest value beyond the schema.

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

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

The description uses a specific verb ('Save data') and identifies the resource ('data the agent will need to reuse later'), and explicitly differentiates from siblings recall and forget. It is clear and unambiguous about the tool's function.

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

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

Provides explicit when-to-use guidance ('Use when you discover something worth carrying forward') with concrete examples, and contrasts with recall and forget. Also covers persistence differences for authenticated vs anonymous sessions.

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 meaningful behavioral context beyond the annotations: it discloses internal cascading lookups, auto-disambiguation, and specific return fields with citation URIs. Annotations already establish read-only and idempotent behavior, but the description enriches this with practical details like accepting multiple input formats.

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

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

The description is efficiently structured with example queries up front, a clear 'SUPPORTED TYPES' section, and a concluding note on internal cascading. It is somewhat long but every sentence contributes, making it appropriately sized 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?

The description compensates well for the lack of an output schema by detailing return fields for both entity types, including citation URIs. It covers input formats and the internal cascade behavior. Minor gaps include edge cases like ambiguous entities that fail auto-disambiguation, but overall it is sufficiently complete for a lookup 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 covers both parameters, but the description goes well beyond by explaining accepted input formats (ticker, CIK, name for company; brand/generic for drug), providing examples, and detailing exactly what each type returns. This adds significant semantic value.

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

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

The description clearly states the tool's purpose: resolving user-spoken names to canonical identifiers required by other tools. It provides concrete example queries and explicitly lists supported types (company, drug) with specific canonical identifiers returned, distinguishing it from sibling tools like entity_profile or compare_entities.

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

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

Strong usage guidance is given: 'Use FIRST whenever you have a name but need an ID.' It also notes that it replaces 2-3 manual lookups. However, it does not explicitly mention when not to use it or name alternative tools for other scenarios, so it falls slightly 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 indicate a safe read-only, idempotent operation. The description adds valuable context by revealing it makes multiple probes via ai_visibility_check, ranks results, and returns score/confidence/signal density. It does not contradict annotations.

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

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

Three concise sentences with no redundancy: core action, how it works, and return value. Front-loaded with 'Compare AI visibility across multiple entities side-by-side.'

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 states what is returned (ranked list with score, confidence, signal density). It also explains the underlying probe mechanism, making the tool's behavior understandable. The use case and entity semantics are covered.

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

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

Schema covers all 4 parameters with descriptions (100% coverage). The description adds little beyond saying the first entity is the subject and others are competitors, which is already in the schema. Baseline 3 is appropriate for full schema coverage.

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

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

The description uses a specific verb ('Compare') and resource ('AI visibility across multiple entities') and clearly distinguishes from siblings like ai_visibility_check by emphasizing side-by-side, ranked comparison. It also states the output (most/least recognized) 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 a clear use case ('competitive AI-marketing audits') with an example query. It implies the alternative (use ai_visibility_check for single entity) by stating it probes each entity with that tool, but doesn't explicitly name it as an alternative or state when not to use this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature. The description adds substantial behavioral context: fan-out across two services, potential 5-30s delay for first bundlephobia measurement, graceful partial failure via sources_failed, and details of the return payload. 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 longer than typical but well-structured: purpose first, then usage, then behavior/caveats. While slightly verbose, every sentence provides useful information and there is no filler. It earns its length for a composite tool with multiple external dependencies.

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 enumerates the return structure (summary block fields, per-advisory details, links, alternative versions) and explains error/partial-failure behavior. For a complex tool with two external data sources and potential timeouts, this is complete and self-contained.

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

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

Schema description coverage is 100% (both package and version are described). The description adds no new parameter details beyond the schema; the schema already covers scoped packages and default version. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states it is a composite 'should I add this npm package to my project' check, specifying the exact data sources (deps.dev and bundlephobia). It names specific outputs and distinguishes itself from sibling tools by being the dedicated npm dependency assessment 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?

Explicitly says 'Use whenever an agent asks...' and provides concrete example queries. It also gives an exclusion: NPM only in v1, and directs other ecosystems to deps.dev:version directly. This fully guides when to use and when not to.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds useful behavioral context by specifying exactly what is returned (name, summary, record_count, owner/org, Feature Service url) and how the result should be consumed. 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 two sentences, front-loads the core purpose, and includes a valuable downstream usage hint. Every phrase carries information; no filler or repetition of schema details.

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

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

Even without an output schema, the description explicitly lists the return fields and explains how the result is meant to be used. Given the simple keyword-search nature and rich annotations, the description provides enough complete context for an agent to select and invoke the tool.

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

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

Schema description coverage is 100%: query, limit, and org_id all have meaningful descriptions. The tool description itself adds no parameter-specific detail beyond 'by keyword', but the schema covers the parameters adequately, 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 states a specific action ('Search East Baton Rouge GIS open geospatial datasets') and a clear resource scope ('parcels, addresses, public works & planning'). It distinguishes itself from siblings by defining its output as dataset metadata plus a Feature Service url for downstream use with query_layer/layer_info.

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

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

The description provides clear context: use this to discover datasets by keyword, then take the returned `url` to query_layer or layer_info. It does not explicitly state when not to use it compared to search_within or other siblings, but the downstream chaining makes the intended flow clear.

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

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

Annotations already mark readOnly, idempotent, openWorld, and non-destructive, but the description adds substantial behavioral detail: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flagging, and return fields (character offsets and similarity scores). This goes beyond 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 dense yet focused. Every sentence carries purpose: it states the action, gives use cases, explains the algorithm and limits, and situates the tool among siblings. It is front-loaded with the core purpose and does not waste words.

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

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

For a tool with no output schema and moderate complexity, the description covers all critical aspects: what it does, when to use it, how it works under the hood, input constraints, output characteristics (passages with offsets and scores), and relationship to other tools. The agent receives enough context to invoke it correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds contextual meaning by specifying that 'text' is content already pulled (e.g., SEC 10-K body) and that 'query' is a natural-language question, with examples. It also clarifies the 'limit' parameter's purpose via 'top-N passages.' While the schema already documents constraints, the description enriches the practical understanding of each parameter.

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 verb and resource: 'Semantic search INSIDE a fetched record.' It distinguishes itself from siblings like search_datasets by focusing on already-fetched text and from ask_pipeworx_grounded by acting as a companion rather than a replacement. The use case (search within a document too large for the prompt) is 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?

It provides explicit when-to-use guidance: 'Use when the record is too big to cram into the prompt.' It also contrasts with ask_pipeworx_grounded by explaining how they pair together, and it mentions the value of character offsets for verification. Alternatives and complementary tools are both identified.

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 this is not read-only, is idempotent, and has open-world side effects. The description adds valuable context: OAuth requirement, subscription ID returned, SMS verification and daily cap, and the always-on feed behavior. No contradictions with annotations.

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

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

The description is dense but well-structured, front-loading the core purpose and then laying out types and delivery. Every sentence carries specific information, though it is slightly long. Schema details for webhook are also included, making it compact but efficient.

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

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

Given the complexity (3 parameters, nested objects, 5 types, multiple delivery options) and no output schema, the description covers the main behavior, return (subscription ID), and prerequisites. It omits some return details beyond the ID and error handling, but the main usage is fully fleshed out.

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

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

The input schema has 100% coverage, and the description enriches it with concrete examples for each type (sec_8k items, polymarket topic, fred series) and clarifies delivery options. This goes beyond the schema's enum and object descriptions.

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

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

The description states a specific verb and resource: "Create a proactive monitoring subscription to a live-data event stream." It clearly lists supported subscription types and delivery channels, which differentiates it from sibling tools like list_subscriptions, unsubscribe, and recent_alerts.

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

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

Provides clear context on when to use: requires a Pipeworx OAuth account, anonymous/BYO cannot persist, and explains how to consume feeds (recent_alerts or direct GET). It does not explicitly exclude alternative one-time query tools, but the proactive monitoring scenario is made clear.

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

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

Beyond annotations (read-only, idempotent), the description adds valuable behavior details: it returns category-bucketed examples from the live catalog, includes tool+argument shapes, behaves differently with no args vs a topic, and teaches meta-tool invocation. This enriches the agent's understanding of what the call does and what to expect.

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

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

The description is front-loaded with example phrasings and logically structured, but it is verbose (over 150 words) for a tool with one optional parameter. Some phrasings (e.g., 'give me ideas', 'show me examples') are repetitive; the content could be trimmed without losing essential 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?

The description fully explains what is returned (category list, tool+argument shape, live catalog), how to invoke with/without parameters, and when to use it first. It even orients the agent to meta-tools, making it a complete onboarding resource despite the absence of an output schema.

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

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

Input schema covers the only parameter (topic) with 100% detail, including allowed values and behavior when omitted. The description adds only a few redundant examples ('finance', 'pharma', 'betting') that do not exceed schema meaning, so baseline 3 applies.

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

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

The description precisely states the tool's role as an onboarding entry point that returns category-bucketed example questions with exact tool calls, distinguishing it from siblings like ask_pipeworx, discover_tools, and deep_research by focusing on 'what is worth asking' rather than answering or discovering broader capabilities.

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 instructs 'Use this FIRST when you do not yet know what Pipeworx can do for you' and mentions related meta-tools to learn. However, it does not explicitly state when NOT to use it or contrast with discover_tools, which could serve a similar onboarding role, so exclusion criteria are missing.

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

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

Beyond annotations (which indicate idempotent and non-destructive behavior), the description explicitly states that the row is deactivated and not deleted, preserving historical events via recent_alerts. This adds meaningful behavioral context about the operation's side effects and data retention.

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 short sentences each add distinct information: the action, ownership restriction, and the deactivation side effect. It is front-loaded and free of redundancy, making it highly readable and efficient.

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

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

Given the single parameter, no output schema, and sibling tools, the description covers the essential context: what happens to the subscription, who can perform it, and where historical data remains available. It is sufficiently complete for a simple mutation 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 fully documents the single parameter (id) with the same 'returned by subscribe' phrasing. The description adds nothing new about the parameter semantics beyond restating that it is a subscription id, 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 starts with the specific verb 'Cancel' and resource 'subscription', clearly stating the action. It distinguishes from sibling tools like subscribe, list_subscriptions, and recent_alerts by focusing on the cancellation action and its side effects.

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 about ownership enforcement and the deactivation behavior, which helps decide when to use this tool. It doesn't explicitly name alternatives but the context is sufficient for a straightforward unsubscribe action.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context: it uses structured SEC EDGAR+XBRL for financial claims with exact percent-delta math, and falls through to a grounded pipeline for any other claim, returning evidence and citation. It also enumerates the returned verdict types, which goes beyond annotations.

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

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

The description is dense but well-structured: it opens with trigger phrases, states purpose, usage guidance, pipeline details, and returns. Each sentence contributes value; no filler. Slightly long but justified by the tool's complexity.

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

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

Given the tool's complexity and lack of output schema, the description explains return values (verdict, actual value, citation, reasoning), routing decisions, and the efficiency advantage over sequential calls. It doesn't explain failure modes or details of 'inconclusive', but is otherwise complete for use.

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 (claim and tolerance_pct) with full descriptions including examples. The description itself adds no additional parameter-level meaning beyond what the schema provides, so baseline 3 applies.

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

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

The description explicitly states the tool performs natural-language claim verification against authoritative sources, provides trigger phrases ('fact check', 'verify the claim that...'), and distinguishes it from sequential multi-step pipelines by claiming it replaces 4–6 calls. It also separates financial and non-financial claim routing, making it specific to this tool among siblings.

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

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

The description says 'Use whenever the agent needs to check whether something a user said is factually correct' and explains the routing for financial vs. other claims. It does not explicitly name alternative tools or exclude non-factual questions, but the routing and 'Replaces 4–6 sequential calls' imply a clear use case.

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