Arcgis Montana

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so the description's value lies in disclosing the free default model, the direct-billing implication of passing a key, and the return structure. This adds economic and output context beyond the annotations. No contradiction.

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

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

The four-sentence description is tightly packed, starting with the core function, then model options, return format, and use cases. No filler; every sentence adds distinct information.

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

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

The description covers the lack of an output schema by specifying per-model and combined response shapes, and outlines the tool's use cases. It could add more detail on 'signals' or error behavior, but it is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, providing a baseline of 3. The description goes beyond by clarifying the default model, the direct payment implication for Anthropic, and the fact that _apiKey is passed straight through. This is meaningful additional context, especially around the models parameter.

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

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

The description uses a specific verb ('Probe'), defines the resource (one or more LLMs), the subject (business/brand/product/topic), and the output (visibility score 0-100). It clearly distinguishes itself from siblings by focusing on LLM awareness scoring rather than generic Q&A or research.

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

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

The description provides clear usage context ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the default vs BYO-key model choice. However, it does not explicitly mention when not to use this tool or name alternative sibling tools.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds valuable context beyond that: it routes across 5,798 tools, fills arguments automatically, and returns structured answers with stable pipeworx:// citation URIs. It could mention limitations or failure modes, but the core behavior is well disclosed.

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

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

The description is long but front-loaded with the most important routing directive and domain scope. The example list is slightly generous, but each section adds practical guidance. It is dense rather than padded.

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 broad routing tool with no output schema, the description covers when to use it, what it does internally, what the answer looks like (structured answer + citations), and how to choose among siblings. Nothing critical is missing for an agent 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 the schema already explains the question parameter and its aliases. The description adds semantic value by enumerating the kinds of questions that work and providing concrete examples, which helps the agent choose appropriate query phrasing.

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

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

The description names a specific action—routing a natural-language question to the right tool among thousands—and clearly defines the resource domain: current/historical real-world data with citations. It explicitly contrasts itself with siblings like ask_pipeworx_grounded and deep_research, so an agent can tell it apart.

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

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

It gives direct preference instructions ('PREFER OVER WEB SEARCH'), lists concrete trigger phrases and example queries, and carves out when to use alternatives like ask_pipeworx_grounded or deep_research. The guidance is actionable and 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?

The description adds substantial behavioral context beyond the readOnly/idempotent annotations: it is a beta under live test, may change behavior when a candidate is active, currently matches ask_pipeworx exactly, and is a full working router rather than a fallback. This is exactly the kind of nuance an agent needs.

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

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

The description is dense and front-loaded with the beta identity and current active-candidate status. Each sentence earns its place, though the date and the exact tool count add specificity without being strictly necessary.

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

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

Given the absence of an output schema, the description adequately points to the same response shape as ask_pipeworx and tells the agent to use it exactly like that sibling. It is complete enough for invocation, though explicit output details would remove reliance on the sibling description.

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

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

Schema description coverage is 100% and all six parameters are aliases for 'question', so the structured schema already carries the full parameter semantics. The description adds no parameter-level detail, which is acceptable given the schema coverage, but it does not go beyond it.

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

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

The description clearly identifies this as the beta version of ask_pipeworx: an identical universal router with the same 5,798 tools, arguments, and response shape. It distinguishes itself from the stable sibling by labeling the experimental edge and explicitly stating 'this is a full working router'.

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

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

It explicitly says to use it exactly like ask_pipeworx when you want the newest routing, and notes that results are compared against the stable router to decide merges. However, it does not explicitly state when not to use it or mention grounding alternatives like ask_pipeworx_grounded.

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

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

Beyond the readOnly/idempotent hints, the description exposes the refusal behavior, output shape, evidence requirement, and the extra LLM call cost. It tells the agent exactly what happens when data is missing or insufficient.

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

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

Dense but mostly front-loaded: the core behavior and output contract appear first, followed by use cases and cost comparison. It could trim the illustrative tool-count detail and some redundancy in 'hallucination-resistant' vs 'ONLY what the tool result contains,' but nothing is extraneous.

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 supplies the full return shape and refusal reasons. The single parameter is already covered by the schema, and annotations cover safety. An agent has everything needed to call it correctly and interpret the result.

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

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

Schema description coverage is 100% and the schema fully documents the question parameter and its aliases. The description adds no extra parameter details, so it does not need to compensate; 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 defines a grounded answer mode: it routes, fetches, and extracts an answer using only the tool result. It explicitly contrasts with ask_pipeworx, so an agent can distinguish this grounded variant from the casual-lookup sibling.

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

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

It gives precise when-to-use conditions: answers that will be quoted, cited, or acted on, plus examples (financial verdicts, legal claims, medical lookups, public statements). It also says when not to use it: casual lookups should prefer ask_pipeworx.

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=true, openWorld, idempotent), the description discloses fan-out parallelism, resolver confidence gating (low_confidence_match short-circuit), closed-market status handling, wide-spread tradeability flag, news fallback behavior (_fallback_attempted), and cancellation-rule parsing. Rich context with no contradiction to 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?

Long but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY). Each section contains specific operational detail. A few sections (resolver and safety) overlap slightly, but the density is justified by the tool's complexity.

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

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

With no output schema, the description compensates thoroughly by documenting response shapes (result.market, result.analysis, result.evidence), resolver contract, parent_event extraction, news fields, and edge-case statuses. It covers safety, illiquid markets, and cancellation risk, making it complete for a complex tool.

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

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

Schema already covers all 3 parameters with descriptions. The description adds value with concrete input examples (slug, URL, question text), explains classification-driven fan-out, and details include_raw's behavior (payload sizes, recommended false). This exceeds the schema baseline.

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

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

The description opens with a specific verb ('Research') and resource ('a Polymarket bet') plus scope ('pulling the relevant Pipeworx data for it in one call'). It clearly distinguishes the tool from siblings like ask_pipeworx and polymarket_edges by targeting bet-specific research with fan-out.

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

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

Explicit 'Use for' phrases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') provide clear context. It also warns when to check cancellation rules before sizing event bets. However, it does not explicitly name when-not-to-use or alternative tools, so it stops short of 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?

Even though annotations already declare read-only/idempotent behavior, the description adds substantial behavioral detail: company type pulls 10-K revenue/net income/cash/debt from SEC EDGAR/XBRL with off-calendar fiscal years handled correctly, drug type pulls FAERS/FDA/trial counts, results are sorted by primary metric, and paired data includes citation URIs. No contradictions with annotations.

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

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

The description is front-loaded with trigger phrases and the core instruction in the first two sentences, and later sentences are information-dense. It is slightly long but every sentence contributes useful behavior or context, so it remains well-structured.

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

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

With no output schema, the description covers the key return characteristics (paired data and pipeworx:// citation URIs) and result ordering. It also covers type-specific behavior, fiscal-year handling, and input constraints, making it complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% for both parameters, and the description supplements the enum by explaining exactly what each type ('company' vs 'drug') retrieves. It also clarifies the values array sizing (2–5) with examples, adding real semantic value beyond the schema.

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

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

The description clearly identifies a compare verb with a bounded resource (2–5 companies or drugs) and provides concrete trigger phrases. It distinguishes itself from single-entity lookup tools by emphasizing one parallel call and 'ALWAYS PREFER 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?

Explicit usage guidance is given via query patterns ('X vs Y', 'which is bigger...') and a direct instruction to prefer this tool over sequential lookups when comparing entities. It also names the count replacement ('Replaces 8–15 sequential lookups'), giving clear context for when to choose it.

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

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

The description adds substantial behavioral context beyond the annotations (readOnlyHint=true, openWorldHint=true, idempotentHint=true): it explains the findings packet structure, explicit gaps[] with 'never invented', contradictions[] for standard/thorough, always-fetchable citation_uri behavior, semantic excerpting, multi-hop iteration, and expected latency (15-60s, up to ~90s). It also discloses the sign-in/paid-tier requirement. 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 dense and front-loaded with critical operational details (account requirement and fallback) before the core functionality. Every sentence conveys useful information, but the structure is somewhat sprawling—account guidance appears twice, and the long parenthetical on iteration details could be tightened. This is minor given the complexity, so it earns 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 carries the burden of explaining return values, which it does in detail: findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], hop field, and citation_uri behavior. It also covers prerequisites (sign-in), timing, limits (thorough requires paid plan), and the fallback sibling, leaving nothing an agent needs to call or interpret the tool correctly.

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

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

Schema description coverage is 100% with both parameters thoroughly documented in the input schema itself: `question` notes 'Broad/multi-part is fine — decomposition is the point,' and `depth` already enumerates quick/standard/thorough with defaults, paid status, and hop behavior. The tool description mostly restates this information and does not add meaningful parameter semantics beyond what the schema already 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 states a highly specific verb and resource: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources' that 'decomposes your question... routes each to the right one of 5,798 tools IN PARALLEL, and returns a findings packet.' It also explicitly distinguishes itself from open-web search ('this is NOT open-web search') and from the single-lookup sibling ask_pipeworx, making the tool's purpose unmistakable.

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

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

Usage guidance is explicit and thorough: 'Best for broad/multi-part questions over structured data' and 'For a single lookup use ask_pipeworx instead' gives a clear when-to-use/when-not-to-use pair. It also names the fallback alternative when not signed in: 'If you are not signed in, use ask_pipeworx instead — it works on every tier.' This directly routes agents to the correct sibling under clear conditions.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering the safety profile. The description adds valuable behavioral context: it returns top-N tools with names, descriptions, and full input schemas including curated examples, and states 'no second schema lookup needed.' This is actionable beyond the annotations.

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

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

The description is three sentences: purpose, usage context, and return behavior. It is front-loaded with the core 'Find tools by describing the data or task' and every sentence carries distinct, essential information. The domain list is compact but informative.

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 thoroughly explains what the agent will receive (top-N tools with full schemas and examples) and how to use the tool first. It fully covers purpose, usage, output, and placement relative to other tools, making it complete for an agent.

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

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

Schema description coverage is 100%, with detailed descriptions for query, limit, and alias parameters. The description does not add meaningful semantics beyond the schema—it reinforces that query is a natural language description but does not introduce new details. Baseline 3 is appropriate.

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

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

The description opens with 'Find tools by describing the data or task,' clearly stating the verb and resource. It lists specific domains (SEC filings, FDA drugs, FRED, etc.) and distinguishes itself from sibling search/research tools by positioning as a meta-tool that returns tool schemas.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides concrete when-to-use context and implies when not to use (when you already know the specific tool).

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

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

Beyond readOnly/openWorld/idempotent annotations, the description discloses significant runtime behavior: fan-out across sources, soft-fail behavior for the USPTO PatentsView API, sources_used/sources_failed, empty sections meaning real 'no data,' and private companies returning resolved:false with notes. This exceeds what annotations alone provide.

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

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

The description is long, but it carries a high density of essential behavioral and output details for a complex multi-source tool. It is front-loaded with user intents and the key preference instruction. A little more formatting or brevity would improve scannability, but no sentence feels wasted.

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

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

With no output schema, the description is responsible for explaining return values, and it does so thoroughly: it enumerates the sections (filings, fundamentals, patents, contracts, FDA products, hiring, news, LEI) and clarifies edge cases like empty FDA results and resolved:false. The description is complete enough for an agent to invoke the tool correctly and interpret results.

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

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

Schema coverage is 100% with decent field descriptions, so baseline is 3. The description adds meaningful extra semantics: `type` values behave identically, `value` can be a ticker, zero-padded CIK, or company name, and names resolve via SEC EDGAR with explicit private-company behavior. These additions go beyond the schema documentation.

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

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

Description states a clearly specific action: build a 'full cross-source profile of a US public company in ONE parallel call' with concrete example intents like 'research Acme' and 'brief me on Tesla.' It distinguishes itself from more targeted lookups by explicitly instructing to prefer it over chaining single-pack SEC/XBRL/news 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 strong when-to-use guidance: trigger phrases, 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' and explains fallback behavior for private companies. It does not explicitly contrast with sibling tools like compare_entities or resolve_entity, but it names the relevant alternative class and the condition that selects this tool.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the agent knows the operation is destructive and repeatable. The description adds the 'clear sensitive data' use case but does not detail further behavioral traits, so transparency is adequate but not enriched beyond annotations.

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

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

Three short sentences, front-loaded with the action. No filler or redundant information.

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

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

For a simple one-parameter delete tool, the description covers purpose, usage scenarios, and relationships. It doesn't specify idempotent behavior or error handling, but annotations fill that gap, making it mostly 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 100% of parameters with a clear description ('Memory key to delete'). The description only echoes 'by key' and does not add additional semantic detail 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 opens with a specific verb and resource: 'Delete a previously stored memory by key.' This clearly states the tool's function and distinguishes it from sibling tools like remember and recall.

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

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

Explicitly states when to use: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' Also advises pairing with remember and recall, giving contextual guidance.

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

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

Annotations already indicate a safe, read-only, idempotent operation. The description adds valuable behavioral context: it fetches the page, extracts key content, and emits a single text blob for site-root placement. This goes beyond annotations by explaining the internal workflow and output format.

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

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

Three sentences, front-loaded with the primary action. Every sentence earns its place: what it does, how it works, and when to use it. 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?

Despite lacking an output schema, the description explains the output format ('standard llms.txt markdown', 'single text blob ready to drop at site-root/llms.txt'). It covers input, process, output, and use cases, making it complete for a tool of this complexity 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 coverage is 100%, so the baseline is 3. The description mentions 'key links' which relates to max_links, but it doesn't add much beyond the schema's own parameter descriptions. The schema already documents url and max_links adequately.

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

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

The description uses a specific verb ('Generate') and names the exact resource (llms.txt file for any URL), clearly distinguishing it from sibling tools. It states what the tool does: fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. This is a specific, non-tautological purpose statement.

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

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

The description provides clear use cases: indexing a client's site, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor. It does not explicitly name alternatives or when-not-to-use, but the context is clear 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 destructiveHint false, so safety profile is clear. The description adds useful behavioral detail about what the tool returns (fields, geometry type, record count, capabilities), providing value beyond annotations.

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

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

The description is a single, well-structured sentence. It front-loads the primary action and lists the returned data components without unnecessary words.

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

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

The tool is simple (one parameter) and annotations cover safety. The description lists the expected return components, which is important given no output schema. It does not elaborate on potential errors or 'capabilities' meaning, but it is sufficiently complete for a straightforward schema-inspection tool.

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

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

Schema description coverage is 100% for the single url parameter, with a clear example and type description. The tool description does not add additional parameter semantics beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool retrieves an ArcGIS Feature/Map Service layer's schema via URL, listing specific returned components (fields, geometry type, record count, capabilities). This is specific and distinguishes it from sibling tools like query_layer.

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

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

The description implies when to use the tool (when schema information is needed for a layer) but does not explicitly state when not to use it or mention alternatives. The sibling tool names suggest related functionality, but the description lacks explicit 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 safety is covered. The description adds useful context beyond that: it specifies the return fields (id, type, params, created_at, last_fired_at, fire_count) and the default scope ('active subscriptions'). This enriches the agent's understanding of what the tool returns without contradicting annotations.

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

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

The description is three sentences, each earning its place: purpose+scope, return fields, and usage guidance. It is front-loaded with the verb-resource pair, structured logically, and contains zero 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 list tool with one optional parameter, no enums, and no output schema, the description is complete. It explicitly lists the return fields, which compensates for the missing output schema, and provides usage context. The annotations cover safety, so no further behavioral disclosure is needed.

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

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

Schema description coverage is 100% with the single parameter include_inactive fully documented. The description does not add additional parameter syntax or format details beyond the schema, but it reinforces the default behavior by saying 'active subscriptions'. This meets the baseline for schema-covered params.

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

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

The description clearly states the tool's purpose: to list the caller's active subscriptions. It uses a specific verb ('List') and resource ('subscriptions'), and specifies the scope ('caller's active'), which distinguishes it from potential siblings like subscribe/unsubscribe. It also enumerates the exact fields returned, leaving no ambiguity.

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

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

The description provides explicit when-to-use guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This directly ties to the subscribe/unsubscribe workflow, making it clear this is a read-only precursor to mutations.

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

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

With all annotations set to false, the description carries the full burden. It discloses the claim_token flow (filing without an account returns a token; passing it back later reads status), rate limiting (5 per identifier per day), quota impact (free, doesn't count), and the team's daily digest cycle. These are meaningful behavioral traits beyond what annotations convey.

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

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

The description is appropriately sized for the tool's complexity and stays front-loaded: it opens with the core purpose, then flows into use cases, exclusions, mechanics, and operational details. Every sentence carries useful information—none are filler. The rate limit and quota note are concise and relevant.

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 explains what a filing returns (a claim_token) and how to later retrieve status/changes. It covers the tool's key behavioral edges (scope limitation to Pipeworx, rate limits, quota) and complements the rich input schema. For a feedback tool of this complexity, the description is fully 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 strong individual descriptions, so the baseline is 3. The description adds extra value by explaining the claim_token round-trip pattern (e.g., 'pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and giving content guidance for the message field (don't paste end-user prompt, be specific). While the schema already covers basics, this supplementary context helps the agent invoke parameters correctly.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this feedback tool from siblings like ask_pipeworx or discover_tools, and explicitly enumerates the categories (bug, feature, data_gap, praise).

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 when a tool returns wrong/stale data... when a tool you wish existed isn't in the catalog... or when something worked surprisingly well'). It also gives a strong when-not-to-use rule: do not report tools from other MCP servers, and tells the user to file those elsewhere. Additional instructions (describe in terms of Pipeworx tools, don't paste user prompt) further clarify usage.

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

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

Annotations already indicate readOnly/idempotent/non-destructive. The description adds meaningful context: 'derived from CF analytics-engine, no PII, just (pack, tool, count)' and 'Cached 5min-1h depending on window,' which informs the agent about data provenance, privacy, and freshness 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 well-structured, front-loaded with the core capability, and uses a compact bulleted list for use cases. Every sentence adds value; it is informative without being verbose.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description thoroughly covers what it returns, use cases, data source, privacy, and caching. It is sufficiently complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% for the single window parameter, including an enum and description. The tool description only restates the window options without adding further semantics, so baseline 3 is appropriate.

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

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

Description clearly states the tool's function: 'Returns the top tools, top packs, and total call volume over a recent window.' 'What other AI agents are calling on Pipeworx right now' provides a specific, vivid resource and distinguishes it from siblings like discover_tools or search_datasets by focusing on trending call volume.

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?

'Useful for:' explicitly lists three distinct use cases, giving clear context for when to use the tool. However, it does not explicitly name alternatives or provide when-not-to-use guidance, 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 declare readOnlyHint=true and idempotentHint=true, and the description adds substantial behavioral context beyond those: it explains partition_check mechanics, the >3pp deviation threshold, placeholders filtering, fill check against live CLOB depth at 1000 shares/leg, and the meaning of realizable_edge_pp ≤ 0. It also discloses that skipped_low_similarity surfaces rejected pair counts, enhancing 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 long but densely packed with unique, non-redundant information. It is front-loaded with a crisp definition, then organized into labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) that aid scanning. A minor deduction because the length may be overwhelming, but all content is valuable.

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

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

Given the tool's complexity (two modes, filters, fill check) and the absence of an output schema, the description thoroughly covers return shapes (opportunities[], partition_check details), edge cases (placeholder thresholds, low similarity), and practical trading guidance. It provides enough context for correct invocation and interpretation.

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?

While schema coverage is 100%, the description adds significant meaning for both parameters: event includes concrete slug examples and mentions full URLs are accepted; topic explains it as a seed question and gives examples. It details the behaviors triggered by each mode, which the schema's brief descriptions do not convey.

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 arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly differentiates from sibling tools like polymarket_edges and polymarket_fill_risk by naming its unique approach and modes (trending_scan, 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?

Explicit usage guidance is provided: 'Call with NO args for a trending_scan... pass event... or topic.' It recommends event for a specific market, topic for cross-event scans, and explicitly names an alternative for custom sizing: 'use polymarket_fill_risk.' It also includes an exclusion/condition: 'realizable_edge_pp ≤ 0 means... do not trade it.'

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds extensive behavioral context beyond that: response segment structure, caching at KV level, the placeholder-slug filter, per-sport bias corrections, the 24h-move warning, and diagnostics for why segments might be empty. It also explains the fed_candidates exclusion and unreliable signals.

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

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

The description is very long, dense, and uses all-caps segment names and bullets. It is front-loaded with the core purpose, but subsequent details (e.g., model family explanations, response structure) are verbose and could be trimmed. However, given the complexity and absence of an output schema, the length is partly 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 must explain return values and it does so thoroughly, listing top-level fields (by_segment, fed_candidates, _diagnostics), the model families, and edge metrics. It also explains caching, knob effects, and why segments may be empty, providing a complete picture for an agent to correctly invoke and interpret the tool.

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

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

Schema description coverage is 100% and each parameter already has a rich description (e.g., slippage_pp explains bid/ask context, min_partition_leg_kelly explains per-leg behavior). The description groups parameters into 'tradeable-edge knobs' and explains their interplay, but this is mostly redundant with the schema. It adds marginal value 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 uses a specific verb ('Scan') and resource ('top Polymarket markets') with a clear outcome ('return opportunities where Pipeworx data disagrees with market price'). It also states the intended use case ('what should I bet on today'), distinguishing it from sibling tools like polymarket_arbitrage or polymarket_fill_risk.

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

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

Clear context is given for when to use the tool, including its purpose to avoid paging hundreds of markets and its knob settings for filtering. It also provides a caution about fed bets being unreliable. However, it does not explicitly name alternative tools or say 'use instead of X', so it misses the top bar for explicit exclusions.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive. The description adds substantial behavioral context: snapshot writing on cache-miss, 60-day TTL, daily closes vs. intraday, and detailed explanation of response fields like trend and decay_pp_per_day. No contradictions.

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

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

The description is dense yet well-structured: purpose, args, response details, and limits are clearly separated. Every sentence adds value—no filler or redundant repetition of annotations. It remains readable despite 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?

Despite having no output schema, the description thoroughly explains the return structure (tracked[], expired[], snapshot_dates[]) and their fields. It covers limitations, data freshness, and interpretive guidance (median lifespan as competition clock). This makes the tool fully understandable without additional documentation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful context: how 'days' maps to snapshot history, how 'window' selects snapshot family, and how these parameters interact with cache-miss gaps and TTL. It goes beyond the schema's default/clamp information.

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

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

The description clearly states the tool's purpose: edge persistence and decay telemetry. It uses specific terms like 'tracked[]', 'expired[]', and 'snapshot_dates[]' and contrasts with fresh vs. old edges, distinguishing it from the sibling polymarket_edges tool.

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

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

The description implies when to use this tool (to assess how long an edge has existed and whether it's shrinking) and contrasts it with current-edge data. It doesn't explicitly name alternatives, but the context makes the distinction clear, and it includes limitations like snapshot TTL and cache-miss gaps.

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 signal readOnly/openWorld/idempotent/non-destructive, but the description adds substantial behavioral context: live order-book walking, partial-fill conversion to unhedged directional risk, forced_directional_risk naming, and verdict states (clean|degraded|cannot_fill). 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 run-on, but every clause contributes critical information and it is front-loaded with the core purpose and mode requirements. It would benefit from paragraph breaks or bullet formatting, but it wastes no words.

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

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

With no output schema, the description fully enumerates return fields for both modes, explains size_usd interpretation per mode, identifies risk indicators (thin_legs, forced_directional_risk), and justifies the tool's purpose. This is complete enough for an agent to select and invoke it correctly.

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

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

Schema description coverage is 100% and already documents each parameter, but the description adds the critical constraint that exactly one of `market` or `event` is required, which the schema does not convey (required params = 0). It also reinforces mode-dependent size_usd semantics and default side behavior, going beyond the structured schema.

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

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

The description opens with 'Realizable-vs-theoretical edge check against live CLOB order-book depth', a specific verb and resource that clearly distinguishes it from theoretical edge tools like polymarket_edges and polymarket_arbitrage. It also names concrete outputs (verdict, slippage_pp, capture_ratio) and explains both single-market and basket modes.

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

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

It explicitly states mode selection requirements ('REQUIRES one of `market` or `event`'), provides mode-specific usage details, and directly tells the agent when to use it: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. This clear when-to-use guidance differentiates it from sibling tools.

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

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

Despite annotations already marking readOnly/idempotent/openWorld, the description adds extensive context beyond them: the pairing is verified only by keyword overlap ('pairing_unverified'), spread_pp is gross and ignores Kalshi fees ('fees_note'), legs with 'unknown' metric_type are never paired, and temporal_alignment null means 'could not be computed', not aligned. This is exactly the kind of behavioral nuance that prevents misinterpretation.

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

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

The description is information-dense but presented as a single wall-of-text paragraph with no breaks for modes, safety codes, or caveats. It is redundant in places — pairing_unverified and keyword-overlap matching are stated more than once, as is the pre-mapped-warning theme. Every sentence carries value, but the structure is not concise or scannable.

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

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

For a complex read-only tool with no output schema, the description is remarkably complete: it explains the response shape (leg-by-leg prices, top_spreads_pp), each compatibility code, the flags on individual spreads, the skipped-leg counters, fees exposure, and the rarity of real spreads. An agent has everything needed to call the tool correctly and interpret the output safely.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics on top: it explains that explicit parameters override the topic-mapped side, that both modes run the identical matcher, and that topic values are pre-mapped shortcuts rather than free-form inputs. This elevates it slightly above the baseline.

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

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

The description opens with a specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This clearly identifies a unique function among the Polymarket-adjacent sibling tools. However, it never explicitly names a sibling it is not (e.g., polymarket_arbitrage, polymarket_edges), so differentiation is left implicit.

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

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

The description clearly lays out two invocation modes — 'topic' for pre-mapped macro shortcuts and explicit ticker/slug for custom pairings — and warns that 'pre-mapped ≠ tradeable' and most topics return compatibility_warning. It doesn't explicitly say 'use tool X instead when Y', but the context for when to call this tool versus when to expect poor results 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?

Annotations already mark it as read-only, idempotent, and non-destructive. The description adds behavioral detail beyond that: it returns attribute rows with geometry, supports SQL-like syntax, and hints at pagination via offset. It doesn't discuss rate limits or errors, but the annotation coverage lowers the burden.

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

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

Two sentences, front-loaded with the core purpose, and the second sentence is a valuable tip without redundancy. No wasted words.

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

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

Despite no output schema, the description states the return type (attribute rows and geometry) and shows how to sample data. Together with the comprehensive parameter schema and strong annotations, the tool is well-specified. Minor gaps like error handling are not critical for a read-only query tool.

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

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

The schema covers 100% of parameters with clear descriptions, so the description adds little new parameter meaning. It summarizes the parameter names and the SQL-like style, but the schema already provides the full semantic detail. The sampling tip does demonstrate parameter 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 precisely states the action ('Query') and the resource ('ArcGIS Feature Service / Map Service layer') and notes the URL comes from search_datasets. This distinguishes it from sibling tools like layer_info or search_within.

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

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

It explains the URL comes from search_datasets and provides a concrete example pattern ('where="1=1" + out_fields="*"' to sample). While not explicitly naming alternatives, the sibling context makes it clear this is the querying tool versus metadata/info 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 declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds meaningful behavioral context beyond these: scoping to the user's identifier (anonymous IP, BYO key hash, or account ID) and the dual-mode behavior (retrieve single value vs. list all keys). This goes beyond the annotations and enriches the agent's understanding.

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 primary action, then usage guidance and scoping. Every word earns its place; there is no fluff or repetition of schema content.

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

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

For a simple tool with one optional parameter, the description covers purpose, usage, scoping, and sibling relationships. It explicitly states the two invocation modes (with and without key). The lack of an output schema is not a gap because the return behavior is implied clearly ('retrieve a value' or 'list keys').

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

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

The schema already covers the single 'key' parameter with a description, so baseline is 3. The description adds semantic richness by explaining the 'omit to list' behavior in the first sentence and providing concrete examples of stored values (ticker, address, research notes), which helps the agent map intent to the parameter without adding bulk.

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, specific verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys.' It distinguishes from sibling tools (remember, forget) by explicitly framing recall as the retrieval counterpart, so there is no ambiguity about its 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?

It provides explicit when-to-use guidance: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also names the paired tools (remember, forget) and their relationship, giving clear context for when to use recall versus the 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?

Beyond annotations (readOnly, idempotent, non-destructive), the description discloses key behaviors: mark_read:true causes returned events to be flagged read, affecting subsequent calls; polling is explicitly stated as safe; and the same data is available via HTTP, providing useful context. No contradictions with annotations.

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

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

The description is four sentences, front-loaded with the core purpose, then details on return fields, filtering, and mark_read. Every sentence adds meaningful information without waste, making it both concise and well-structured.

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

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

With 5 optional parameters and no output schema, the description covers the return format, filtering options (type, since), mark_read behavior, polling safety, and an alternative HTTP endpoint. This is sufficient for an agent to select and invoke the tool effectively without additional context.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the effect of mark_read on future calls, giving a concrete example for type ('sec_8k'), and describing the since parameter as an ISO timestamp. These addition extras justify a 4.

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

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

The description opens with a specific verb+resource ('Pull fired events from your subscription feed'), clearly identifying the tool's function. It further specifies the return contents (source, citation_uri, raw event payload), distinguishing it from sibling tools like list_subscriptions or recent_changes.

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

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

The description gives clear context for use: it's for polling recent alerts, with filtering options and a mark_read mechanism. It also mentions an alternative HTTP endpoint for scripts/dashboards, implying this tool is for AI agent use. However, it does not explicitly contrast with sibling tools or state when not to use it.

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

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

Annotations already mark the tool read-only, open-world, and idempotent, but the description adds substantial behavioral context: source fan-out to SEC EDGAR, GDELT/GNews fallback, USPTO sunset soft-fail, and the parallel-call nature. 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?

Every sentence contributes unique information—query examples, source behavior, parameter formats, output structure, and alternative tool. It is long but dense, with user intent examples front-loaded for 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?

Even without an output schema, the description specifies the return structure (changes[], total_changes, citation URIs). It also covers edge cases like rate limits, API sunset, and the single-type limitation, making the tool self-explanatory for a complex multi-source fan-out.

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

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

Schema covers all three parameters with descriptions, so the bar starts at 3. The description adds extra value by giving concrete examples for `since` (ISO/relative) and recommending '30d' or '1m' for monitoring, plus clarifying `value` as ticker/CIK.

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 natural-language query patterns ("What's new with X") and clearly identifies the tool as a change feed for a company over a time window. It explicitly differentiates from sibling entity_profile by naming the alternative use case.

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

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

Provides explicit when-to-use guidance: 'Use entity_profile instead when you want the static profile...' and illustrates query phrasing. Also explains fallback behavior (GDELT→GNews) and the USPTO soft-fail, clarifying when results may be limited.

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

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

Annotations already indicate a write operation (readOnlyHint=false, destructiveHint=false, idempotentHint=true). The description adds valuable behavioral context beyond annotations: persistence scoping by user identifier, retention policy (24 hours for anonymous, persistent for authenticated), and key-value storage format. It doesn't mention overwrite behavior, but annotations cover idempotency, so the added context is useful without being exhaustive.

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

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

The description is four sentences, each earning its place: purpose, usage triggers, behavioral details, and companion tools. It is front-loaded with the core function and avoids redundancy or fluff. Every sentence contributes to understanding.

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 required params, no output schema, no nested objects), the description covers everything needed: what it does, when to use it, how data is stored (key-value scoped to identifier), persistence rules, and how it relates to recall/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 covers both parameters fully (100% coverage), so description doesn't need to re-explain them. However, it adds meaningful examples for key naming conventions ('subject_property', 'target_ticker') and clarifies the value type ('any text — findings, addresses, preferences, notes'), which goes beyond the schema's generic descriptions. This adds practical guidance for tool invocation.

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

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

The description opens with a clear verb-object structure: 'Save data the agent will need to reuse later' and immediately distinguishes itself from sibling tools by naming recall and forget. It gives concrete examples (resolved ticker, target address, user preference) that make its 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?

It explicitly states when to use it ('Use when you discover something worth carrying forward...') and provides examples of appropriate use cases. It also references sibling tools ('Pair with recall to retrieve later, forget to delete'), giving clear contextual guidance on how it fits into a workflow.

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

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

The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior; the description adds substantive context by disclosing graceful degradation (EDGAR identifiers still return if GLEIF/OpenFIGI are unavailable), ambiguity handling (`figi_candidates` instead of a false assertion), and the explicit `unresolved` field. There is no contradiction between the description and annotations.

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

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

The description is front-loaded with examples, purpose, and a 'use FIRST' directive, and every later segment addresses a distinct aspect: input forms, per-type outputs, ambiguity, unresolved handling, and failure degradation. It is comprehensive but heavy on nested parentheticals and run-on phrasing, which reduces skimmability even though the length is largely earned by the tool's multi-source 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 that there is no output schema, the description carries the full burden of explaining return behavior, and it does so thoroughly: per-type identifiers, source labels, ownership fields, `figi_candidates`, unresolved identifiers, graceful degradation, and even a concrete bond-issuer naming rule. An agent has enough context to decide when to call the tool and what to expect back.

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 input schema already documents both parameters well, the description adds meaning beyond the schema: it introduces ISIN as an accepted company input (absent from the schema), explains how ISIN resolves via GLEIF to the issuing legal entity, covers non-equity instruments, and details the drug-mode output with a pipeworx citation. This directly helps an agent construct a correct `value` in edge cases the schema does not mention.

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

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

The description states a clear action: resolving a user-spoken name to canonical/official identifiers that other tools require as input. It opens with concrete natural-language triggers ('ticker for…', 'CIK for…', 'LEI for…') and distinguishes supported types ('company' and 'drug'), making it easy to recognize when this tool applies and easy to separate from sibling tools like entity_profile.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' and it enumerates the accepted input forms and entity types, giving an agent a clear trigger condition. It does not, however, name alternative tools or state explicit exclusion cases, so it stops short of full when-not-to-use guidance.

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

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

The description details that it probes each entity with ai_visibility_check and returns a ranked list with score, confidence, signal density. This goes beyond the annotations (readOnly, idempotent, etc.) by explaining the composite call and output structure.

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

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

Three sentences, each with clear purpose: what, mechanism, use case/return. No fluff.

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

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

Despite no output schema, the description specifies return contents and the composite nature of the tool. Combined with rich schema annotations, it provides sufficient context for correct usage.

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

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

The input schema provides thorough descriptions for all 4 parameters (100% coverage), so the description adds little beyond framing the first entity as the subject. The baseline of 3 applies.

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

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

The description clearly states 'Compare AI visibility across multiple entities side-by-side' and explains the ranking and output, distinguishing it from single-entity tools like ai_visibility_check.

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

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

It provides a concrete use case 'competitive AI-marketing audits' and implies when to use (for multiple entities) versus ai_visibility_check. However, it does not explicitly list exclusions or alternative tools beyond the implied single-entity check.

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 transparency beyond the read-only/idempotent annotations by disclosing composite fan-out behavior, partial failure degradation, and the 5-30s first-measurement timeout with sources_failed reporting. This gives the agent a clear model of what to expect at runtime without contradicting the annotations.

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

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

The description is a single dense paragraph but every sentence carries distinct information: purpose, usage triggers, return fields, ecosystem scope, and failure behavior. It is longer than ideal but the density of new facts justifies the length; a slight structural breakdown into sections would improve scannability but is not required.

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 takes on the responsibility of explaining return values, listing exact summary fields (`is_latest`, `license`, `advisory_count`, etc.), per-advisory details, links, and alternative versions. It also covers edge cases like partial failures and ecosystem limitations, making it fully self-contained for an agent.

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

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

The input schema already provides 100% coverage of both parameters (`package` and `version`) with descriptions. The tool description does not add meaningful parameter-level detail beyond what the schema says; it mentions the default version behavior but that is already in the schema. Therefore 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 begins with a specific verb and resource: 'Composite "should I add this npm package to my project" check in ONE call' and clearly enumerates the underlying sources (deps.dev and bundlephobia) and outputs (summary block, advisories, links, alternatives). This sharply distinguishes it from sibling tools by describing a unique composite behavior.

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

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

The description explicitly states when to use the tool: "Use whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'". It also provides exclusion guidance in 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', steering users to an alternative approach for other ecosystems.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior, so the description doesn't need to repeat those. It adds useful context by disclosing the return fields (name, summary, record_count, owner/org, URL) and the chaining workflow, which goes beyond what annotations or schema provide.

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

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

The description is two sentences long. The first states the action and resource, the second lists the output and downstream usage. Every phrase is necessary, no redundant content.

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

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

For a read-only search tool with three optional parameters and no output schema, the description effectively lists the return fields and directs the user to query_layer/layer_info. Combined with the schema, the agent has sufficient information to invoke the tool and interpret results. The open-world hint is also consistent with the unspecific keyword search.

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?

All three parameters are fully documented in the schema with descriptions (100% coverage), so the baseline is 3. The description adds the domain context of keyword search and the purpose of the returned URL, but it does not elaborate on limit or org_id beyond the schema, so it meets but does not exceed the baseline.

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

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

The description clearly states the tool's function: 'Search Montana State GIS open geospatial datasets' by keyword, with specific examples (parcels, zoning, transport). It also distinguishes itself from sibling tools by noting the returned Feature Service URL is meant for query_layer/layer_info, making the purpose unambiguous.

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

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

The description gives clear context for when to use this tool: to search and discover datasets, then pass the returned URL to query_layer/layer_info. This implies a workflow and differentiates from those sibling tools, though it does not explicitly list exclusions or alternative search methods.

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

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

The description adds rich behavioral details beyond the annotations: it uses BGE-base-en embeddings with cosine similarity over 500-char overlapping windows, enforces a 200K character cap with truncation flagging, and returns passages with character offsets and similarity scores. These details disclose how the tool executes and what limitations exist, consistent with the readOnly and idempotent hints.

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

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

The description is four sentences, each earning its place: the first establishes the core action, the second explains when to use, the third provides a companion workflow, and the fourth details technical behavior. No filler or redundant phrasing.

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

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

Despite lacking an output schema, the description specifies the return format (top-N passages with character offsets and similarity scores). It also covers the input size limit, truncation behavior, and safety profile (read-only). For a tool with only three parameters, this description is fully complete.

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

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

The schema already describes all three parameters at 100% coverage, so the baseline is 3. The description adds value by giving concrete examples of text inputs (SEC 10-K body, article, long tool result) and clarifying the query as 'natural-language query.' This enriches the meaning of the 'text' and 'query' parameters.

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: 'Semantic search INSIDE a fetched record.' It distinguishes itself from siblings like ask_pipeworx_grounded by emphasizing it operates on text you already have, not a global knowledge base. The verb 'search' and resource 'fetched record' are specific and unambiguous.

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

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

The description explicitly advises when to use the tool: 'Use when the record is too big to cram into the prompt.' It also provides an alternative workflow, pairing with ask_pipeworx_grounded, to ground over relevant passages. This gives the agent clear decision guidance.

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

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

The description extensively discloses behavioral traits beyond the annotations, such as requiring a Pipeworx OAuth account, delivery channel mechanics (always-on feed, email/SMS/webhook options), phone verification, the 10/day SMS cap, webhook auto-disabling after 10 consecutive failures, and one-time delivery of the signing secret. This level of detail far exceeds the basic safety hints provided by the annotations.

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

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

The description is long but well-structured and dense, with each sentence adding meaningful context. It front-loads the core purpose, then details requirements, types, and delivery options. While not brief, it earns its length given the tool's complexity and nested parameters.

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

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

Given the tool's moderate complexity (3 parameters, nested objects, no output schema), the description is exceptionally complete: it covers subscription types, parameter requirements, delivery channels, and constraints. The only minor gap is that it does not describe the full return response shape beyond the subscription id, but this is acceptable for a creation tool.

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

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

The input schema already provides 100% parameter coverage, so the baseline is 3. The description adds value by giving concrete examples for each subscription type (e.g., items:["5.02"] = officer change), clarifying optionality rules (e.g., sponsor or condition required for clinical_trial), and explaining delivery channel nuances, although some information is redundant with the schema.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Create a proactive monitoring subscription to a live-data event stream.' It distinguishes itself from sibling tools like list_subscriptions and unsubscribe by focusing on the creation action, and enumerates the supported subscription types, 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?

The description provides clear context on when to use the tool, including prerequisites (OAuth account, phone verification) and supported types. However, it lacks explicit 'when not to use' guidance or direct alternatives like 'use list_subscriptions to view existing subscriptions,' though the context strongly implies these.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description reveals the output structure (category-bucketed example questions), the dynamic source (live catalog of thousands of tools), and the optional topic filter. Adds meaningful context without contradicting annotations.

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

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

The description is dense but well-structured: it opens with natural user queries, then provides a clear explanation of outputs and usage. It's slightly long but every sentence carries useful information, 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?

For a simple read-only tool with one optional parameter and no output schema, the description covers purpose, usage, parameter semantics, and expected output shape. It is fully sufficient for an agent to decide when and how to invoke it, and even names associated meta-tools it teaches.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds valuable semantics by explaining omitted vs provided behavior ('Call with no arguments for the full spread, or pass topic to focus') and provides concrete examples (finance, pharma, betting), elevating it above the baseline.

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

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

The description clearly defines the tool as the onboarding entry point that returns category-bucketed example questions with exact tool+argument shapes. It lists specific categories and distinguishes itself from siblings by emphasizing its role as the 'first step' when unfamiliar with 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?

Explicitly instructs to 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains how to learn to call meta-tools. Also clarifies behavior when called with no arguments vs with a topic, providing concrete examples.

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

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

The description goes beyond the annotations by explicitly disclosing ownership enforcement ('you can only cancel your own subscriptions') and the deactivation behavior ('row is deactivated (not deleted)'). These are meaningful behavioral traits not captured by readOnlyHint or destructiveHint.

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 deliver the core purpose, a critical constraint (ownership), and a key behavioral detail (soft delete) without any fluff. The description is front-loaded with the verb and resource, and every clause carries information.

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

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

For a single-parameter mutation tool with no output schema, the description explains the action, the ownership rule, and the post-cancellation behavior, making it self-contained. The reference to recent_alerts provides additional context for the tool's effect.

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 fully documents the single parameter 'id' with a clear description. The tool description adds no parameter-specific detail beyond what the schema provides, and 100% schema coverage sets the baseline at 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 the action ('Cancel a subscription by id') and the specific resource. It differentiates from siblings by noting ownership enforcement and deactivation instead of deletion, making the tool's scope unmistakable.

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

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

The description provides clear context for when to use the tool (canceling subscriptions) and implies exclusion via the soft-delete note (historical events remain available via recent_alerts). However, it does not explicitly name alternative tools or state when not to use it, 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?

Beyond the readOnly/openWorld/idempotent annotations, the description discloses key behavioral nuances: the distinction between 'could_not_verify' (check did not happen) and 'unsupported' (no source exists), and the warning not to treat 'could_not_verify' as evidence. It also explains the two pipeline behaviors and the return format, which significantly aids correct use.

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 detailed but every sentence earns its place: query phrasings, use case, routing logic, return values, failure semantics, and efficiency note. It is front-loaded with the purpose and uses clear structural cues (e.g., 'IMPORTANT for callers'), making it easy to scan.

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

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

Even without an output schema, the description enumerates all possible verdicts ('confirmed / approximately_correct / refuted / inconclusive / unsupported / could_not_verify'), explains the meaning of the ambiguous ones, and describes the citation and reasoning returned. It covers both fast-path and grounded flows, making the tool fully self-contained for an agent.

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

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

Parameter schema coverage is 100%, but the description adds valuable semantics: it explains how tolerance_pct overrides claim-implied tolerance, caps at 5, and recommends 1–2 for hallucination detection. It also embeds concrete examples for the claim parameter, going beyond the schema's basic documentation.

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

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

The description opens with explicit natural-language query phrasings and a clear verb+resource pairing: 'natural-language claim verification against authoritative sources.' It distinguishes itself from siblings by detailing the two routing paths (SEC EDGAR fast path vs. grounded pipeline) and its efficiency ('Replaces 4–6 sequential calls').

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

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

It provides a clear use case: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also distinguishes between company-financial claims and any other factual claim. However, it does not name alternative tools or explicitly state when not to use the tool, 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.