Arcgis Lincolncountync

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description goes beyond those by disclosing that the default model is free, that passing _apiKey triggers direct Anthropic billing ('you pay Anthropic directly'), and that the response includes both per-model details and a combined view. This adds real behavioral context 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, zero filler. The first sentence states the core action and deliverable, the second adds cost/model details, and the third lists use cases. Information is front-loaded and every sentence earns its place.

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

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

The tool has no output schema, so the description's mention of the return shape ({score, confidence, signals, raw_response} + combined view) fills that gap. It also covers use cases, default behavior, and the optional key. Minor omissions like error handling or rate limits don't materially hurt 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%, so the baseline is 3. The description adds meaningful context by specifying the default model (Windows AI Llama-3.3-70b) and the condition for using _apiKey (only needed if 'anthropic' is in models). This goes beyond the schema's per-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 ('Probe'), a clear resource (LLMs), and a concrete outcome (score visibility 0-100 per model). It also names the default model and lists distinct use cases (AI-marketing audits, pre-launch checks, competitive monitoring), which clearly differentiates it from siblings like scan_competitor_ai_presence.

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

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

The description provides explicit use-case framing ('Useful for AI-marketing audits...') and clarifies the free default vs. BYO-key Anthropic option. It doesn't explicitly name alternative tools or say when not to use this tool, but the context is sufficient for an agent to make a reasonable choice.

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

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

Annotations already declare read-only/idempotent behavior. The description adds valuable context: routes among over 5,000 tools, fills arguments, returns stable pipeworx:// citation URIs, works on every tier, and is fast. It goes beyond annotations without contradicting them.

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

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

The description is somewhat long but front-loaded with the key directive 'PREFER OVER WEB SEARCH'. Every sentence adds practical value: use cases, trigger phrases, examples, alternatives, and performance characteristics. Slightly dense, but not wasteful.

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

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

For a router tool with no output schema, the description fully covers when, why, and how to use it, including alternatives and expected output shape (structured answer with citations). It is self-sufficient and leaves little ambiguity.

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

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

Schema covers all parameters (question and 5 aliases) with a clear description, so baseline is 3. The description adds examples but no new semantic detail about parameters; it does not need to, given 100% schema coverage.

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

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

The description clearly states the tool routes natural-language questions to a large set of verified data sources and returns structured answers with citations. It names specific use cases (SEC filings, FDA, FRED, etc.) and distinguishes from 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?

Explicitly instructs to prefer this over web search for factual questions, names concrete trigger phrases ('what is', 'look up', 'get the latest'), and provides 'step up only when needed' alternatives for grounded answers and broad multi-part research. This is exemplary when-to-use guidance.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses that candidate routing improvements are enabled live when under test, that currently no candidate is active so it matches ask_pipeworx exactly, and that it does not fall back to another router—it is fully functional. This adds valuable context about the experimental and potentially changing behavior.

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

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

The description is four sentences, each earning its place: it defines identity and scope, states current routing status, gives usage guidance, and corrects a potential fallback misconception. The structure is front-loaded with the key identity in the first sentence and remains dense without verbosity.

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 (a universal router with 5,462 tools) and no output schema, the description covers the necessary context: what it is, current experimental state, how it differs from the stable version, how it behaves during tests, and that it returns the same response shape. It is sufficiently complete for an agent to select and invoke it appropriately.

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

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

Input schema coverage is 100%, with question documented and aliases listed. The description adds no parameter-specific meaning beyond saying the arguments match ask_pipeworx, so the schema carries the full semantic burden, which is acceptable at the baseline score.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router with the same 5,462 tools and arguments. It distinguishes this beta variant from the stable ask_pipeworx and ask_pipeworx_grounded by emphasizing its experimental routing improvements, making the purpose and scope 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 explicitly says to use it exactly like ask_pipeworx when you want the newest routing, and explains that results are compared against the stable router to decide what merges. It gives a clear use case and current state, though it doesn't explicitly state when not to use it or mention alternatives beyond the comparison context.

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

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

Goes far beyond annotations (readOnly, openWorld, idempotent) by disclosing the answer is extracted 'using ONLY what the tool result contains' and enumerates explicit refusal reasons such as 'not_in_source' and 'data_truncated.' It also transparently notes the added cost of 'one extra LLM call.'

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, each earning its place: definition, mechanism, return shape, usage guidance. The description is information-dense but not bloated, progressing logically and front-loading the purpose.

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

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

Despite lacking an output schema, the description fully specifies the success return object ({answer, evidence, confidence, source, fetched_at, refusal_reason:null}) and the failure shape with all possible refusal_reason values. It also covers the routing scope (5,462 tools / 1419 sources) and compares against the sibling for 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?

The input schema has 100% coverage with all six parameters described as aliases for the same natural-language 'question.' The description does not add syntax details but reinforces that the tool internally fills arguments on the user's behalf, which aligns with the schema's alias design. Baseline 3 due to high schema coverage.

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

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

Description opens with a clear, specific purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It then details the mechanism (same routing as ask_pipeworx, picks tool, fills args, fetches data, extracts answer), which distinguishes it from the sibling ask_pipeworx by emphasizing the extraction-only behavior and refusal handling.

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' and where fact-invention is unacceptable (financial, legal, medical, public statements). Also gives an explicit alternative: 'prefer ask_pipeworx for casual lookups,' including cost tradeoff.

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

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

The description goes well beyond the annotations (readOnlyHint, openWorldHint, idempotentHint) by disclosing detailed behavioral traits: resolver contract with confidence levels, low-confidence short-circuiting, market_closed_or_inactive status, wide-spread tradeability flag, news fallback behavior, and cancellation rule risk. This is rich behavioral context that helps the agent know 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 well-structured with CAPS headers and front-loaded purpose, but it is quite long (~600 words). Every section adds operational value, though some details (e.g., extensive fan-out examples) could be trimmed. It's organized and readable, earning a 4.

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

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

Without an output schema, the description thoroughly covers response shapes (result.market, result.analysis, result.evidence), resolver contract (market_match_confidence, suggestions), parent event extraction, status conditions, and cancellation rule risk. This is comprehensive for a complex tool, leaving little ambiguity.

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

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

Schema coverage is 100% — all three parameters (market, depth, include_raw) are fully described in the schema. The description restates the market formats but adds no new param-specific semantics beyond what the schema already provides. 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 a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes this from siblings like polymarket_edges or ask_pipeworx by emphasizing the one-call fan-out research pattern and the explicit use cases ('should I bet on X').

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

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

The description provides explicit usage guidance: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It does not explicitly name alternatives or exclusions, but the context is clear enough. This is a 4 rather than a 5 because it lacks explicit 'when not to use' or alternative tool pointers.

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, covering the safety profile. The description adds valuable behavioral context beyond annotations: data source (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), correct handling of off-calendar fiscal years, sorting by primary metric, and return format with citation URIs. This is rich, non-redundant 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 front-loaded with trigger phrases and a clear directive, then packs data-source details, output behavior, and efficiency gains into a compact text. Every sentence earns its place—there is no filler or redundancy, 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?

The tool has only two well-documented parameters, no output schema, but strong annotations. The description covers inputs, data provenance, output format (paired data + citation URIs), sorting behavior, and the scale of the operation. This is fully sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description enriches parameter meaning by explaining that type='company' pulls 10-K financial metrics and type='drug' pulls FAERS/FDA counts, which is more than the schema's simple enum. It also clarifies values (tickers/CIKs vs names). This adds meaningful semantics beyond the schema.

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

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

The description clearly states a specific action ('side-by-side comparison of 2–5 companies or drugs in ONE parallel call') and gives trigger phrases like 'X vs Y' and 'rank these companies.' It explicitly distinguishes itself from sibling tools by saying 'ALWAYS PREFER over sequential single-pack lookups,' making its unique purpose unmistakable.

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

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

The description provides explicit when-to-use guidance ('when comparing entities') and contrasts with sequential single-pack lookups, implying the alternative for single-entity queries. It also includes concrete example queries and notes the efficiency gain (replaces 8–15 lookups), giving the agent clear decision criteria.

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

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

Annotations provide readOnly/openWorld/idempotent hints; the description adds substantial context beyond that: account/paywall constraints, parallel decomposition across 5,462 tools, gap[] handling that never invents, semantic excerpting, citation resolvability, latency expectations, and contradictions[] 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 long but front-loaded with prerequisites and core value. Each sentence contributes unique info—alternatives, output structure, depth behavior, latency—though a slight trim could tighten it. Still highly efficient for its complexity.

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

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

With no output schema, the description fully documents return values: findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], and contradictions[]. It also covers prerequisites, limitations, and timing, making the tool fully understandable for an agent.

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

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

Schema covers both parameters at 100%, so baseline is 3. The description adds behavioral meaning for depth (e.g., 'standard re-angles unanswered gaps', 'thorough additionally chases the best leads') and clarifies that broad/multi-part questions are fine, going beyond the schema's basic descriptions.

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

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

The description opens with 'Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources' — a specific verb and resource. It explicitly differentiates from siblings by contrasting with 'this is NOT open-web search' and positions itself for broad/multi-part structured-data questions.

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

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

Includes explicit when-to-use: 'Best for broad/multi-part questions over structured data', and clear exclusions: 'For a single lookup use ask_pipeworx', 'For BREAKING... prefer ask_pipeworx'. Also covers unsigned-in users and depth-tier guidance.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds behavioral context about the return value: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This explains the output format and eliminates a follow-up step, which is valuable beyond the annotations.

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

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

The description is three sentences, each with a distinct role: (1) what the tool does, (2) what it returns and the domains covered, (3) when to use it first. It is front-loaded with the core purpose and contains no redundant or filler content. The length is appropriate given the tool's breadth.

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 highly complete for a discovery tool: it explains the purpose, the domains supported, the output format (top-N tools with schemas and examples), and the usage context (call first when many tools). Even without an output schema, the description tells the agent exactly what to expect. The inclusion of examples and the 'no second schema lookup' detail ensure the agent can invoke the tool correctly.

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

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

Schema description coverage is 100% (all 6 parameters have descriptions), so the baseline is 3. The description goes beyond the schema by providing representative examples for the query parameter (e.g., 'look up FDA drug approvals', 'analyze housing market trends') and clarifying that the tool returns 'top-N' results, which connects to the limit parameter. This adds practical meaning to the query and limit semantics.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task' and lists specific domains (SEC filings, FDA drugs, etc.), which distinguishes it from siblings that search within data. The phrase 'Call this FIRST when you have many tools available' further solidifies its role as a discovery tool, differentiating it from tools like search_within or search_datasets.

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

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

It explicitly says when to use the tool: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set.' It also implies a contrast with using it for a single answer ('not just one answer'), but does not explicitly name alternative tools or state when not to use it, so it misses the full 5-level guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds valuable context beyond that: it fans out across multiple sources, notes the USPTO PatentsView API sunset May 2025 with soft-fail behavior, mentions GDELT→GNews fallback, and lists specific return fields. This gives the agent insight into data freshness and reliability.

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

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

The description is dense but every phrase earns its place. It front-loads with user-intent examples, then states the core behavior, then details the remote sources and return payload, and ends with input constraints. No wasted words; the structure is effective for a complex tool.

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

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

For a tool with no output schema, the description is remarkably complete. It enumerates the return fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI), discloses the patents API sunset, and explains the parallel-call efficiency. With annotations covering safety, the agent has enough to know when and how to invoke it.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by showing example values ('AAPL', '0000320193'), reinforcing that names are not supported, and clarifying that type only supports 'company' for now — all 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 concrete user intents ('Tell me about X', 'research Acme', 'brief me on Tesla') and states a specific verb+resource: 'full cross-source profile of a US public company'. It distinguishes itself from siblings by explicitly instructing to 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' for holistic views, and references resolve_entity for name-only inputs.

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?

Clear when-to-use guidance is embedded in the examples and the explicit preference instruction. It also gives a strong exclusion: 'names not supported (use resolve_entity first if you only have a name)', which tells the agent when to pick an alternative tool.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data and that the memory was 'previously stored', which enriches the behavioral picture beyond the annotations.

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

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

Two sentences, front-loaded with the action, and no wasted words. Every sentence earns its place.

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

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

Given the single parameter, no output schema, and strong annotations, the description fully covers purpose, usage, and pairing. Nothing essential is missing.

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

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

Schema description coverage is 100% with a clear description for the 'key' parameter. The description does not add more parameter detail, but the schema fully documents it, 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 states 'Delete a previously stored memory by key' with a specific verb (delete), resource (memory), and access method (by key), and distinguishes from siblings like remember and recall.

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

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

It explicitly provides when-to-use scenarios ('stale context, task done, clear sensitive data') and names alternatives ('Pair with remember and recall').

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

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

Annotations already indicate read-only, non-destructive, idempotent behavior. The description adds valuable context by describing the fetch-extract-emit process and the output format, which goes beyond the annotation safety profile. 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 three sentences: purpose, process, and use cases. It is front-loaded with the main action and every sentence contributes useful information without redundancy.

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

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

Despite no output schema, the description explicitly states the output is a single text blob for llms.txt. It covers operation, use cases, and output format. It could mention edge cases or errors, but for a simple two-parameter tool with strong annotations, it is sufficiently complete.

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

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

The input schema already provides complete descriptions for both parameters (100% coverage). The tool description does not add additional meaning beyond the schema, 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 clearly states a specific verb ('Generate') and resource ('llms.txt file for any URL'), and outlines the process (fetches, extracts, emits). It differentiates from sibling tools by explicitly mentioning competitor auditing, a use case tied to scanning AI presence.

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

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

The 'Useful for' section lists three concrete scenarios: getting a client's site indexed, drafting your own llms.txt, and auditing a competitor's AI visibility. This provides clear context on when to use the tool, though it does not explicitly name alternatives or state when not to use it.

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

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

The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds useful behavioral context by specifying exactly what information is returned (fields, geometry type, record count, capabilities), which goes beyond the annotations. No contradictions.

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

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

The description is a single, focused sentence that front-loads the core purpose and enumerates the returned items. 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?

With one simple parameter, no output schema, and strong annotations, the description sufficiently covers the tool's behavior and return value. The agent can confidently invoke it to get schema details.

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

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

The schema has 100% coverage for the single 'url' parameter, with a description already explaining it is a Feature/Map Service layer URL. The tool description adds only 'by url' which is implicit in the schema, providing minimal additional meaning. 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 action ('Get'), resource ('ArcGIS Feature/Map Service layer's schema'), and method ('by url'), and lists specific output contents (fields, geometry type, record count, capabilities). This distinguishes it from siblings like query_layer, which likely retrieves 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 on what the tool does and implies its use for schema inspection, but it does not explicitly mention alternatives or when not to use it (e.g., when you need actual feature data, use query_layer). This is a clear context without exclusions, warranting a 4.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds value by specifying that only active subscriptions are returned by default and by detailing the exact response fields. It doesn't need to re-assert safety traits, so this is transparent enough.

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

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

Two sentences: the first states purpose and return fields, the second gives actionable usage guidance. Every word earns its place, no filler or redundant phrasing.

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 list operation with one optional parameter, rich annotations, and no output schema, the description covers purpose, return fields, and when to use it. It is fully sufficient for an agent to invoke correctly.

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

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

Schema coverage is 100% and the parameter include_inactive is fully described in the schema with its default behavior. The description's mention of 'active subscriptions' aligns with the parameter but doesn't add extra semantics 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 lists 'the caller's active subscriptions' and enumerates the exact fields returned (id, type, params, created_at, last_fired_at, fire_count). It distinguishes from siblings like subscribe and unsubscribe by framing use cases (review what you're monitoring, find an id to cancel).

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

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

The description provides clear usage context: review current monitoring before adding more or to find a subscription id to cancel. It implicitly contrasts with subscribe (adding more) and unsubscribe (cancelling), though it doesn't explicitly mention alternatives or exclusions.

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

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

Annotations are all false, so the description carries the full burden. It discloses the rate limit (5/day), the claim_token flow for anonymous users, that it doesn't count against tool-call quota, and that the team reads digests daily. It also clarifies the scope boundary (only Pipeworx tools). This goes well 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 longer than typical but each sentence serves a purpose: purpose, usage types, exclusions, claim_token behavior, and rate limit. It is front-loaded with the core purpose and progressively details constraints. Slightly dense 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?

The description covers the essential operational aspects: what to report, exclusions, follow-up via claim_token, and rate limits. It does not fully explain the output format for account-holders or the exact response structure, but the claim_token explanation covers the main anonymous path. Given no output schema, it's reasonably complete.

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

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

Schema description coverage is 100%, giving a baseline of 3. The description adds meaningful guidance beyond the schema: 'don't paste the end-user's prompt,' specific use of claim_token with 'no other arguments,' and context on message length. These enrich parameter semantics without being redundant.

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

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

The description opens with a clear verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly enumerates feedback types (bug, feature, data_gap, praise), and differentiates itself from sibling tools by being the only feedback/suggestion channel for Pipeworx.

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 conditions: bugs, feature gaps, data gaps, praise. Also explicitly states when NOT to use: if the problematic tool came from a different MCP server, file with that vendor instead. This exclusion prevents misuse and delays.

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

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

Annotations already cover read-only, idempotent, non-destructive behavior. The description adds valuable context: the data is self-aggregated from CF analytics-engine, contains no PII, and is cached for 5 minutes to 1 hour depending on the window. These details go beyond annotations and help agents understand data freshness and privacy.

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

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

The description is front-loaded with the main action, then organized into use cases and additional context. While it is somewhat verbose, each sentence contributes useful information without redundancy, making it well-structured for its 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?

For a simple tool with an optional parameter, rich annotations, and no output schema, the description covers what it returns, use cases, data source, and cache behavior. It lacks explicit output shaping, but the core behavior is clear and sufficient for an agent to understand what the tool does.

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 'window' parameter with enum values and descriptions (100% coverage). The description does not add additional parameter semantics beyond what the schema already provides, so a baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: returning trending tool/pack usage and call volume from other AI agents. It specifies the exact resource (top tools, top packs, total call volume) and window options, distinguishing it from siblings like ask_pipeworx or discover_tools.

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

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

The 'Useful for' list provides concrete use cases such as discovering hot data sources, confirming canonical tools, and assessing alignment with other agents' needs. It does not explicitly mention alternatives or when not to use the tool, but the context is clear enough to guide an agent.

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

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

Annotations already declare safe read-only behavior, and the description adds substantial context: thresholds (3pp, 0.30 Jaccard, 20% placeholder), response structure, fill check logic, and what skipped_low_similarity means. No contradiction with annotations.

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

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

The description is long but every section earns its place: core purpose in the first sentence, then mode selection, technical details in labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK), and response format. Front-loaded and well-organized.

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

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

With no output schema, the description fully covers return values (opportunities[], partition_check{}, fill check fields), edge cases (placeholder slugs, low similarity), thresholds, and usage context. It is complete for the tool's complexity and sibling landscape.

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?

Even though schema coverage is 100%, the description enriches both parameters with examples, accepted formats (slugs vs full URLs), and detailed behavioral differences between event and topic modes. It adds significant meaning beyond the schema.

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

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

The description clearly states the tool's purpose: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes from siblings by naming specific methods and modes (trending_scan, event, topic), and provides concrete 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?

Explicit guidance is given: when to call with no args, when to use `event` vs `topic`, and that `polymarket_fill_risk` should be used for custom sizing. It even tells when NOT to trade (when realizable_edge_pp ≤ 0). This is exemplary 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?

The description goes far beyond the readOnly/idempotent annotations by disclosing caching behavior (1h KV keyed on all knobs), the three response segments, diagnostics funnel counters, slippage assumptions, and a 24h-move warning. It also details placeholder-slug filtering and rare-by-design longshot gates. All disclosed behaviors align with the non-destructive read-only annotations, with no contradictions.

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

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

The description is a dense, multi-hundred-word paragraph that, while segmented by caps and lists, overloads the agent with model internals (alpha values, GDELT ratios, funnel counters) that could be summarized. It is not appropriately sized—essential selection information is buried under excessive detail, and the lack of concise structure reduces scannability.

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

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

For a tool with 9 parameters and no output schema, the description fully compensates by defining the top-level response fields (by_segment, fed_candidates, _diagnostics), per-opportunity fields (edge_pp_net, kelly_fraction, market liquidity/spread/volume), and filter behavior. The diagnostics section tells callers why segments might be empty, making the tool self-explanatory. This is exceptional completeness.

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?

Even though the schema covers 100% of parameters, the description adds crucial inter-parameter context: it identifies 'TRADEABLE-EDGE KNOBS' as a group, explains that min_kelly does NOT filter partition arbs because parent-level Kelly is always 0, and clarifies that slippage_pp modifies edge before ranking. This significantly enhances understanding beyond the per-parameter schema descriptions.

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

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

The description opens with a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly establishes the tool's unique value as an edge-discovery engine among siblings, with the 'Built for' phrase reinforcing the intended use case.

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 'Built for "what should I bet on today"' provides a clear invocation context, and the detailed knob explanations (min_liquidity, max_spread_pp, min_partition_leg_kelly) tell the agent how to tune for realizable edges. It also excludes Fed bets from ranking with an explanation, implicitly guiding when to avoid trusting signals. However, it does not explicitly contrast sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial behavioral context: response structure (tracked[], expired[], snapshot_dates[]), the signed edge value meaning (negative = SELL YES), data source limitations (60-day TTL, cache-miss snapshots, daily closes not intraday). This exceeds what annotations alone communicate, with no contradictions.

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

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

The description is long but every sentence earns its place: purpose, args, response keys, and limitations. It is front-loaded with the core question and structured with clear labels (Args, RESPONSE, LIMITS). No filler or repetition of schema descriptions beyond necessary context.

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

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

Given there is no output schema, the description thoroughly explains all return fields (tracked, expired, snapshot_dates) and their interpretation, plus data limitations and source behavior. It is self-contained enough for an agent to invoke the tool and correctly interpret results. No significant gaps.

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

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

Schema coverage is 100% and includes defaults and clamps for both params. The description restates these facts ('default 14, max 30', 'default 1wk') and adds the concept of 'snapshot family', but the added semantic value is modest. It does not meaningfully go beyond the structured schema, so the baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It directly answers a distinct question ('how long has this edge existed and is it shrinking?'), and the example contrasting fresh vs. old edges distinguishes it from sibling tools like polymarket_edges. This is a clear, differentiated purpose.

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

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

The description implies when to use the tool: when the user needs edge history and decay trends, rather than just current edges. The question framing ('Answers...') and the explanation of expired opportunities as a 'competition clock' provide context. However, it does not explicitly name alternatives or state 'use this instead of X', 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=true, destructiveHint=false) already establish safety, and the description adds rich behavioral context: it walks the order-book ladder, returns per-leg fill details, identifies thin_legs[], and warns about forced_directional_risk and partial-fill conversion to unhedged positions. No contradiction with annotations.

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

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

The description is long but well-structured with clear 'SINGLE-MARKET' and 'BASKET' sections, and it front-loads the core purpose. Every sentence adds information, though some parameter details (e.g., size_usd defaults) are repeated from the schema, making it slightly 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 fully enumerates return fields for both modes, explains the risk verdicts, and provides usage context tied to sibling tools. It is complete enough for an agent to select and invoke the tool correctly without additional documentation.

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 meaningful semantic value beyond the schema by explaining the mutual exclusivity of market/event modes, the auto behavior for side in basket mode, and the interpretation of size_usd as settlement notional vs max spend/target proceeds. This is more than 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 states a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes from siblings by framing itself as a pre-trade validation tool for polymarket_arbitrage and polymarket_edges, and names the two modes (single-market and basket) with distinct return values.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the consequence of not using it (partial fills convert an arb into an unhedged directional position), giving clear exclusionary guidance.

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

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

Beyond the readOnlyHint annotation, the description discloses detailed behavioral edge cases: compatibility_warning conditions (a) and (b), temporal_alignment semantics, and skipped_cross_type/subtype counters. It explicitly explains what 'aligned:false' means, making the tool's behavior transparent and predictable.

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 carefully organized with clear labels (TWO MODES, RESPONSE, SAFETY FIELDS). Every section provides necessary information without filler or repetition. The core definition is front-loaded, and each sentence earns its place.

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

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

With no output schema, the description fully compensates by specifying the response structure (leg-by-leg prices, spread[].top_spreads_pp, safety fields). It covers all major edge cases including temporal alignment and skipped comparisons, making the tool's behavior well-understood for a complex cross-venue 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 all 3 parameters with 100% coverage, including descriptions for topic values and overrides. The description adds the conceptual framing of TWO MODES, clarifying that topic is a shortcut and explicit params are for custom pairings, which is moderate added 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 opening sentence 'Cross-venue spread between Kalshi and Polymarket for the same resolving question' clearly identifies the tool's function with a specific resource and distinguishes it from siblings like polymarket_arbitrage by focusing on cross-venue comparison. It also describes two modes, further clarifying scope.

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

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

The description explains when to use topic shortcuts vs explicit ticker/slug pairings and warns that 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable,' providing clear when-not guidance. However, it does not explicitly name alternative tools for same-venue arbitrage, so it lacks fully explicit alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is safe. The description adds that it returns attribute rows and geometry, and the sampling tip illustrates safe exploration. No contradictions.

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

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

Two sentences, front-loaded with the core action, then compactly lists the main parameters and a practical tip. No wasted words.

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

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

Despite 6 parameters and no output schema, the description covers the source of the URL, return payload, and a key usage pattern. With schema covering parameter specifics, this is sufficient for a read-only 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 covers 100% of parameters with descriptions. The description adds context that parameters are SQL-like, out_fields are comma-separated, and provides a concrete example of using where and out_fields together for sampling, enhancing schema descriptions.

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

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

The description clearly states it queries an ArcGIS Feature/Map Service layer by URL, and explicitly ties the URL source to search_datasets, distinguishing it from siblings like search_datasets (finding) and layer_info (metadata). It specifies SQL-like parameters and return type.

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 tells the agent the URL comes from search_datasets, creating a clear workflow ('use this after search_datasets'). It also provides a sampling tip with where='1=1' and out_fields='*', but doesn't explicitly name alternative tools or when-not-to-use scenarios.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable scoping context (anonymous IP, BYO key hash, or account ID) and the behavior of listing all keys when the key is omitted, which goes beyond the annotations.

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

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

The description is three sentences with no fluff. It front-loads the primary action, then gives usage context, scoping, and pairing in a logical order. Every sentence contributes useful information.

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

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

For a simple one-parameter tool with no output schema and strong annotations, the description covers the essentials: purpose, usage, scoping, and related tools. It does not explicitly describe behavior for missing keys or the exact format of the key list, but those are minor gaps for this simple retrieval 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 describes the 'key' parameter and its optional omission. The description reinforces this and adds real-world examples of key contents, plus the scoping note about identifiers. Since schema coverage is 100%, the baseline is 3; the description adds a bit more context, justifying a 4.

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

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

The description clearly states the tool's function: retrieve a value previously saved via remember, or list all saved keys when key is omitted. It gives concrete examples of content (ticker, address, research notes) and explicitly distinguishes it from sibling tools by pairing with remember and forget.

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

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

The description provides clear usage context: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It mentions scoping and pairing with remember/forget, but does not explicitly state when not to use it or list alternatives beyond the paired 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 says 'Set mark_read:true to flag returned events read so the next call only shows newer ones,' which is a state-modifying side effect. This directly contradicts the readOnlyHint:true annotation. While the description adds useful behavioral details like citation_uri and polling, the contradiction is severe.

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

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

The description is three sentences, front-loaded with the core purpose, and every sentence adds value—purpose, return shape/filtering, and polling/external access. 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 5-parameter tool with no output schema, the description covers the main purpose, return fields, filtering, mark_read side effect, polling, and an alternate access URL. It is nearly complete, but the unresolved annotation contradiction leaves a completeness gap regarding the true read/write nature of the tool.

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

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

The input schema already describes all 5 parameters (100% coverage), but the description adds meaning beyond it: a concrete type example ('sec_8k'), reinforces the ISO timestamp format, and explains the consequence of mark_read:true (next call only shows newer events).

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: 'Pull fired events from your subscription feed.' It clearly distinguishes the tool from siblings by focusing on subscription alerts, and adds detail about the returned payload and filtering.

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

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

It provides clear context for when to use the tool (pulling recent subscription alerts), describes filtering options, and explicitly states 'Polls work fine.' It also mentions an external HTTP endpoint as an alternative for scripts/dashboards, but does not compare against sibling 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?

Despite readOnlyHint and idempotentHint in annotations, the description adds substantial behavioral context: it fans out to multiple sources, explains fallback logic, notes the PatentsView sunset and soft-fail behavior, and describes the return structure. This goes well beyond the annotations.

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

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

The description is dense but every sentence contributes information: examples, sources, fallbacks, return format, and alternative tool. It is a single block of text, but the content is well organized in a logical flow. A bit shorter or with line breaks would earn a 5.

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

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

Given there is no output schema, the description appropriately explains the return payload (changes[], total_changes, citation URIs). It covers all key aspects: input format, supported sources, fallback behavior, time handling, and relationship to sibling tools. Completeness is high.

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

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

The schema already documents all three parameters fully, so baseline is 3. The description adds value by clarifying the `since` parameter with examples and recommending '30d' or '1m' for typical monitoring, which is a helpful usage nuance. It also confirms `value` accepts ticker or CIK, but that is already in the schema.

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

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

The description clearly states the tool's function: a change feed for a company over a time window, aggregating SEC, news, and patent sources. It distinguishes itself from sibling entity_profile by explicitly pointing to that tool for static profiles.

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

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

Provides concrete example queries ('What's new with X') and gives explicit guidance on when to use this tool versus entity_profile. The mention of fallback behavior (GDELT to GNews) also sets expectations for usage conditions.

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

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

The description adds behavioral context beyond annotations: memory is scoped by agent identifier, authenticated users get persistent memory, anonymous sessions expire after 24 hours. This supplements the annotation hints (idempotent, non-destructive) without contradicting them.

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

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

The description is front-loaded with the primary action and is concise. Each sentence adds value (purpose, usage trigger, storage details, retention, companion tools) without redundancy. Slightly longer than minimal but earned.

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

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

For a simple two-parameter write tool with annotations and no output schema, the description covers purpose, when to use, scoping, persistence, and related tools. It could mention overwrite behavior or return value, but these are not essential given the 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% with clear descriptions for key and value. The description adds minor context (examples of keys/values, value can be 'any text') but mostly reinforces what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool saves data needed later, with a specific verb ('Save') and resource (key-value store). It provides examples of what to store and distinguishes itself from related tools by naming recall and forget as companions.

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

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

It gives explicit usage guidance: 'Use when you discover something worth carrying forward' and explains the benefit ('so you don't have to look it up again'). It also identifies related tools (recall, forget) but does not explicitly 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 indicate read-only, idempotent, and non-destructive behavior. The description adds substantial context: it cascades through several lookup endpoints internally, returns specific fields (ticker, CIK, RxCUI, ingredient, brand), and includes citation URIs. This goes beyond the annotation's safety clues to explain internal mechanics and return details.

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

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

The description is well-organized and front-loaded: it opens with example queries, then the usage directive, then type-specific details. Every sentence contributes meaning without redundancy. While detailed, it remains focused and scannable, appropriate for a tool with two distinct entity types.

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

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

Given no output schema, the description fully explains what each entity type returns, including identifier fields and citation URIs. It also covers input flexibility and internal cascading. The tool's complexity is adequately addressed, making it complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing concrete examples for each entity type (e.g., 'AAPL', '0000320193', 'ozempic'), noting that company accepts ticker, CIK, or name with auto-disambiguation. This enriches the schema's parameter descriptions enough to warrant a 4.

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

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

The description clearly states the tool resolves user-spoken names to canonical identifiers, with explicit example queries ('What's the ticker for…', 'find the CIK for…', etc.) and supported types. It distinguishes itself from siblings by specifying it provides IDs required by other tools, positioning itself as the go-to for name-to-ID 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?

Explicit usage directive: 'Use FIRST whenever you have a name but need an ID.' Concrete examples of triggering queries and delineation between company and drug types provide unambiguous guidance. It also explains that the tool replaces 2-3 manual lookups, reinforcing when it should be preferred.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds valuable behavioral context beyond annotations: it describes that the tool probes each entity with ai_visibility_check, ranks results, and surfaces most/least recognized entities. It also discloses the output format including score, confidence, and signal density. While not exhaustive (no mention of rate limits or edge cases), it meaningfully augments the annotation-defined safety profile.

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 earning its place: purpose, operational behavior, use-case example, and return value. It is front-loaded with the primary action and avoids redundant or filler text. No word is wasted, making it highly concise and well-structured.

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

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

The tool's complexity is moderate (multi-entity aggregation), and the description covers the input (entities, first as subject), the process (probe and rank), and the output format. Annotations cover safety, and the schema covers parameter constraints. It lacks details on potential errors or edge cases (e.g., what happens if entities list is invalid), but for typical use the description is sufficiently complete.

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

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

Schema description coverage is 100%, with all four parameters (models, _apiKey, context, entities) having thorough descriptions. The tool description does not add significant parameter-level meaning beyond what the schema already provides. Since the baseline for high coverage is 3, and the description's mention of 'ai_visibility_check' and output concepts does not clarify parameters further, a 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Compare AI visibility across multiple entities side-by-side.' It clearly differentiates from siblings by focusing on multi-entity comparison and explicitly referencing ai_visibility_check as the underlying probe. The phrase 'competitive AI-marketing audits' further clarifies the intended use, making this distinct from single-entity 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 provides clear usage context with a concrete example question, 'does Claude know about us as well as our competitors?' and states it is useful for competitive audits. It implies this tool is for comparing multiple entities while ai_visibility_check handles individual probes, but it does not explicitly state when to avoid this tool or prefer an alternative. This stops short of the explicit when/when-not guidance that would earn 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?

Adds timing (bundlephobia's first measurement can take 5-30s), partial failure behavior (sources_failed lists timeouts, rest still returns), and the composition of two external services. This is beyond the readOnly/idempotent annotations, and there is 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?

Front-loaded with purpose and dense but informative. Every sentence adds value (usage, return shape, ecosystem limit, failure behavior). It's slightly long but appropriate for a composite tool with no output schema.

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

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

Covers the return payload (summary block fields, per-advisory detail, links, alternative versions), ecosystem scope, timing, and failure modes. With no output schema, this level of detail is necessary and sufficient.

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

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

Schema coverage is 100% (both package and version have descriptions including scoped package support and default-latest behavior). The description adds no new parameter semantics beyond what the schema already provides, so the baseline 3 applies.

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

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

The description states a specific composite check ('should I add this npm package to my project') and lists exactly what it fans out to (deps.dev, bundlephobia) and what it measures (license, advisories, bundle size, etc.). It clearly distinguishes from sibling tools like scan_competitor_ai_presence by focusing on npm package viability.

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 "is X safe / popular / small" or "what does adding lodash cost me"' and identifies exclusions ('NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly'). This gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds value by detailing the return payload (name, summary, record_count, owner/org, url) and the workflow of using the url with query_layer/layer_info. 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-loaded with the action and resource, then followed by output specifics and next steps. Every word earns its place, with no redundancy or filler.

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

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

For a read-only search tool with full schema coverage and no output schema, the description sufficiently covers the purpose, return fields, and downstream usage. It lacks some details like pagination or error handling, but these are not critical given the tool's simplicity. The mention of query_layer/layer_info adds valuable contextual workflow.

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

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

Schema coverage is 100%, with all three parameters (limit, query, org_id) already described. The description adds minimal semantic value beyond the schema, mentioning keyword search but not providing additional syntax or edge-case details. Baseline of 3 is appropriate given high schema coverage.

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

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

The description clearly states a specific verb (Search), a resource (Lincoln County GIS open geospatial datasets), and a scope (parcels, addresses, zoning & public works). It distinguishes from siblings by mentioning follow-up tools query_layer/layer_info, indicating a unique role in the ecosystem.

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 (searching GIS datasets by keyword) and explicitly instructs to pass the returned url to query_layer/layer_info. It does not, however, explicitly state when not to use it or compare to alternative discovery tools like discover_tools or search_within.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description richly discloses behavioral details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, the 200K char cap with truncation flagging, and that each passage includes offsets for verbatim verification. It fully describes the return format, which is especially valuable since no output schema exists.

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

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

The description is well-structured and every sentence contributes value. It front-loads the core purpose, then covers usage guidance, technical details, and limitations in a logical flow. While somewhat lengthy, it avoids fluff and is easy to scan.

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

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

Given the tool's complexity and the absence of an output schema, the description is highly complete. It covers the input, the processing approach, return values, limits, and a related tool. It provides enough context for an agent to select and invoke the tool correctly without additional documentation.

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

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

The input schema provides complete descriptions for all three parameters (text, query, limit), including examples and defaults. The description adds context about the truncation cap and query style but largely repeats schema information, so it doesn't significantly augment parameter semantics. Baseline 3 is appropriate given the high schema coverage.

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

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

The description clearly states the tool performs semantic search inside a fetched record, with a specific verb, resource, and scope. It distinguishes itself from siblings by emphasizing it works with already-fetched text and saves context, and it explicitly contrasts with ask_pipeworx_grounded.

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

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

The description explicitly defines when to use the tool ('Use when the record is too big to cram into the prompt') and mentions a companion tool (ask_pipeworx_grounded) as an alternative for grounding over passages. This provides clear decision guidance, even if it doesn't explicitly state negative use cases.

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

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

The description discloses key behavioral traits: it creates a subscription, returns a new ID, requires OAuth, and details SMS/email constraints. It does not mention idempotency or potential duplicate behavior, but annotations already indicate idempotentHint=true. The description adds value beyond annotations by specifying account prerequisites and delivery nuances.

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

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

The description is dense but well-organized, covering purpose, requirements, types, and delivery in two long sentences. It front-loads the main action and uses examples to clarify complex parameters. While it is a bit run-on, it wastes no words and is 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?

With no output schema, the description correctly states the return value ('Returns the new subscription id'). It covers all supported types and most delivery channels, but omits the webhook channel from the main text (though the schema covers it). It provides enough guidance for a non-trivial subscription tool, but could be slightly more complete regarding webhook details.

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

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

The input schema already has 100% description coverage, so the baseline is 3. The description enhances parameter understanding with concrete examples for each type (e.g., sec_8k with items:["5.02"], polymarket_edge with topic:"fed") and explains the always-on feed behavior. These examples add practical meaning beyond the schema's generic descriptions.

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

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

The description clearly states the tool's function: 'Create a proactive monitoring subscription to a live-data event stream.' It identifies the resource (subscription) and the verb (create), and distinguishes itself from sibling tools like list_subscriptions and unsubscribe. The supported types and delivery channels further clarify its specific scope.

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

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

The description provides usage context by noting the account requirement ('anonymous + BYO cannot persist subscriptions'), and describes delivery channel options with practical constraints (e.g., SMS verification and 10/day cap). It also points to how the feed is consumed via recent_alerts, though it does not explicitly compare with alternative tools for similar actions.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral detail beyond annotations: it explains the output structure (category-bucketed example questions with tool+argument shape), the source (live catalog of thousands of tools), and the difference between no-arg and topic-filtered calls. No contradictions.

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

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

The description is front-loaded with concrete example questions, then states purpose, output, and usage. It is longer than two sentences but every sentence contributes distinct information. Slight redundancy with the schema's parameter list could be trimmed, but overall structure is 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?

There is no output schema, so the description must explain what is returned—it does: category-bucketed example questions with exact tool and argument shapes. It also covers invocation variants and when to use, making it fully self-contained for an onboarding tool with zero required parameters.

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

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

Schema covers the single parameter with a full description including allowed values and omit behavior, so coverage is 100%. The description repeats this ('pass topic (e.g. "finance", "pharma", "betting") to focus') but adds no new semantic beyond the schema. Baseline 3 is appropriate.

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

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

The description states a specific verb+resource: helping users learn what to ask Pipeworx, returning example questions with tool-argument shapes. It explicitly positions itself as the onboarding entry point, clearly distinguishing it from siblings like discover_tools or ask_pipeworx by framing 'Use 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?

The description gives explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also mentions related tools (ask_pipeworx, entity_profile, compare_entities) as things to learn, providing clear context for placement among siblings.

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

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

The description adds important behavioral context beyond the annotations: ownership enforcement ('you can only cancel your own subscriptions') and the non-destructive deactivation ('row is deactivated, not deleted'). This complements the annotations without contradicting them.

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

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

The description is two sentences, front-loaded with the action, and each sentence adds necessary detail. There is no redundancy or fluff.

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

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

For a simple one-parameter cancellation tool, the description covers the key aspects: action, ownership, and data persistence. It does not mention return behavior, but the annotations and simplicity make this 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% and the description provides no additional meaning beyond the schema. The 'by id' phrase merely repeats what the schema already specifies for the 'id' 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 uses the specific verb 'Cancel' and identifies the resource as 'a subscription by id', which clearly distinguishes it from sibling tools like 'subscribe' and 'list_subscriptions'. It directly states the action and target.

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 title 'Unsubscribe from Alerts' implies the intended use case, and the description clarifies the scope (only own subscriptions) and the effect on historical events. It does not explicitly name alternatives, but the sibling context makes the usage clear.

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

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

The description adds substantial behavioral context beyond the annotations: it explains the SEC EDGAR + XBRL fast path for financial claims, the grounded pipeline fallback for other claims, the specific return value types (verdict categories, evidence citation, reasoning), and that it replaces 4–6 sequential calls. This exceeds what the readOnly/openWorld/idempotent hints communicate.

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

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

The description is dense but efficient, front-loading with natural-language examples and the core use case. Each sentence delivers distinct information: examples+trigger, when to use, routing behavior, and return values. It's longer than minimal but the complexity of the tool warrants it, with no fluff.

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

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

Despite having no output schema, the description thoroughly documents what the tool returns: a verdict (with the five possible values), the grounded/structured value with citation, and reasoning. It also covers the two parameters, routing logic, and the efficiency benefit. For a tool with moderate complexity, nothing critical is missing.

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

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

The schema has 100% coverage with descriptions for both parameters, earning a baseline of 3. The description adds extra meaning by explaining how tolerance_pct overrides claim-implied defaults and its use in hallucination detection, going beyond the schema's raw description. This incremental value 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 uses a specific verb ('verify') and resource ('natural-language claim verification against authoritative sources'), making the tool's purpose unmistakable. It also distinguishes it from siblings by explicitly positioning it as the fact-checking tool versus research/asking tools, and even differentiates its internal routing for financial vs. other claims.

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

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

The description clearly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the fallback routing for different claim types. However, it does not explicitly mention when not to use it or name alternatives, so it misses the 'when-not' aspect for a full 5.

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