Arcgis Courtenay

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

Annotations already declare readOnly/idempotent, so the description adds valuable behavioral context: default model is Workers AI Llama-3.3-70b (free), passing _apiKey probes Anthropic with direct billing ("you pay Anthropic directly"), and it discloses the return structure (per-model {score, confidence, signals, raw_response} + combined view). This goes well beyond the annotation 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?

Three sentences, front-loaded with the core purpose, followed by default behavior/cost and use cases. Every sentence earns its place with no repetition or filler.

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

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

Without an output schema, the description compensates by explaining the return shape. With 4 parameters fully documented in the schema, plus default behavior, cost, and use cases, the description is complete for a read-only probe tool of this complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by clarifying the default model (free) and the cost implication of _apiKey (BYO key — you pay Anthropic directly), which enriches the models and _apiKey parameters. This raises the score to 4.

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

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

The description opens with a specific verb and resource: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' This clearly distinguishes it from siblings like ask_pipeworx (Q&A) and scan_competitor_ai_presence (competitor-focused), as it applies to any entity and yields a visibility score.

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

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

The description gives explicit use cases: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' This provides clear context for when to use the tool. It does not explicitly name alternatives or exclusions, but the use-case framing is enough to guide selection.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds meaningful behavioral context: it routes queries, works on every tier, makes one fast call, and returns stable pipeworx:// citation URIs. No contradiction with annotations.

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

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

The description is longer than necessary but well-structured, with key guidance front-loaded ('PREFER OVER WEB SEARCH'), followed by examples and sibling differentiators. Each sentence earns its place, though some redundancy exists (e.g., repeated emphasis on 'START HERE').

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 covers return format (structured answer with citation URIs), use cases, and when to prefer alternatives. It is complete for a broad question-routing tool with rich annotations.

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, including the question field and five aliases. The description provides examples and clarifies natural language input, but does not add significant meaning beyond what the schema already documents. 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 routes questions to one of 5,430 tools across 1,408 sources and returns structured answers with citation URIs. It explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, making the purpose unambiguous.

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

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

Provides explicit 'PREFER OVER WEB SEARCH' guidance with a broad list of domains, instructs to 'START HERE for most questions', and names specific alternatives (ask_pipeworx_grounded, deep_research) with conditions for when to step up. Also includes concrete examples and notes about breaking-news routing.

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 read-only, open-world, idempotent, and non-destructive annotations, the description discloses the beta status, live candidate testing behavior, current state with no active candidate, and that it falls back to nothing (i.e., is a full working router). It also explains the comparison/merge evaluation process, which is critical for understanding how it differs from the stable version.

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-loading the beta status and core identity. Each sentence contributes: what it is, current state, usage instructions, and clarification that it is fully functional. It is concise and well-structured, though the first sentence is dense with parentheticals.

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

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

Given the lack of an output schema, the description compensates by stating the response shape is identical to ask_pipeworx and by explaining the experimental context. It covers purpose, usage, current status, and fallback behavior, providing enough for an agent to decide whether to invoke it. A slight gap is that it does not detail potential differences in output when candidates are active.

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 documents all six parameters with 100% coverage, including aliases for 'question'. The description only mentions 'same arguments' as ask_pipeworx, adding no specific parameter semantics beyond the schema. With high schema coverage, the baseline score 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 explicitly defines this as a beta version of ask_pipeworx, a universal router with 5,430 tools, same arguments, and same response shape. It clearly distinguishes from the stable sibling by highlighting its experimental routing improvements and current inactive candidate state, making the purpose unmistakable.

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

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

The description gives an explicit usage condition: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also notes that results are compared against the stable router to decide merges, implying the stable alternative for normal use. However, it does not explicitly state when not to use it beyond the experimental label.

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?

Discloses refusal reasons ('not_in_source','no_tool_match','tool_error','data_truncated','llm_error') and the success response shape including 'evidence (verbatim quote)'. The description adds honesty guarantees and cost tradeoffs beyond the readOnlyHint/idempotentHint annotations, with no contradiction.

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

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

The description is dense but every sentence contributes: use-case, routing mechanism, extraction method, return format, refusal reasons, and cost comparison. It is front-loaded with the key differentiator and contains no filler.

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

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

With no output schema, the description fully specifies the success and refusal return formats, covers when-to-use, compares with the sibling tool, and explains costs. This is complete for a complex tool even without an output schema.

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

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

The schema already documents all six parameters as aliases for 'question' with 100% coverage. The description does not add parameter-specific details beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description clearly states it is a 'Hallucination-resistant answer mode for high-stakes reads' that routes to tools, fetches data, and extracts answers only from tool results. This specific verb+resource+scope distinguishes it from the sibling ask_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?

It explicitly says to use 'whenever an answer will be quoted, cited, or acted on' and lists high-stakes domains (financial, legal, medical, public statements). It also warns that it 'costs one extra LLM call vs ask_pipeworx' and directs 'prefer ask_pipeworx for casual lookups,' giving a clear alternative.

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

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

Annotations already set readOnlyHint=true and destructiveHint=false, and the description adds substantial depth: resolver contract details (market_match_confidence, market_match_score, alternatives), safety short-circuit statuses (low_confidence_match, market_closed_or_inactive), spread warnings, parent-event extraction, news fallback fields, and resolution-rule risk. It goes far beyond the annotations and provides critical operational 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 long but well-structured with capitalized section labels and progressively deeper detail. Every section contributes important behavioral information. Minor redundancy exists (e.g., the note about de-indexed markets being described both in the SAFETY section and in the closing resolution-rule risk), and it could be tightened slightly, but it is front-loaded with the core purpose and use cases.

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

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

For a complex tool with no output schema, the description thoroughly documents response shapes (result.market, result.analysis, result.evidence), resolver contract, parent_event extractor, news fallback fields, and safety/error statuses. It also covers edge cases like wide spreads and cancellation rules, making the tool's runtime behavior highly predictable 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 description coverage is 100%, so baseline is 3. The description adds meaningful value by explaining the market parameter accepts slugs, URLs, or question text with concrete examples, and clarifies depth ('quick = 2-3 evidence sources') and include_raw behavior including response size trade-offs. These enrich the raw schema info.

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 lists use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and provides classifiers and fan-out examples, clearly distinguishing it from sibling tools like polymarket_edges or validate_claim.

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

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

The description gives explicit when-to-use guidance: 'Use for "should I bet on X"...' and includes extensive examples across categories (crypto, fed, geopolitics, sports, etc.). However, it does not explicitly state when not to use it or name alternative tools, so it lacks a full when-not/alternatives contrast.

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

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

Annotations already declare read-only and non-destructive behavior, but the description adds rich behavioral context: pulls specific SEC EDGAR/XBRL data, handles off-calendar fiscal years, sorts results by primary metric, returns paired data with pipeworx:// citation URIs, and notes it replaces 8–15 sequential lookups. This goes far beyond annotation hints.

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

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

The description is dense but highly structured: trigger phrases first, then type-specific data sources, then result behavior. Every sentence adds functional value, with no fluff or repetition of schema details. Despite its length, it remains scannable and purposeful.

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 fully covers invocation semantics, data sources, edge cases (off-calendar fiscal years), result ordering, and return format (paired data + URIs). It is complete enough for an agent to select and invoke correctly without 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?

Input schema covers 100% of parameters with descriptions, but the description enhances meaning by explaining what each 'type' pulls (10-K metrics for companies, FAERS/trial counts for drugs) and gives concrete examples for 'values'. This additional context helps the agent construct valid invocations.

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

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

The description clearly states the tool performs side-by-side comparisons of 2–5 companies or drugs in one parallel call, with specific trigger phrases like 'X vs Y' and 'rank these companies'. It distinguishes itself from sibling tools by explicitly preferring it over sequential single-pack lookups.

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

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

Provides explicit when-to-use guidance via trigger phrases and a strong directive to prefer this tool over sequential lookups for comparisons. It also clarifies type-specific behavior, effectively guiding the agent on when to call this tool instead of alternatives like entity_profile.

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, but the description adds substantial behavioral context: account/paid plan requirements, gap recovery and contradiction scans, hop field, citation_uri, semantic excerpting, and latency expectations. This does not contradict the annotations and goes well beyond 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 long but every sentence earns its place, providing critical account context, alternative tool guidance, operational details, and output behavior. It is front-loaded with the account requirement and fallback, and structured to convey complex information efficiently.

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

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

For a complex tool with no output schema, the description is exceptionally complete. It explains the findings packet, gaps[], contradictions[], hop field, citation_uri, semantic excerpting, latency, and the difference between depth levels. It also covers account prerequisites and when to use alternatives, leaving no significant gaps for an agent.

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

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

Although schema coverage is 100%, the description adds meaning beyond the schema: it elaborates on depth values ('quick=3', 'standard=5 default', 'thorough=8 paid'), clarifies that the question can be broad/multi-part, and explains the hop behavior. This extra context helps the agent select appropriate depth values.

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

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

The description explicitly states the tool performs 'grounded multi-source research across Pipeworx's 1408 STRUCTURED data sources' and explains the decomposition and parallel routing. It clearly distinguishes itself from siblings like ask_pipeworx by noting 'For a single lookup use ask_pipeworx' and 'this is NOT open-web search'.

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

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

Provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and explicit alternatives: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. Also includes account requirements: 'ACCOUNT REQUIRED' and fallback: 'If you are not signed in, use ask_pipeworx instead'.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that results include full input schemas with curated examples ready for direct invocation, eliminating a second lookup step—useful behavioral context beyond the annotations. Minor gap: no mention of output ranking criteria or pagination behavior, but the core safety profile is annotation-covered.

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

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

The description is two sentences long, front-loaded with action and purpose, enumerates domains efficiently, and explains the value-add (ready-to-call results) without padding. Every sentence earns its place.

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

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

For a discovery tool with no output schema, the description explains what it returns (tool names, descriptions, schemas, examples) and situates it within the tool ecosystem. It could mention limit defaults or result ordering, but the described functionality is sufficient for an agent to choose and invoke it correctly.

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

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

Schema coverage is 100% for the six parameters, and the schema already documents aliases (query, q, task, search, description) and limit. The description adds the domain list and that the query is a natural language description, but it largely restates what the schema provides. Baseline 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 opens with a specific verb+resource: 'Find tools by describing the data or task.' It clearly enumerates the domains covered (SEC filings, FDA drugs, FRED, etc.) and differentiates itself from siblings by stating it returns tool recommendations ready to call, contrasting with direct data tools like query_layer 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?

Explicitly instructs 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear when-to-use guidance and implies it is a discovery/selection tool rather than a direct data lookup, distinguishing it from 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?

Discloses behavioral traits beyond annotations: the tool fans out across multiple external services (SEC EDGAR, XBRL, USPTO, GLEIF, GDELT), runs in parallel, and 'soft-fails' for the USPTO PatentsView API sunset. These are valuable operational details not covered by readOnly/idempotent annotations, though latency or partial failure behavior is not fully specified.

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

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

The description is long but dense and well-structured: it front-loads the core purpose, gives usage examples, lists return components in a scannable semicolon-separated format, and includes a critical limitation. Every sentence contributes value, though a slightly tighter phrasing could improve quick comprehension.

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 absence of an output schema, the description covers all major output categories and key constraints (ticker/CIK input, name unsupported, patent API soft-fail). It stops short of specifying exact JSON structure or handling of partial source failures, but it is sufficient for an agent to invoke the tool correctly.

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

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

The input schema already provides comprehensive descriptions for both 'type' and 'value', including examples and the note about names not supported. The tool description essentially repeats this information without adding new semantic detail, so the score remains at the baseline for high schema coverage.

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

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

Description clearly states 'full cross-source profile of a US public company in ONE parallel call' and enumerates returned data types (CIK, filings, fundamentals, patents, news, LEI). It also includes multiple example user phrasings, making the tool's trigger conditions unmistakable.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view', providing strong when-to-use guidance. It also directs users to resolve_entity when only a name is available, clearly distinguishing this tool from that alternative.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description aligns by saying 'Delete'. It adds behavioral context by explaining the rationale for deletion (stale context, sensitive data), going beyond the annotations. No contradiction, but could mention behavior for nonexistent keys.

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 main function, and no unnecessary details. The guidance is concise and actionable.

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

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

For a simple 1-parameter tool with annotations covering safety, the description fully covers purpose, usage, and parameter semantics. No output schema is needed, and there are no gaps.

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

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

Schema coverage is 100% with the property 'key' described as 'Memory key to delete'. The description reinforces 'by key' but adds no additional meaning beyond the schema, so baseline 3 is appropriate.

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

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

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

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

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

Explicitly describes when to use: 'context is stale, the task is done, or you want to clear sensitive data'. Also suggests pairing with remember and recall, providing clear context and related 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, establishing safety. The description adds behavioral context by noting it fetches the page, extracts content, and emits a text blob, which is useful beyond the annotations. It does not contradict annotations, and no rate limits or auth details are mentioned, but for a read-only fetch tool this is acceptable.

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 purpose and proceeds logically to process, output, and use cases. Every sentence adds value, though it is slightly longer than strictly necessary, making it concise but not maximally terse.

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

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

Given the tool's simplicity (2 parameters, no output schema, rich annotations), the description covers purpose, process, output format, and use cases. It lacks error-handling details (e.g., invalid URL), but for a simple read-only generator, it is adequately complete.

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

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

Schema description coverage is 100%, so both parameters (url and max_links) are already well documented in the schema. The description does not add extra meaning about parameters, mentioning only 'any URL' and the output format. With high schema coverage, 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 function: generating a production-ready llms.txt file for any URL. It specifies the verb 'Generate', the resource 'llms.txt file', and the context (AI crawlers indexing sites). It also outlines the process (fetch, extract, emit) and output format, distinguishing it from sibling tools like scan_competitor_ai_presence.

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

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

The description provides explicit use cases ('Useful for: getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), giving clear context for when to use the tool. However, it does not explicitly name alternatives or state when not to use it, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the specific return contents, but it doesn't disclose additional behavioral details like rate limits, authentication requirements, or limitations beyond the purpose itself.

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, efficient sentence that front-loads the tool's purpose and enumerates its output. No wasted words 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 one-parameter tool with no output schema, the description adequately lists what the agent will receive (fields, geometry type, record count, capabilities) and provides an example URL. Annotations cover safety behaviors, making the description complete for the tool's complexity.

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

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

The schema covers the url parameter 100%, and the description only repeats that the tool works 'by url' without adding new meaning. Baseline 3 is appropriate because schema does the heavy lifting.

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

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

The description clearly identifies the action ('Get') and the resource ('ArcGIS Feature/Map Service layer's schema'), and lists the concrete output components (fields, geometry type, record count, capabilities). This distinguishes it from siblings like query_layer, which would query data rather than schema.

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

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

The description implies use for schema retrieval by providing the exact input (url) and output, giving clear context. However, it doesn't explicitly state when to use this tool versus alternatives like query_layer or search_within, nor does it mention exclusions.

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

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

Annotations already declare read-only and idempotent, so the description's job is lighter. It adds behavior by enumerating the return fields (id, type, params, created_at, last_fired_at, fire_count) and notes it's scoped to the caller's subscriptions. 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, no filler. The first sentence states the action and return value; the second gives practical usage guidance. Every word earns its place.

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

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

Given the simple tool shape (one optional parameter, no output schema) and rich annotations, the description provides enough context. It specifies return fields and usage timing, though it doesn't explicitly mention the include_inactive filter, which is covered by the schema.

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

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

Schema coverage is 100% with a well-described 'include_inactive' parameter. The description adds no additional parameter semantics, but the schema already fully documents the single optional parameter, meeting baseline.

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

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

The description 'List the caller's active subscriptions' clearly states the verb and resource, and the second sentence positions it as a review step before subscribing or cancelling, distinguishing it from sibling tools.

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

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

The phrase 'Use this to review what you're monitoring before adding more or to find an id to cancel' explicitly tells the agent when to use this tool—before subscribe or unsubscribe operations. It doesn't name alternatives explicitly but provides clear 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?

All annotations are false, so the description carries the full burden. It discloses rate limiting (5 per identifier per day), cost implications (free, doesn't count against quota), escalation path (digests read daily, roadmap influence), and scope limitation (only Pipeworx tools). This far exceeds annotation coverage.

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

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

Although ~130 words, every sentence serves a purpose: purpose declaration, use cases, exclusion rule, disambiguation heuristic, content guidance, impact expectation, rate limit, and cost info. Dense but efficient, with no filler.

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

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

For a simple feedback tool with no output schema, the description covers all necessary context: what to report, how to report it, when not to report, what happens after reporting, and practical limitations. An agent can decide to use or avoid this tool with full confidence.

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 constraining the message content ('in terms of Pipeworx tools/packs', 'don't paste the end-user's prompt') and implicitly explaining the purpose of the context field with examples. This is a meaningful addition beyond the schema's already-detailed 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 starts with a specific verb ('Tell') and the resource ('the Pipeworx team'), then enumerates the exact use cases (broken, missing, needs to exist). It clearly distinguishes this from sibling tools by being the dedicated feedback channel for Pipeworx-only issues.

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 triggers (bug, feature/data_gap, praise) and an explicit when-not-to-use rule (tools from other MCP servers) with an alternative action (file with that server). Also offers a concrete test to determine if a tool belongs to Pipeworx: 'Pipeworx tool names are the ones this connection lists.'

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

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

The description adds substantial behavioral context beyond the annotations: it explains the data source (CF analytics-engine), confirms no PII, specifies the output format (pack, tool, count), and discloses caching behavior (5min-1h depending on window). This is highly transparent and complements the readOnly/idempotent annotations well.

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 with the core purpose, then expands into numbered use cases, and closes with provenance, privacy, and caching details. Every sentence contributes valuable information without redundancy, making it appropriately sized for the tool's complexity.

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

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

Given the tool has only one simple parameter and no output schema, the description fully compensates by specifying exactly what is returned (top tools, top packs, total call volume), the data source, privacy characteristics, and caching behavior. It is complete and self-contained for an agent to decide whether 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 description coverage is 100%, so the parameter semantics are fully documented in the schema. The description only mentions the window values parenthetically and adds no extra meaning beyond what the schema already states. Thus the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Returns the top tools, top packs, and total call volume over a recent window.' It uses specific verbs and resources, and explicitly frames the tool as an aggregate of other AI agents' activity, distinguishing it from sibling tools like discover_tools 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?

The description provides three explicit use cases (discovering hot data sources, confirming canonical tools, aligning with user needs) under 'Useful for'. It gives clear context for when to use the tool, though it does not explicitly mention when not to use it or name alternatives. This matches a 'clear context, no exclusions' level.

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

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

Annotations declare readOnly/openWorld/idempotent, and the description adds substantial behavioral depth: the Jaccard ≥0.30 semantic anchor, placeholder filtering (>20% returns null signal), fill-check against CLOB depth, and the interpretation of realizable_edge_pp ≤ 0. No conflict 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 each section (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) is tagged for scannability. It front-loads the core purpose and every sentence provides operational detail, with no fluff or repetition.

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

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

Given there is no output schema, the description specifies response fields (opportunities[], partition_check, fill_check results) and critical conditions (null arb on high placeholder fraction, do-not-trade threshold). It also covers alternatives and edge cases, making it self-sufficient for an agent.

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

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

Although the schema already covers both parameters 100%, the description enriches them: `event` explains slug format, child-market walking, ordering checks, and partition_check; `topic` explains seed examples, cross-event flattening, and pattern matching (e.g., 'by May 31' vs 'by Jun 30'). Concrete examples add real value beyond 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 first sentence states 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks', using a specific verb and resource. It distinguishes from siblings by naming `polymarket_fill_risk` as an alternative and clearly enumerates the three invocation modes (no args, `event`, `topic`).

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

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

Provides explicit when-to-use guidance: no args for `trending_scan`, `event` for a specific market (recommended), `topic` for cross-event scanning. It also directs users to `polymarket_fill_risk` for custom sizing and warns not to trade when realizable_edge_pp ≤ 0.

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

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

Although annotations already mark the tool as read-only and idempotent, the description goes well beyond them by disclosing complex runtime behavior: five model families, per-leg Kelly caps, placeholder-slug filtering, slippage handling, 24h-move warnings, diagnostics funnel counters, and KV-level caching. This gives the agent deep insight into what the call will actually compute and return.

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

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

The description is well-structured with uppercase section markers and a clear opening sentence, but it is extremely long and contains niche details (e.g., 'gates relaxed Run 8 from prior 85%/5%/50:1' and OIS/SOFR-futures data caveat) that could be trimmed for easier ingestion. It trades conciseness for exhaustive transparency.

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

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

With no output schema present, the description takes on the full burden of explaining return values and does so thoroughly: top-level segments, per-opportunity fields, diagnostics, and filtering behavior are all described. Caching, default windows, and edge-case handling are also covered, making the tool self-contained enough for correct invocation.

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

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

The input schema already covers all 9 parameters at 100% with detailed descriptions, so the baseline is 3. The description adds non-obvious semantic context, such as how min_partition_leg_kelly applies to per-leg Kelly inside top_legs and how slippage_pp interacts with edge_pp_net, which is genuinely useful beyond the schema text.

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

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

The description opens with a specific verb+resource+outcome: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It further distinguishes the tool by naming its three response segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), making its role as a market-edge discovery tool clear versus sibling Polymarket 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: built for 'what should I bet on today' and enabling agents to 'discover opportunities without paging hundreds of markets.' It also gives a notable when-not caveat, stating Fed bets are 'excluded from ranking' due to unreliable signal data, but it does not explicitly name sibling alternatives or offer an exhaustive when-to-use comparison.

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

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

Beyond readOnlyHint and idempotentHint, the description discloses key behaviors: 60-day snapshot TTL, cache-miss snapshot writing, gaps meaning no scan that day, and that decay is based on daily closes not intraday. It also explains the meaning of expired opportunities, adding substantial context.

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

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

The description is long but every sentence delivers essential information, from purpose to response structure to limitations. It is well-organized with clear sections (RESPONSE, LIMITS) and no fluff, making the length justified.

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

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

With no output schema, the description thoroughly details the return format including tracked, expired, and snapshot_dates, along with edge cases like data gaps and TTL. It provides complete operational context for an agent to use 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% with both parameters already described (days lookback with clamp, window family). The description restates these defaults and semantics without adding new meaning, so it does not elevate beyond the baseline for fully documented schema.

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

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

The description clearly states it provides 'edge persistence and decay telemetry' built from daily snapshots, answering a specific question about edge age and trend. It differentiates from sibling tools by focusing on time-series behavior rather than current edge 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?

It implies when to use this tool by contrasting fresh vs. 3-week-old edges, suggesting it is for historical edge analysis. However, it does not explicitly name alternative tools or state when not to use it, though the sibling context makes the distinction fairly 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 richly details behavioral traits beyond the read-only and idempotent annotations: it walks the order-book ladder, computes top-of-book vs VWAP, returns per-leg fill details, identifies thin legs, and warns about forced directional risk. It explains the difference between single-market and basket execution, and the nuance of size_usd interpretation. This far exceeds the annotations' baseline and gives the agent a clear mental model of what happens during invocation.

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 adds operational value. It is front-loaded with a crisp purpose statement, then logically structured into REQUIREMENTS, SINGLE-MARKET, BASKET, and usage guidance. The density is appropriate for the tool's complexity (two modes, four parameters, multiple return values). No fluff 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?

The description fully covers the tool's modes, parameters, return values (top_of_book, vwap_fill_price, slippage_pp, verdict, etc.), and risk context (thin books, partial fills, unhedged directional risk). Given the absence of an output schema, the description compensates by enumerating key outputs and their semantics. It is complete enough for an agent to select and invoke the tool correctly.

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

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

Even though the input schema already provides 100% description coverage, the tool description adds essential meaning: it clarifies that 'size_usd is max spend on buys, target proceeds on sells' in single-market mode, and 'settlement notional S (shares per leg; each share pays $1)' in basket mode. It also explains side defaults (auto from partition sum) and the requirement to pass exactly one of market/event. This goes well beyond the schema descriptions.

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

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

The description opens with a clear purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It explicitly distinguishes two modes (single-market and basket), and contextually separates itself from sibling tools by naming when it should precede polymarket_arbitrage or polymarket_edges trades. This is a specific verb+resource+scope description that fully clarifies what the tool does.

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: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the failure mode (partial basket fills converting arb into unhedged directional position), giving clear rationale for using the tool over alternatives. Single-market vs basket mode prerequisites are also stated.

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 and idempotentHint, so no contradiction. The description adds substantial behavioral context: how compatibility_warning fires, the meaning of skipped_cross_type/subtype, temporal alignment, and the fact that most pre-mapped topics return warnings. This exceeds the minimal requirement and fully discloses edge cases.

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

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

The description is lengthy, but each paragraph/section adds value: purpose, modes, response fields, and safety field explanations. It uses CAPS and structured sentences to improve scannability. It is not as tight as the TDQS 4.3 example, but the complexity of the tool justifies the length.

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

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

Given no output schema, the description fully explains return values (leg prices, spread, compatibility_warning, temporal_alignment, skipped_cross_type). It also covers failure modes and why spreads may not be meaningful. For a tool with this complexity, this is complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes further by explaining the two operational modes and how the parameters interact (topic shortcuts vs explicit overrides), and it enumerates the valid topic values. This adds meaningful semantics beyond the schema, though the schema already documents each parameter thoroughly.

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: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly names the two venues and the concept of a spread, distinguishing it from single-venue tools like polymarket_arbitrage. The two modes (topic shortcuts vs explicit ticker/slug) further clarify what the tool does.

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 strong when-to-use guidance: explains the two modes and when to use each. Also gives explicit when-not-to-use warnings (compatibility_warning conditions, 'pre-mapped ≠ tradeable') and describes scenarios where spreads are meaningless (temporal misalignment). However, it does not explicitly name alternative tools, so it stops short of a 5.

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

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

Annotations already declare this as a safe, read-only, idempotent operation, so the bar for additional transparency is lower. The description adds useful behavioral details beyond annotations: it states the return type (attribute rows and geometry) and offers a practical sampling strategy. It does not elaborate on errors or rate limits, but the existing coverage justifies a 4.

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 exactly two sentences. The first sentence front-loads the main purpose and key parameters, while the second gives a practical tip. 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?

With a fully-documented schema and safety annotations, the description fills remaining gaps: it specifies the return type (attribute rows and geometry) and how to sample data. It lacks an output schema and does not mention potential error scenarios, but for a read-only query tool this is well-covered.

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

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

Schema description coverage is 100%, so parameters are already well-documented. The description adds semantic nuance by calling the where clause 'SQL-like', clarifying out_fields as comma-separated, and providing a concrete usage example (where='1=1' + out_fields='*'), which are valuable 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 with a specific verb ('Query') and resource ('ArcGIS Feature Service / Map Service layer'). It also distinguishes itself by referencing 'from search_datasets' and listing core capabilities (where, out_fields, order_by, limit, offset), making its role distinct from sibling tools like layer_info.

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

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

The description provides clear context for use, indicating it queries layers obtained from search_datasets and gives a concrete sampling tip. It does not explicitly mention when not to use it or name alternative tools, so it stops short of full exclusion guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful context beyond annotations: scoping to identifier, listing behavior when key omitted, and the relationship to save/delete operations. It doesn't describe behavior on missing keys or return format, but this is minor.

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

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

Three sentences, front-loaded with the primary action, then context and scoping. Every sentence adds value with no redundancy or fluff.

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

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

For a low-complexity tool with one optional parameter, the description covers purpose, usage, scoping, and key behavior. It doesn't specify return format or missing-key behavior, but the output is likely self-evident from the retrieval context, so the description is sufficiently complete.

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

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

Schema coverage is 100% with the single key parameter described. The description adds extra meaning by explicitly explaining that omitting the key lists all saved keys, which goes beyond the schema. It also provides example keys to clarify usage.

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 retrieves a value saved via remember or lists all saved keys, using a specific verb and resource. It also distinguishes itself from sibling tools like remember and forget by describing the retrieval function.

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

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

Explicitly states when to use the tool: to look up previously stored context without re-deriving it. It also references sibling tools remember and forget, giving clear usage alternatives and pairing.

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

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

The annotations declare readOnlyHint:true and idempotentHint:true, yet the description says 'Set mark_read:true to flag returned events read so the next call only shows newer ones.' This is a clear state mutation, directly contradicting the read-only hint. No other behavioral disclosures (e.g., rate limits, auth) are provided, so the description fails to add trustworthy 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 five sentences, starting with the core purpose, then return format, filtering, mark_read behavior, and an alternative access method. Every sentence contributes useful information, and there is no filler or repetition.

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

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

For a read-focused tool with five optional parameters and no output schema, the description covers the return fields, filtering semantics, the mark_read side effect, and polling suitability. It also points to the same feed via HTTP for scripting. The only gap is the contradiction with readOnlyHint, but that's a transparency issue rather than a completeness gap regarding expected behavior.

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

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

The schema covers 100% of parameters with descriptions, so the baseline is 3. The description adds value by providing an example for type ('sec_8k'), clarifying the 'since' timestamp format, and explaining the effect of mark_read on subsequent calls. This goes beyond the schema without being excessive.

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 'Pull fired events from your subscription feed' and specifies that it returns the most recent alerts with source, citation_uri, and raw payload. This distinguishes it from related tools like list_subscriptions, which manage subscriptions rather than events.

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

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

The description gives practical usage guidance: 'Filter by type (e.g. "sec_8k") and/or since (ISO timestamp)' and explicitly notes that 'Polls work fine' while also mentioning an alternative HTTP endpoint for scripts/dashboards. It lacks an explicit exclusion of other sibling tools, but the context is clear.

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

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

The description discloses behavior beyond the annotations: it details the fan-out to SEC EDGAR, GDELT→GNews fallback (including when fallback triggers), USPTO soft-fail due to API sunset, and the exact return structure. Annotations only say readOnly/openWorld/idempotent, so this context is valuable.

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

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

The description is dense but well-structured: example queries first, then core function, then source details, parameter specifics, return type, and alternative tool. Every sentence adds information, though the length is above average. It's not a model of brevity but earns its 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 description is complete for a complex tool with no output schema. It explains what the tool returns (structured changes[] with source grouping, total_changes, citation URIs), covers all sources and their failure modes, and addresses parameters. The agent has enough to invoke it correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds important semantic details: it explains the `since` parameter accepts ISO date or relative shorthand with concrete examples ('7d', '30d', '3m', '1y'), and clarifies `value` can be a ticker or CIK. This goes beyond the schema's descriptions.

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

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

The description clearly states the tool's purpose: 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It specifies the resource (company change feed) and the action (retrieve recent changes), and distinguishes it from the sibling tool entity_profile, which provides 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?

The description explicitly provides usage context with example queries like "What's new with X" and "updates on Acme." It also names an alternative: 'Use entity_profile instead when you want the static profile... regardless of window.' This clearly tells the agent when to choose this tool over a specific sibling.

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

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

Beyond annotations, the description adds crucial behavioral details: key-value storage scoped by identifier, persistence for authenticated users, 24-hour TTL for anonymous sessions, and the pairing with recall/forget. This goes well beyond what annotations already declare.

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

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

The description is compact and front-loaded with the primary action. Every sentence adds value: usage guidance, storage model, persistence behavior, and sibling pairing. No fluff or redundancy.

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

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

For a simple two-parameter tool with no output schema, the description covers use cases, persistence behavior, TTL, scoping, and how it fits with recall and forget. It is complete for an agent to select and invoke correctly.

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

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

Schema description coverage is 100% and both parameters are well-described in the schema. The description reinforces with examples of keys and values but does not add new parameter-level semantics beyond what the schema already provides.

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

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

The description opens with a specific verb and resource: 'Save data the agent will need to reuse later.' It clearly distinguishes from sibling tools by explicitly mentioning 'Pair with recall to retrieve later, forget to delete,' and by noting scope across conversations and sessions.

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

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

Provides explicit guidance: 'Use when you discover something worth carrying forward' with concrete examples (ticker, address, preference). Names alternatives (recall, forget) for complementary operations, making the usage context unambiguous.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description goes beyond by revealing that each call cascades through several internal lookup endpoints and auto-disambiguates inputs, plus it outlines return values and citation URIs. This provides useful behavioral context beyond the structured hints.

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

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

The description is dense with useful information but remains well-organized, starting with example queries and then detailing types. It is slightly long but each sentence adds value, covering purpose, usage, return data, and internal behavior 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 having no output schema, the description fully explains what the tool returns for each entity type (company: ticker, CIK, company_name, citation URI; drug: RxCUI, ingredient, brand, citation URI). It also covers input variations and the internal cascading behavior, making it complete for an agent to use effectively.

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

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

Schema coverage is 100%, and the schema already describes both parameters. The description adds extra context by explaining how 'value' is interpreted per 'type', including examples ('AAPL', '0000320193', 'ozempic'). It also clarifies that company input accepts ticker, CIK, or name with auto-disambiguation, which is 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: resolving user-spoken names to canonical identifiers (e.g., ticker, CIK, RxCUI). It provides concrete example queries and explicitly distinguishes it as the go-to tool for name-to-ID lookup, setting it apart from siblings like entity_profile or compare_entities.

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

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

The description gives explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains what each supported type returns and how the tool replaces multiple manual lookups. However, it does not explicitly mention when not to use it or name direct alternatives, so it misses the full 'when-not' guidance.

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

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

Beyond annotations (readOnly/openWorld/idempotent/non-destructive), description discloses that it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. This adds behavioral detail not captured by annotations.

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

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

Three sentences, front-loaded with main purpose, then behavior, then use case and output. 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?

Despite no output schema, description specifies the output shape (ranked list with score, confidence, signal density) and explains the tool's internal process and intended use case, making it complete for an AI agent to decide 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?

Since schema covers 100% of parameters with descriptions (including first-entity-as-subject, supported models, _apiKey requirement, context use), description adds no new parameter-level meaning beyond what the schema already provides, so baseline 3 applies.

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

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

Description uses specific verb 'Compare' and resource 'AI visibility across multiple entities side-by-side,' explicitly names ai_visibility_check as probe, and differentiates from sibling compare_entities by focusing on AI presence and ranking by score.

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

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

Provides clear context: 'Useful for competitive AI-marketing audits' with a concrete example question. Does not explicitly state when not to use it or name alternative tools (e.g., compare_entities), so only 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?

The description discloses partial failure behavior: 'Partial failures degrade gracefully — bundlephobia’s first measurement on a new version can take 5-30s; sources_failed will list it if it times out, the rest still returns.' It also adds the NPM-only limitation and the fact that it fans out to multiple sources. This goes beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) by providing latency and error-handling context. There is 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 efficiently structured: it opens with the core purpose, then use cases, then return contents, then ecosystem scope, then failure behavior. Every sentence adds necessary information without redundancy. Despite being longer than typical descriptions, it earns its length with useful details.

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

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

This is a complex tool (composite of two external services) with no output schema. The description lists all returned summary fields (is_latest, license, published_at, advisory_count, bundle_kb_min, bundle_kb_gz, dependency_count, has_esm, tree_shakeable), per-advisory detail, links, and alternative versions. It also explains the NPM-only scope, the external dependencies, and the latency/failure behavior. This is complete for its complexity.

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

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

The input schema has 100% coverage: 'package' is described as an npm package name with scoped packages accepted, and 'version' is described as optional with default to latest. The tool description does not add any additional parameter semantics beyond what the schema already provides, so it receives the baseline score of 3.

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

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

The description clearly states a specific verb and resource: 'Composite “should I add this npm package to my project” check in ONE call'. It also lists the exact data sources (deps.dev and bundlephobia) and what aspects each covers (license, advisories, version history, bundle size, dependency count, ESM/tree-shake support). It distinguishes itself from siblings by explicitly limiting to NPM ecosystem in v1 and directing other ecosystems to deps.dev:version directly.

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 usage triggers: 'Use whenever an agent asks “is X safe / popular / small” or “what does adding lodash cost me”'. It also provides an exclusion/alternative: 'PyPI / Maven / Cargo / Go fall under deps.dev:version directly', making clear when not to use this tool. This satisfies both when-to-use and when-not-to-use.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds behavioral detail by listing exactly what is returned (name, summary, record_count, owner/org, Feature Service url) and the recommended follow-up action. This goes beyond 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 main action, and then compactly details return values and integration with other tools. There is no redundancy or unnecessary wording.

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 search tool with optional parameters, rich annotations, and no output schema, the description provides enough context to invoke it correctly and interpret results. It also explains the purpose of the returned URL, making the tool's role in the workflow clear.

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

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

The input schema already provides full descriptions and examples for all parameters, covering them 100%. The description adds domain context (e.g., parcels, zoning) but does not significantly enhance understanding of the parameters themselves beyond what the schema offers, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool searches City of Courtenay GIS open geospatial datasets by keyword, and lists example dataset categories (parcels, zoning, parks & city services). It specifies the resource and action distinctly, and differentiates from siblings like query_layer and layer_info by indicating the returned URL is for them.

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

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

The description implies use for discovering datasets before querying, and explicitly instructs passing the returned URL to query_layer or layer_info. However, it does not explicitly state when not to use this tool or compare it to alternative search tools like search_within, so it lacks 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?

Beyond the annotations (readOnlyHint, idempotentHint), the description discloses the embedding model (BGE-base-en), windowing approach (500-char overlapping windows), similarity metric (cosine), and the 200K char cap with truncation flagging. This gives the agent solid expectations about behavior and limitations.

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

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

The description is a bit long but front-loads the core purpose and each sentence provides distinct value (purpose, usage, pairing, technical behavior). The structure is logical, moving from what it does to when to use it to how it works.

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 adequately covers the return format (passages with offsets and similarity scores), the main use case, and the technical constraints. It also situates the tool among siblings by suggesting a pair with ask_pipeworx_grounded. This is complete enough for an agent to select and invoke the tool correctly.

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

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

The input schema already covers 100% of parameters with meaningful descriptions. The description adds context (e.g., 'text you already pulled', 'top-N passages') but doesn't significantly expand on the schema's own parameter documentation. 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 performs 'Semantic search INSIDE a fetched record', with concrete examples (SEC 10-K body, article, tool result). It distinguishes itself from siblings by the 'fetched record' scope and pairs explicitly with ask_pipeworx_grounded, which is a different workflow.

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 an explicit use case: 'Use when the record is too big to cram into the prompt', and explains the benefit (saves context, returns only relevant passages). It also suggests pairing with ask_pipeworx_grounded for grounding over relevant passages. It does not explicitly state when not to use, but the guidance is clear enough.

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

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

Annotations already convey readOnlyHint=false and destructiveHint=false. The description adds valuable behavioral context: OAuth requirement, phone verification and daily cap for SMS, always-on feed channel, and returns a subscription ID. However, it does not explain the idempotency behavior hinted by idempotentHint=true, leaving ambiguity about duplicate subscriptions. Still, 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 a single dense paragraph but well-structured with 'Supported types' and 'Delivery channels' sections, front-loading the core purpose. Every sentence provides useful information. It is somewhat long but appropriate for a tool with multiple subscription types and channel options; no redundant 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?

With no output schema, the description compensates by stating 'Returns the new subscription id' and outlining delivery behavior. It covers the main operational aspects, including type-specific params and channel settings. It does not describe error handling or duplicate subscription semantics, but given the complexity and available schema detail, 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 schema covers all parameters at 100%, but the description enriches meaning with real-world examples: items:["5.02"] = officer change, topic:"fed", series_id:"UNRATE", and details on delivery channel constraints (verified phone, cap). These clarifications go beyond the schema's descriptions, helping the agent select appropriate param values.

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

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

The description clearly states the tool's function with a specific verb+resource: 'Create a proactive monitoring subscription to a live-data event stream.' It distinguishes itself from sibling tools like recent_alerts (pull) and unsubscribe (remove), and enumerates the supported subscription types, making the purpose unmistakable.

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

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

The description provides explicit prerequisites ('Requires a Pipeworx OAuth account') and exclusions ('anonymous + BYO cannot persist'), plus alternative actions like 'pull via recent_alerts'. It does not explicitly name list_subscriptions/unsubscribe as alternatives, but the context is clear enough. The mention of delivery channel options and their conditions (verified phone, cap) adds practical usage guidance.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. Beyond that, the description adds valuable context about the return format (category-bucketed example questions, each with exact tool + argument shape), the data source (live catalog of thousands of tools), and the ability to focus via a topic. No contradiction with annotations.

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

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

The description is dense but front-loaded with example queries that help an agent recognize triggers. It is a single paragraph with all necessary information, and while it is somewhat long, every clause contributes to understanding the tool's purpose, usage, and output. No wasted sentences.

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

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

There is no output schema, so the description carries the burden of explaining the return value; it does so clearly (category-bucketed example questions with tool + argument shape). It also explains the optional parameter, the no-argument behavior, and when to use this tool first. The description is fully complete for an agent to invoke this tool correctly.

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

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

The input schema already provides a full description of the single 'topic' parameter, including all allowed values and the default behavior when omitted. The description adds example values (finance, pharma, betting) and the word 'focus,' but this is marginal beyond the schema's own coverage. Baseline 3 is appropriate because schema coverage is 100%.

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

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

The description clearly states that this is the onboarding entry point for an agent that just connected, returning category-bucketed example questions with the exact tool and argument shape. It is specific about the verb (suggest), resource (what can I ask Pipeworx), and explicitly distinguishes itself from siblings by saying 'Use this FIRST' and referencing meta-tools like ask_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?

It provides 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 explains when to call with no arguments vs. passing a topic, and gives alternatives (ask_pipeworx, entity_profile, compare_entities) for learning how to call meta-tools.

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

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

Annotations already declare idempotent and non-destructive, but the description adds that the row is deactivated not deleted, preserving historical events — a behavioral nuance not captured by annotations.

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

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

Two sentences, front-loaded with the action, and every clause adds value (ownership constraint, soft-delete behavior).

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

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

For a single-parameter tool with rich annotations and no output schema, the description covers the core operation, the side effect, and the alternative for historical access, making it complete enough 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?

The schema fully describes the id parameter (100% coverage), including 'returned by subscribe'. The description merely repeats 'by id', adding no new semantic information.

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

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

The description uses 'Cancel a subscription by id' — a specific verb (cancel) and resource (subscription), clearly distinguishing it from sibling tools like subscribe and list_subscriptions.

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 states ownership is enforced (only your subscriptions) and that deactivation keeps history accessible via recent_alerts, giving context for when to use. However, it doesn't explicitly compare against list_subscriptions or subscribe for alternative scenarios, so it's clear but not exhaustive.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds substantial context beyond these: the structured SEC EDGAR + XBRL fast path with percent-delta math, the fallback grounded pipeline with verbatim evidence, and the list of possible verdicts. This gives the agent a clear mental model of internal processing without contradicting any annotation.

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

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

The description is a single dense paragraph that front-loads natural-language triggers and then methodically explains the two routing paths, return value, and efficiency gain. Every sentence contributes unique information; it is longer than strictly necessary but not bloated. It is well-structured and scannable despite its length, earning a 4 rather than 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?

With no output schema, the description fully covers return values: verdict types, actual value with citation, and reasoning. It also clarifies the tool's scope (all factual claims), special-cases company-financial claims, and explains how it compresses multiple sequential calls into one. For a tool of this complexity, the description is complete and self-contained.

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

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

Schema description coverage is 100% for both parameters ('claim' and 'tolerance_pct'), with detailed explanations in the schema itself. The description adds no extra parameter semantics beyond mentioning 'exact percent-delta math' which indirectly relates to tolerance. Given high schema coverage, baseline 3 is appropriate—the description does not improve on what the schema already provides.

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

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

The description opens with concrete natural-language examples ("fact check", "verify the claim that…") and immediately states the core function: natural-language claim verification against authoritative sources. It clearly distinguishes this tool from siblings by naming the specific task (fact-checking) and the output (verdict + evidence), making its purpose unambiguous.

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

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

Explicitly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also differentiates between company-financial claims and other factual claims, explaining routing to different backends. However, it lacks explicit 'when not to use' or named alternative tools, which would push it to a 5.

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