Usajobs

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 valuable behavioral context: default model is free, passing _apiKey incurs direct Anthropic costs, and the return format per model. This goes beyond the annotations without contradicting them.

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

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

Three concise sentences, front-loaded with the core action, then return format, then use cases. No fluff or repetition of schema details; every sentence earns its place.

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

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

Despite no output schema, the description fully specifies the return structure (per-model object + combined view), default model, optional key behavior, and intended use cases. This gives an agent enough context to select and invoke the tool correctly without additional documentation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning for _apiKey ('BYO key — you pay Anthropic directly') and explains the default model, enriching the schema's minimal descriptions. It clarifies the relationship between models and _apiKey.

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 ('Probe one or more LLMs for what they know') and the output ('score visibility (0-100) per model'). It distinguishes itself from siblings like ask_pipeworx and scan_competitor_ai_presence by focusing on multi-LLM visibility scoring.

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

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

Provides explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') that indicate when to use it. However, it doesn't mention when NOT to use it or name alternative tools, so it stops short of full exclusion guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context beyond annotations: the tool automatically routes questions to sub-tools, fills arguments, and returns citations with stable pipeworx:// URIs. It also positions the tool as authoritative/verified, which helps an agent set expectations about result quality. The description does not contradict annotations.

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

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

The description is highly informative and front-loaded with the key guidance ('PREFER OVER WEB SEARCH'), but it is overly long and contains a strange, garbled tail of rhyming wordplay ('enter on hit, think through the chain, decide with evidence, then off you go') that adds no semantic value and could confuse an agent. The example list is useful but could be trimmed. The first few sentences are excellent; the ending hurts the structure.

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-required-parameter tool with a rich schema and explicit annotations, the description covers the key usage context: when to prefer it, what it does, what kinds of questions it handles, and what output to expect (structured answer with citations). It doesn't document rate limits, pagination, or error behavior, but those are less critical for a natural-language query tool with read-only, idempotent annotations. The garbled ending is the main blemish preventing a 5.

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

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

Schema description coverage is 100% and the schema already documents all six parameters clearly, including aliases for 'question'. The description reinforces that the parameter is a natural-language question and gives examples, but it doesn't add much semantic detail beyond what the schema already provides. Baseline 3 is appropriate because the schema carries the explanatory weight.

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

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

The description is explicit about what the tool does: it routes a natural-language factual question to one of 5,798 tools across 1,517 verified sources and returns a structured answer with stable pipeworx:// citation URIs. It clearly distinguishes itself from generic web search and sibling tools like deep_research and ask_pipeworx_beta by emphasizing verified structured data, citations, and automatic argument filling.

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 'PREFER OVER WEB SEARCH' and gives both when-to-use and when-not-to-use guidance. It lists concrete example questions and specific domains (SEC filings, FDA, FRED/BLS, patents, real estate, etc.), plus trigger phrases like 'what is', 'look up', 'find', 'get the latest', 'how much', 'current'. This gives an agent clear decision criteria for selecting this tool over siblings like deep_research, search, or bet_research.

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, idempotent, and non-destructive. The description adds useful behavioral context beyond that: candidates can be enabled live, the last one was retired on 2026-07-26, and the tool 'Falls back to nothing'—it is a real working router, not a wrapper that delegates. This transparency about current experimental state and fallback behavior goes well beyond the structured fields.

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 and front-loads the core purpose before explaining experimental status, current state, and fallback behavior. There is slight redundancy in saying 'identical universal router' and later 'currently matches ask_pewx exactly', but every sentence earns its place and the description remains compact.

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 an experimental alias over a large router with no output schema, the description is complete: it says what the tool is, how to use it, when to choose it, what its current state is, and whether it falls back. An agent has enough context to invoke it correctly without additional lookups.

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

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

The schema has 100% description coverage, so the baseline is 3 even when the description adds no parameter detail. The description only says 'same arguments' and does not elaborate on types, formats, or default behavior. It clarifies that the arguments match ask_pewx, but parameter-level meaning is mostly already carried by the schema.

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

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

The description states a specific purpose: it is the 'Beta version of ask_pipex', an 'identical universal router' with the same 5,798 tools, same arguments, and same response shape. It further distinguishes itself from the stable ask_pewx by explaining it carries candidate routing improvements. This is far beyond a tautology and clearly tells an agent what this tool does.

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

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

The description gives explicit guidance: 'Use it exactly like ask_pewx when you want the newest routing', and contrasts the beta with the stable router by saying results are compared to decide what merges. It also notes that no candidate is currently active, so it matches ask_pewx exactly—an agent can decide whether to prefer this experimental edge or the stable sibling.

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

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

Annotations already cover readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds substantial behavioral context beyond that: exact refusal reasons, verbatim evidence output, restriction to data contained in tool results, and the extra LLM call cost. No contradiction with annotations.

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

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

The description is long but information-dense: front-loaded with the core mode and use case, then internal mechanics, return shape, refusal semantics, and cost trade-off. Every clause adds operational value and the structure with em dashes and lists makes it 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?

There is no output schema, but the description fully specifies both success and refusal return shapes, including evidence, confidence, source, fetched_at, and each refusal reason. Combined with annotations covering safety and schema covering parameters, an agent has enough to decide and invoke correctly.

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

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

The description does not document the question parameter, but the input schema already provides full semantic coverage with aliases and natural-language guidance. Schema description coverage is 100%, so the baseline of 3 applies and no description compensation is needed.

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

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

States a specific mode: hallucination-resistant answer extraction for high-stakes reads, with the same routing as ask_pipeworx but grounded answer generation. Clearly distinguishes itself from sibling ask_pipeworx by emphasizing extraction only from tool results and the refusal/evidence return shape.

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?

Gives explicit when-to-use guidance: whenever the answer will be quoted, cited, or acted on and the agent must not invent facts, with concrete high-stakes examples. Also states when not to use it: prefer ask_pipeworx for casual lookups because this mode costs an extra LLM call.

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

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

The description goes far beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) by disclosing internal behaviors such as low-confidence short-circuiting, status codes like 'market_closed_or_inactive', fan-out patterns, resolver contract details, wide-spread illiquidity flags, and cancellation-rule risk. It even warns about EV-material void settlements, which is critical behavioral context not available in annotations. 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?

Despite being long, the description is exceptionally well-structured with capitalized section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, NEWS FIELDS, SAFETY, RESOLUTION-RULE RISK). Every sentence contributes necessary operational detail for a complex tool, and the critical purpose and usage guidance are front-loaded in the first two sentences. The length is justified by the tool's complexity, so it earns 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?

The description is exhaustive for a tool with no output schema. It covers the full range of behaviors: input resolution, fan-out logic, response field shapes, resolver confidence, parent-event extraction, news fallback handling, safety short-circuits, market closure status, liquidity warnings, and cancellation-rule risk. Given the tool's depth and the absence of an output schema, this description fully equips an agent to select and correctly interpret results.

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

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

The input schema already provides 100% coverage of all three parameters with detailed descriptions (e.g., 'quick = 2-3 evidence sources, thorough = full fan-out' and 'include_raw: Default false...'). The description adds minimal parameter-specific detail beyond the schema, mostly repeating the acceptable input forms for 'market'. Since schema coverage is high, the baseline of 3 applies, and the description confirms semantics without adding substantial new meaning.

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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes the tool from siblings by focusing on single-market research with market-vs-model comparison, and lists concrete use cases like 'should I bet on X' and 'is there edge in Z', making the purpose unmistakable.

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

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

The description explicitly states when to use the tool with phrases like 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. It does not explicitly name alternative tools or exclusions, but given the sibling set includes specialized Polymarket tools like polymarket_edges and polymarket_arbitrage, the context is clear enough that this is the single-bet research tool. The lack of explicit when-not/alternatives keeps it from 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 annotations (readOnly, openWorld, idempotent), the description discloses detailed behavior: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), specific metrics pulled, sorting by primary metric, and citation URIs. It also notes correct handling of off-calendar fiscal years, which is non-obvious and valuable.

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

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

The description is appropriately sized for the tool's complexity. It front-loads example user queries for quick recognition, then provides structured details on data sources and behavior. Every sentence adds value, with no filler or redundancy.

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

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

Despite no output schema, the description fully accounts for the tool's interface: it explains what data is returned, how results are sorted, and that citations are provided per entity. It also gives context on when to use this tool relative to alternatives, making it complete for an agent to select and invoke correctly.

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

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

The schema already covers both parameters well (100% coverage with enums and examples), and the description enriches them further by explaining what each type pulls and how values should be formatted (e.g., tickers vs drug names). This adds significant meaning beyond the schema.

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

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

The description clearly identifies the tool's purpose: side-by-side comparison of 2–5 companies or drugs in a single parallel call. It uses specific verbs like 'compare' and lists concrete example queries, and it distinguishes itself from single-lookup alternatives by stating it replaces 8–15 sequential 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?

The description explicitly says to prefer this tool over sequential single-pack lookups when comparing entities, and provides concrete trigger phrases. It also specifies when to use type='company' vs type='drug', giving clear guidance on when this tool is appropriate.

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 say readOnly/openWorld/idempotent/non-destructive, and the description aligns with those while adding substantial context beyond them: parallel tool routing, gap[] behavior for unanswered facets, contradictions[], semantic excerpting rather than head-truncation, duplicate/fallback hop logic per depth tier, citation_uri fetchability guarantee, and latency expectations. This gives the agent an unusually rich behavioral model before invoking.

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 and front-loaded with the most decision-relevant constraint (account required, fallback tool). However, it's a very long wall of text with run-on parenthetical asides and a price warning embedded mid-sentence, which makes it harder to parse than necessary. Every sentence earns its place, but the structure is not cleanly organized for scanning.

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

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

Given the tool's complexity (3 depth tiers, multi-hop behavior, gap recovery, contradictions, paid tier), the description covers all decision-relevant context: authentication prerequisite, latency expectations, what the output contains, what guarantees hold (citations always fetchable), and when to pick a sibling instead. No output schema exists, so the description correctly shoulders the burden of describing return behavior.

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

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

Schema coverage is 100%, so the schema already documents both parameters well. The description adds value by explaining the depth tiers in behavioral terms (quick builds 3 facets single-hop; standard adds a gap-recovery hop + contradictions[]; thorough adds a full iterative hop and is paid) and clarifies that 'question' should be broad/multi-part because decomposition is the tool's purpose. It loses a point because the tier semantics in the description and schema are slightly redundant, and the core parameter semantics were already fully covered.

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

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

States specific verb+resource: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources... in ONE call.' Clearly distinguishes from open-web search and specifically contrasts with ask_pipeworx for single lookup. The description's detail about decomposition into facets, parallel routing to 5,798 tools, and findings packet makes the tool's purpose unmistakable even among many siblings.

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

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

Explicitly names when to use: 'Best for broad/multi-part questions over structured data' with concrete examples. Explicitly states when not to use: 'For a single lookup use ask_pipeworx instead.' Also warns about account requirements and names the fallback tool if not signed in. This is unusually complete routing 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 idempotentHint=true. The description adds that it returns top-N tools with names, descriptions, full input schemas, and curated examples, and emphasizes results are ready to call directly with no second schema lookup needed. This gives useful behavioral context 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?

Front-loaded with a clear verb phrase ('Find tools by describing the data or task'), then usage guidance, then return format. The domain list is long but reinforces scope. It's slightly verbose but well-organized and every sentence serves a purpose.

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

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

With no output schema, the description compensates by describing the return value (names, descriptions, schemas, curated examples) and provides strong usage context. It doesn't cover failure modes or edge cases, but for a read-only discovery tool with full annotations, it is adequate.

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

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

Schema coverage is 100%, with descriptions for query, limit, and aliases. The description adds no new parameter semantics beyond example queries and the 'top-N' concept, which the schema already explains (default 20, max 50). The description's domain list helps formulate queries but doesn't add parameter-level detail.

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 'Find tools by describing the data or task' and enumerates supported domains (SEC filings, FDA drugs, etc.), clearly framing it as tool discovery. It distinguishes from data-search siblings like 'search' or 'search_within' by emphasizing discovering available tools rather than querying data.

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

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

Explicitly instructs when to use: '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 clear context and differentiates from alternatives like direct search tools.

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

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

The description goes far beyond the annotations, disclosing that USPTO PatentsView will soft-fail after May 2025, that FDA products only cover biologics (so an empty section is expected for generic-drug-only firms), and that sources_used/sources_failed distinguish real absence from bugs. These edge-case disclosures are exactly what an agent needs to interpret results correctly.

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 somewhat long, but nearly every clause earns its place given the tool's complexity. It front-loads the purpose and usage intent before enumerating sources and edge cases, though a bulleted structure would improve scannability.

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

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

With no output schema, the description carries the full burden of explaining the return shape, and it does so thoroughly: it lists every result section, explains expected-empty cases, covers fallbacks (GDELT→GNews), notes API sunset behavior, and clarifies resolution failures. Nothing critical is left implicit for an agent to discover at runtime.

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 documents both parameters and their accepted shapes. The description repeats the ticker/CIK/name formats and the interchangeable nature of type, adding examples but no materially new semantic information beyond what the input schema provides.

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

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

The description opens with concrete user phrasings and states the exact function: a full cross-source profile of a US public company in one parallel call. It clearly identifies the resource (SEC EDGAR, XBRL, news, etc.) and differentiates itself from chaining 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?

The description explicitly says to ALWAYS PREFER this tool over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view. It also specifies the accepted value forms and explains the resolved:false behavior for private companies, giving an agent clear when-to-use and what-to-expect guidance.

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

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

The annotations already declare destructiveHint=true and idempotentHint=true, so the description doesn't need to restate those. It adds context about clearing sensitive data and clarifies the tool operates on 'previously stored memory,' which is useful. 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 two concise sentences with no unnecessary words. It front-loads the core action and follows with use cases and relationships to sibling tools. Every sentence earns its place.

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

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

For a simple one-parameter tool with no output schema and strong annotations, the description is complete. It covers the action, use cases, and related tools. The presence of annotations and full schema coverage means no additional details are necessary.

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

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

Schema coverage is 100% with the key parameter described as 'Memory key to delete.' The description's 'by key' and 'previously stored memory' add minimal semantic value beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states the action: 'Delete a previously stored memory by key.' It specifies the resource (stored memory) and the key-based operation. It also distinguishes itself from sibling tools remember and recall by explicitly noting the pairing, 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 provides explicit when-to-use scenarios: 'when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also points to complementary tools ('Pair with remember and recall'). However, it lacks an explicit 'when not to use' clause, which would make it a 5.

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

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

The description adds behavioral detail beyond the readOnlyHint and idempotentHint annotations by stating it 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It also clarifies the output is 'a single text blob ready to drop at site-root/llms.txt', enhancing understanding of the tool's behavior.

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

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

The description is three sentences plus a use-case list, front-loaded with the primary action. It is concise with no filler; each sentence provides distinct value covering purpose, process, output format, and usage scenarios.

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 explains the return value as 'a single text blob' and the standard markdown format, covering the essential output information. It adequately addresses purpose, behavior, and usage for a simple 2-parameter tool, though it omits edge cases like invalid URLs or non-HTML pages, which is acceptable for this 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?

Both 'url' and 'max_links' have schema descriptions covering 100% of parameters, so the schema already provides adequate parameter semantics. The description adds minimal extra meaning (e.g., 'extracts title/description/key links' implies what max_links controls), but it does not significantly go beyond the schema.

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

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

The description clearly states 'Generate a production-ready llms.txt file for any URL', providing a specific verb, resource, and scope. It also describes the process of fetching the page, extracting title/description/key links, and emitting the standard llms.txt markdown format, which distinguishes it from sibling tools focused on AI visibility checks.

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

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

The description lists explicit use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' This context is clear, though it does not explicitly name alternative tools, and no obvious sibling exists for this specific function.

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 (readOnlyHint=true, destructiveHint=false, idempotentHint=true) already disclose the safety profile, so the description doesn't need to repeat it. However, the description adds no additional behavioral context beyond what the schema and annotations provide. This is acceptable but not enhanced.

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

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

The description is a single, front-loaded sentence with no wasted words. It immediately states the action, the resource, and the unique identifier, making it highly concise and well-structured.

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

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

For a simple lookup tool with one parameter, full schema description, an output schema, and rich annotations, the description is sufficient. It doesn't need to explain return values or safety because those are covered by structured data.

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 description coverage is 100%, so the parameter 'announcement_number' is already well-documented. The description adds minimal meaning beyond what the schema provides, just restating 'by announcement number.' Baseline 3 applies.

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

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

The description uses a specific verb ('Fetch') and resource ('a single announcement') with a clear identifier ('by USAJOBS announcement number'). This clearly distinguishes it from sibling tools like list_agencies or search, which serve different purposes.

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 the usage context: you would use this tool when you have a specific announcement number and need the corresponding announcement. While it doesn't explicitly mention alternatives or exclusions, the context is clear enough for a get-by-ID tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context by specifying the content type ('USAJOBS reference list of all federal agency sub-element codes and names') and its utility in decoding search results. No contradictions or missing critical behavioral details for a simple list tool.

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 sentence with two clauses, front-loading the purpose and following with a usage hint. Every word earns its place; there is no wasted text.

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 zero parameters and an output schema present, the description provides all necessary context for invoking the tool correctly. It explains both what the tool returns and why it's useful, making it complete for the tool's simple nature.

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

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

The input schema has zero parameters, so there are no parameter details to explain. The baseline for zero-param tools is 4. The description reinforces the full scope without any filtering, which is sufficient.

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

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

The description clearly identifies the tool's function: 'Return the USAJOBS reference list of all federal agency sub-element codes and names.' It uses a specific verb and resource, and the scope ('all federal agency sub-element codes') distinguishes it from sibling list tools like list_occupational_series.

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 an explicit use case: 'useful for resolving agency codes returned by the search tool.' This clarifies when to use the tool, though it does not explicitly name alternatives or state when not to use it. The context is still clear and practical.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which cover the safety profile. The description adds minimal context by providing an example of the data (2210 Information Technology), but it does not disclose any additional behavioral traits such as whether the list is exhaustive, sorted, or paginated. With annotations present, this is acceptable but not particularly rich.

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, compact phrase that communicates the subject matter without any wasted words. It is appropriately sized for such a simple tool.

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

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

Given the tool has no parameters, has an output schema, and is well-annotated, the description is largely sufficient. However, it could be slightly more explicit by stating that the tool lists all occupational series codes, since the description alone reads as a definition rather than an action. Still, the name and annotations fill in the gaps.

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

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

The tool has zero parameters, and the schema is trivially fully covered. The baseline for 0 params is 4, and the description adds no parameter information, which is fine since there are none to explain.

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 'Occupational series codes (e.g. 2210 Information Technology)' identifies the resource but lacks an explicit action verb like 'list' or 'retrieve'. It primarily defines what occupational series codes are, relying on the tool name to convey the listing action. It does not distinguish from sibling tools beyond the resource name, making the purpose slightly vague.

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?

No guidance is provided about when to use this tool versus alternatives. The description gives no context about typical use cases, nor does it mention any sibling tools or exclusions. It is purely a definitional statement with no usage direction.

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, covering the safety profile. The description adds context that this is a reference list (implying a static, non-mutating operation) and includes example codes, which helps set expectations. No contradictions.

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

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

The description is a single sentence with no wasted words. It front-loads the action ('Return...') and uses a semicolon to separate the primary function from the usage context. Every word earns its place.

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

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

For a zero-parameter tool with an output schema, the description fully conveys what is returned (list of pay plan codes and descriptions) and the practical use case. No additional gaps are evident.

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 tool has zero parameters, so the schema is fully covered by default. The description doesn't need to explain parameter semantics, and it adds no parameter-specific information. Baseline of 4 is appropriate for a no-parameter tool.

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 returns the USAJOBS reference list of pay plan codes (GS, FW, ES, etc.) and their descriptions. This specifies the exact resource and action, and it distinguishes this tool from siblings like list_agencies and list_occupational_series.

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 actionable guidance: 'use pay plan codes with the pay_grade_low/pay_grade_high search filters.' This tells the agent how the output will be used and implies when to call this tool (to get valid codes for those filters). It doesn't explicitly state exclusions or alternatives, but the context is clear.

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

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

Annotations already indicate a safe, read-only, idempotent operation, so the bar is lower. The description adds valuable context by specifying the return fields (id, type, params, timestamps, fire_count) and clarifying that it lists the caller's own subscriptions, which goes beyond the annotations.

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

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

The description is two sentences, front-loaded with the purpose, and includes the return fields and usage guidance without any fluff or repetition. Every sentence contributes meaning.

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, the description covers what it does, what it returns, and when to use it. There's no output schema, but the enumerated return fields compensate, making the tool's behavior sufficiently clear 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 coverage is 100%, and the parameter include_inactive is already fully described in the schema. The description adds no extra semantic insight beyond what the schema provides, consistent with the baseline for high schema coverage.

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

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

The description clearly states the tool's action ('List the caller's active subscriptions') with a specific resource and scope, and distinguishes it from sibling tools like subscribe and unsubscribe by its listing role. It also enumerates the output fields, 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 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 implies alternatives (subscribe/unsubscribe) and gives a clear context, though it doesn't explicitly name the alternative tools.

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

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

The description goes well beyond annotations by disclosing rate limits ('Rate-limited to 5 per identifier per day'), the claim_token returning and read-back workflow, daily digest timing, and that it's free/quota-free. No contradiction with readOnlyHint=false or other 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 ~140 words and front-loads purpose before diving into usage rules and token mechanics. Every section earns its place, though some details (e.g., 'Free; doesn't count against quota') are marginally redundant given the rate-limit sentence.

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

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

For a feedback tool with nested context object and no output schema, this description covers purpose, when to use, exclusions, parameter semantics, and return-token workflow. No required parameters means agents need this guidance to know when and how to invoke it effectively.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning for message (describe in terms of Pipeworx tools/packs, don't paste user prompt) and claim_token (how to use it to read replies later). It also clarifies the context parameter scope ('Pipeworx tool names are the ones this connection lists').

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 pair: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this from sibling research/search tools by enumerating feedback categories (bug, feature, data_gap, praise) and explicitly scoping to Pipeworx connection tools.

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

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

Provides explicit when-to-use triggers for each feedback type and an explicit exclusion: 'ONLY for tools served by this Pipeworx connection,' directing cross-server issues elsewhere. It even gives a disambiguation hint ('Pipeworx tool names are the ones this connection lists').

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses valuable behavioral details: it is 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count)' and 'Cached 5min-1h depending on window'. This adds context about data provenance, privacy, and freshness that the annotations do not provide.

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

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

The description is four sentences, each providing distinct value: what it returns, when to use it, data source, and caching. It is slightly longer than strictly necessary but not verbose; every sentence earns its place. The front-loaded first sentence immediately clarifies purpose.

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

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

For a tool with a single optional parameter and no output schema, the description is highly complete: it states the returned data (top tools, top packs, total call volume), the time windows, use cases, data provenance, privacy (no PII), and caching behavior. No important operational context is missing.

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

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

The input schema fully describes the only parameter (window) with enum values, default, and semantics ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). The description adds no additional meaning beyond the schema, so it earns the baseline score of 3.

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

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

The description clearly states what the tool does: 'What other AI agents are calling on Pipeworx right now' and specifies it 'Returns the top tools, top packs, and total call volume'. This is a specific verb (returns) + resource (Pipeworx trending) + output scope, and it distinguishes from sibling tools like discover_tools by focusing on real-time trending signal from other agents.

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

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

The description provides three explicit 'Useful for' scenarios, giving clear context on when to use the tool (e.g., discovering hot data sources, confirming canonical tool choice, checking alignment with agent needs). It lacks explicit exclusions or named alternatives, but the use cases are specific 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?

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses detailed behavioral traits: partition filters, similarity anchors, placeholder handling, fill-check logic, and the warning not to trade when realizable_edge_pp ≤ 0. It also explains skipped_low_similarity and thin_legs, giving the agent a clear mental model of the tool's internal checks and output caveats.

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

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

Though lengthy, every sentence adds unique value: mode explanations, filters, response structure, fill check, and pointers to related tools. It is well-organized with caps-labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) aiding scannability. The front-loaded main verb and clear opening sentence make it efficient despite the detail.

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

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

Given the tool's complexity, no output schema, and the need to guide invocation, the description is remarkably complete. It covers all invocation modes, expected arguments, filtering logic, response fields, and the crucial fill-check caveat. It also cross-references polymarket_fill_risk for related functionality, ensuring the agent understands the full context.

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

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

Schema coverage is 100% with both params described, but the description enriches them substantially. It explains what constitutes a valid event slug vs. a topic seed question, provides concrete examples, and details what each mode does with the input. This goes far beyond the schema's one-line descriptions, adding critical semantic context.

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: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly defines the tool's unique function and differentiates it from siblings by naming polymarket_fill_risk for custom sizing. The three invocation modes (default, event, topic) are explicitly laid out with examples, 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 provides explicit when-to-use guidance for each mode: 'Call with NO args for a trending_scan... pass event for... or topic for...' It also recommends when to prefer event over topic and points to polymarket_fill_risk as an alternative for custom sizing. This is strong, actionable usage direction.

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

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

Adds extensive behavioral context beyond the annotations: response segments, model family details, Kelly capping, slippage treatment, 24h-move warnings, placeholder-slug filters, caching at KV level, and diagnostics. It even explains why Fed signals are unreliable. No contradiction with readOnlyHint is present.

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

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

The description is long, but it is structured with clear headers and logical groupings (model families, response top-level, knobs, diagnostics). Content is dense but relevant, and front-loaded with the core purpose. It could be trimmed, but for a 9-parameter complex tool, the length is largely 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 this thoroughly: by_segment groups, per-opportunity fields, fed_candidates/fed_note, diagnostics funnel counters, and caching behavior. It even covers why segments might be empty, giving the agent enough context to interpret results correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra semantic value by explaining how min_liquidity/max_spread_pp gate 'tradeable edges', and how min_partition_leg_kelly applies per-leg rather than parent-level. It also clarifies the interaction between min_kelly and partition arbs, going 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 immediately states it 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price' and frames it as 'what should I bet on today'. This is a specific verb+resource+scope statement that clearly distinguishes it from sibling Polymarket tools like arbitrage, edge tracker, or 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 use case is given ('what should I bet on today') and it provides some exclusions (e.g., Fed bets excluded from ranking, rare-by-design concentration). However, it never explicitly names alternatives or states when NOT to use this tool versus a sibling, so it misses the top tier of guidance.

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

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

The description goes well beyond the annotations by disclosing response structure, snapshot gap behavior, 60-day TTL limits, daily-close decay computation, and the meaning of 'expired' opportunities. These caveats significantly affect how an agent should interpret results.

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 a tool with no output schema, using clear labels (RESPONSE, LIMITS) and front-loading the purpose. Every sentence adds necessary context, from the interpretive example to the details about snapshot gaps and TTL constraints.

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

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

With no output schema, the description fully compensates by detailing the three response categories (tracked, expired, snapshot_dates), explaining edge sign conventions, and listing limitations. This provides an agent with sufficient information to invoke the tool and interpret its results correctly.

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

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

The input schema already describes both parameters with 100% coverage, including defaults and value ranges. The description adds the phrase 'snapshot family' and restates defaults, but does not meaningfully expand on the schema's parameter 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 clearly defines the tool as 'Edge persistence and decay telemetry' and explicitly frames it as answering 'how long has this edge existed and is it shrinking?'. This distinguishes it from sibling tools like polymarket_edges by focusing on historical persistence and decay rather than current edge values.

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

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

The description provides strong usage context with the fresh vs. 3-week-old edge example, making it clear when to use this tool to assess edge longevity. It does not explicitly name alternative tools or state when not to use it, but the context is clear enough for an agent to select it appropriately.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. The description adds valuable context: explains it walks the order book ladder, simulates fills, returns specific metrics (top_of_book, vwap_fill_price, slippage_pp, etc.), and clarifies the basket mode's risk of 'forced_directional_risk'. No contradictions with annotations.

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

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

The description is lengthy but well-structured with clear labels (SINGLE-MARKET vs BASKET) and a logical flow. It front-loads the purpose and then details modes, parameters, and return values. While dense, every sentence carries useful information; however, it could be tightened to reduce reading load.

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, 4 parameters), the description is exceptionally complete. It lists all return values, explains default behaviors, and warns about key risks (thin books, partial fills, directional exposure). No output schema exists, so the description fully covers what to expect from execution.

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

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

Schema coverage is 100%, but the description adds significant semantic depth beyond the schema. It clarifies that `size_usd` means 'max spend on buys, target proceeds on sells' in single-market mode and 'settlement notional S (shares per leg)' in basket mode. It also explains the auto-default behavior for `side` in basket mode and the difference between `market` and `event` modes.

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

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

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' with specific verbs like 'walks the ladder' and 'returns'. It distinguishes itself from siblings by explicitly referencing polymarket_arbitrage and polymarket_edges signals and positioning itself as the pre-trade risk 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?

Provides explicit usage direction: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Also states the requirement for either `market` or `event` and explains basket vs single-market scenarios, including the warning against partial fills converting arb into directional positions.

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 mark the tool read-only, idempotent, and non-destructive, the description goes far beyond them: it discloses the token-overlap matching strategy, compatibility warning codes, fee modeling limitations, gross-vs-net spread semantics, skipped cross-type/cross-subtype counters, and the meaning of null temporal alignment. This is exceptionally transparent.

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

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

The description is front-loaded with the core purpose and then organized around labeled concepts like TWO MODES, RESPONSE, SAFETY FIELDS, and Codes. It is dense and long, but given the complexity and the absence of an output schema, the detail is largely justified. A little redundancy remains, such as repeating that codes can be non-empty even with matched pairs.

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 carries the full burden of explaining return semantics, and it does so thoroughly: top_spreads_pp, compatibility warnings, per-entry flags, skipped_unclassified, low_confidence_pairs, temporal_alignment, fees_note, and skipped counters are all covered. An agent has enough context to invoke the tool correctly and interpret ambiguous 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%, and the description adds substantial meaning beyond the schema: it explains that both modes run the identical matcher, that explicit ticker/slug overrides replace the topic-mapped sides, how the topic shortcuts map to events, and how parameters interact with the response and disclosures.

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 core function: computing cross-venue spreads between Kalshi and Polymarket for the same resolving question. It distinguishes itself from likely siblings by emphasizing the cross-venue nature, but it does not explicitly name sibling tools or contrast itself against them.

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

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

The two modes and the shortcut list give clear operational context for when to use each pathway, and warnings like 'pre-mapped ≠ tradeable' guide expectations. However, there is no explicit statement about when to prefer this tool over sibling tools such as polymarket_arbitrage or polymarket_edges.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context beyond these: the tool is scoped to an identifier (anonymous IP, BYO key hash, or account ID) and supports dual modes (retrieve vs. list all keys). This enriches the agent's understanding of behavior 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 long, front-loaded with the core action, followed by use case, scoping, and related tools. Every sentence adds distinct value: purpose, usage context, and security scope. There is no redundant or filler wording.

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

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

For a simple tool with one optional parameter, the description covers the action, return behavior (implicitly via 'retrieve a value' or 'list all keys'), usage context, and scoping. Annotations cover safety, and the schema covers the parameter. The description is sufficiently complete without needing to explain return formats or error handling.

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

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

The input schema covers the only parameter 'key' with a description ('Memory key to retrieve (omit to list all keys)') and examples, so schema coverage is 100%. The description essentially repeats the schema's guidance about omitting the key to list all, adding no new semantic meaning. Baseline 3 is appropriate.

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

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

The description starts with a specific verb+resource: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It clearly distinguishes from siblings by mentioning 'remember' (save) and 'forget' (delete), and gives concrete examples of what can be stored (ticker, address, research notes). Purpose is unambiguous and differentiated.

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

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

The description explicitly states when to use this tool: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also mentions pairing with 'remember to save, forget to delete,' which gives related-tool context. However, it does not explicitly rule out alternative lookups (e.g., search) or provide a 'when not to use' condition, so it stops short of a 5.

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

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

Annotations already indicate read-only/idempotent behavior. The description adds valuable context: events carry source/citation_uri/payload, mark_read side-effect affects future calls, and the feed is persisted. Does not contradict annotations.

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

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

Three sentences, each earning its place: purpose, payload/behavior, and alternative access. No fluff, information is front-loaded.

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

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

No output schema exists, but the description explicitly describes what returned events carry, which compensates. Combined with full schema coverage, the tool is well-understood for a simple read operation.

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

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

Schema covers all parameters 100%, but description adds an example ("sec_8k") for type and clarifies mark_read's effect on subsequent calls. This adds 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?

Description opens with a specific verb+resource: "Pull fired events from your subscription feed." It clearly distinguishes from siblings like list_subscriptions (which lists subscriptions) and search, and describes the return payload (source, citation_uri, raw event payload).

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 guidance on filtering by type and since, mentions polling works, and offers an alternative external endpoint for scripts/dashboards. Does not explicitly state when NOT to use it vs other tools, but the context is clear enough.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description goes beyond annotations by adding operational details: parallel fan-out to three sources, fallback triggers (rate-limited or 5xx), USPTO sunset soft-fail behavior, and the structured return shape with citation URIs. No contradiction exists.

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

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

The description is dense and front-loaded, but the opening list of query paraphrases ('What's new with X' / 'latest on Y' / etc.) is somewhat repetitive. However, every subsequent clause adds necessary information: source fan-out, fallback, sunset, since formats, return shape, and alternative tool. It's well-structured and appropriately sized for a tool with this complexity, though not maximally concise.

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 medium-high complexity (multi-source, fallbacks, soft-fail, no output schema), the description covers all essential aspects: return structure (changes[] grouped by source + total_changes + citation URIs), source priority and failure modes, date formats, and the key sibling alternative. Combined with the rich annotations, the agent has enough context to invoke the tool correctly without needing an output schema.

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

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

Schema coverage is 100%: all three parameters have descriptions (type only company, value ticker/CIK, since types and examples). The description adds extra semantic value by explaining since accepts both ISO dates and relative shorthand with examples ('7d', '30d', '3m', '1y') and recommending '30d' or '1m' for typical monitoring—practical guidance beyond the schema. This warrants a score above the baseline 3.

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

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

The description is front-loaded with concrete query phrasings ('What's new with X', 'latest on Y') and then defines the tool as a 'change feed for a company in the last N days/weeks/months in ONE parallel call,' listing the exact sources (SEC EDGAR, GDELT/GNews, USPTO). It explicitly distinguishes itself from entity_profile by pointing to the alternative for static profiles, so the purpose is clear and scoped.

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 entity_profile instead when you want the static profile ... regardless of window,' providing a clear when-not-to-use. It also gives typical window guidance ('Use "30d" or "1m" for typical monitoring') and explains source fallback behavior (GDELT preferred, GNews when rate-limited/5xx, USPTO soft-fails). This tells the agent exactly when and how to use the 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 the annotations (idempotent, non-destructive), the description reveals persistence details ('Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours') and scoping ('scoped by your identifier'). It lacks overwrite semantics or size limits, but adds meaningful context over 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 tight sentences: purpose, when to use, and key behavioral details. Every sentence adds new information without redundancies, and the most critical information is front-loaded.

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

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

For a simple 2-parameter tool with no output schema, the description covers purpose, usage, persistence, scope, and related tools. It's fully sufficient for an agent to select and invoke correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the key-value structure with real-world examples, but doesn't add technical parameter details beyond what the schema already provides.

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

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

The description opens with a specific verb phrase 'Save data the agent will need to reuse later' and clarifies scope across conversations/sessions. It explicitly distinguishes from sibling tools by pairing with 'recall to retrieve later, forget to delete'.

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 concrete when-to-use guidance with examples like 'a resolved ticker, a target address, a user preference, a research subject'. It also names the companion tools (recall and forget), giving clear alternative usage.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, and the description adds substantial behavioral context beyond them: ambiguity handling ('asserts nothing and returns figi_candidates'), explicit `unresolved` reporting instead of silent omission, graceful degradation when GLEIF/OpenFIGI is unavailable, ISIN-to-LEI mapping for non-US issuers, and internal cascading lookups. No contradiction with annotations; this richly informs the agent of call outcomes.

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

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

The description is long but every sentence earns its place given the tool's genuine complexity (two entity types, four identifier systems, ambiguity and degradation behavior). It is front-loaded with the purpose and 'Use FIRST' directive. The first sentence is a dense run-on cramming seven query examples into one clause, which slightly hurts scannability, but structure otherwise organises purpose → types → nuances.

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 multi-source resolution tool with no output schema, the description is remarkably complete: it covers accepted inputs, per-type return content (RxCUI+ingredient+brand; CIK+ticker+company_name+LEI+FIGI), output-shape details (`figi_candidates`, `unresolved`, source-labelled identifiers), failure modes (graceful degradation), and cost context (replaces 2-3 manual lookups). An agent has everything needed 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% and the schema's value description is already detailed, so the baseline is 3. The tool description adds material semantics beyond the schema: it introduces ISIN as a valid input form (absent from the schema's 'ticker, CIK, or name' list), covers the 'who owns X'/'is X a subsidiary of Y' query shapes, and warns that non-equity instruments resolve despite never having tickers. This elevates it above baseline.

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

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

The description opens with concrete example queries and states a specific verb+resource: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It clearly distinguishes from siblings like search, entity_profile, and compare_entities by framing this as the ID-resolution precursor to those tools, and enumerates exactly what it resolves per type (CIK/ticker/LEI/FIGI for company, RxCUI for drug).

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?

'Use FIRST whenever you have a name but need an ID' is an explicit, actionable when-to-use rule that positions this tool as the entry point before other tools. It also lists accepted inputs (ticker, CIK, ISIN, name) and graceful-degradation behavior. However, it never names alternative tools or states when NOT to use it, so the exclusion half of the guidance is missing.

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

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

Annotations already declare read-only, idempotent, non-destructive, so the bar is lower. The description adds meaningful behavior: it probes each entity with ai_visibility_check, ranks by score, surfaces most/least recognized, and lists return fields. It does not mention rate limits or multi-probe cost implications, which keeps it from a 5.

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 tightly written sentences front-load the core purpose, then add mechanism and use case. No redundancy, no filler, and all sentences earn their place.

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

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

The description covers the return format (ranked list with score, confidence, signal density), describes the execution mechanism (probes via ai_visibility_check), and gives a concrete use case. Since there is no output schema, this is sufficient context for an agent to invoke and interpret results.

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

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

Schema description coverage is 100%, so the schema fully documents all parameters, including the entities first-entry-as-subject note. The description does not add any information about parameters beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description states a specific verb ('Compare') and resource ('AI visibility across multiple entities'), explicitly differentiates from ai_visibility_check by emphasizing side-by-side multi-entity comparison, and provides a concrete use case. This distinguishes it clearly from sibling tools.

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

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

It gives a clear use case ('competitive AI-marketing audits') and implies the alternative for single-entity checks by referencing ai_visibility_check as the underlying probe. However, it does not explicitly state when not to use this tool or name alternatives like compare_entities, just missing that final exclusion.

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 and idempotent annotations, the description reveals the fan-out architecture, the 5-30s first-measurement latency, graceful degradation via sources_failed, and the exact return structure. This is substantial behavioral context that annotations alone do not provide.

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

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

The description is dense but organized: it leads with purpose, then sources, use cases, return fields, and limitations. Every sentence adds critical information, though the single-paragraph format could be slightly more structured. It is efficient and front-loaded.

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

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

With no output schema, the description fully compensates by enumerating the exact summary fields, advisory details, links, and alternative versions. It also addresses edge cases (partial failures, timeouts) and ecosystem scope, making it complete for a tool of this complexity.

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

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

The input schema already fully describes both parameters (100% coverage), including scoped package acceptance and version defaulting. The description does not add additional parameter-specific meaning beyond confirming the package is an npm package, so a baseline score of 3 is appropriate.

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

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

The description opens with a clear, specific purpose: a composite 'should I add this npm package to my project' check. It names the concrete data sources (deps.dev and bundlephobia) and distinguishes itself from sibling tools like scan_competitor_ai_presence by focusing on npm dependency analysis.

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

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

The description explicitly states when to use this tool: 'whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides an explicit alternative for non-NPM ecosystems ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly'), giving clear boundary 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 establish readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds useful return-field context, but it does not elaborate on pagination behavior, result ordering, or the implications of openWorldHint. Given annotation coverage, this adds some but not rich behavioral context.

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

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

The description is a single, front-loaded sentence. It states the action, the resource, and the return fields without redundancy or unnecessary words. Every phrase earns its place.

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

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

Given the presence of an output schema and high schema parameter coverage, the description covers the core purpose and return values adequately. It lacks guidance on combining multiple optional filters or pagination nuances, but these are not critical for a search tool with well-structured schema metadata.

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 high (89%), so the input schema already documents most parameters. The description adds no parameter-specific semantics beyond listing return fields, which does not compensate for the small schema gap. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource ('Search USAJOBS announcements') and enumerates the return fields (title, agency, location, salary band, posting/closing dates). This clearly distinguishes it from sibling tools like get_job (retrieving a single announcement) or list_agencies.

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 no guidance on when to use this tool versus alternatives. It does not mention that for a specific job ID, get_job should be used, or that list_agencies handles agency lookups. The only contextual clues come from sibling tool names, which the agent must infer.

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 and idempotentHint, but the description adds significant behavioral details beyond those: output format (top-N passages with character offsets and similarity scores), implementation specifics (BGE-base-en embeddings, cosine, 500-char overlapping windows), and input limits (200K chars, longer inputs truncated and flagged). This transparency helps the agent anticipate results and constraints.

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?

Despite having more content than the ideal two-sentence version, every sentence earns its place: purpose, use case, pairing, and technical limits. The information is front-loaded—the first sentence nails the purpose. No filler or repetition exists, and the structure flows logically from what to how.

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 3 simple params and no output schema, the description covers all necessary context: input source, output shape (passages with offsets and scores), return limit, algorithm, and failure/truncation behavior. It even explains how to integrate with a sibling tool, making it complete for an agent to decide and invoke without additional lookups.

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 enriches the `text` param by giving concrete examples (SEC 10-K body, article, long tool result) and clarifies that `query` is a natural-language expression, reinforcing the intent beyond the schema's examples. While it doesn't add technical syntax not in the schema, it provides valuable usage context that aids parameter selection.

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+resource: 'Semantic search INSIDE a fetched record.' It immediately distinguishes itself from siblings by positioning the tool as operating on already-fetched text rather than external sources, and explicitly contrasts with ask_pipeworx_grounded. This makes the tool's unique role 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 explicit when-to-use guidance: 'Use when the record is too big to cram into the prompt.' It also explains the complementary relationship with ask_pipeworx_grounded, telling the agent to fetch with the gateway and ground over passages instead of the whole document. This is actionable and prevents misuse.

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

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

Annotations already mark this as a non-readonly, non-destructive, idempotent operation. The description adds meaningful behavioral context: authentication prerequisite (OAuth account, anonymous/BYO cannot persist), returns the new subscription id, feed is always-on with a pull mechanism, SMS requires a verified phone with a 10/day cap. 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?

Four sentences efficiently cover the tool's purpose, prerequisites, subscription types, and delivery channels. It is front-loaded with the action and return value. The text is dense but every clause serves a purpose; no filler.

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

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

Comprehensive for a subscription-creation tool: prerequisites, all five types, delivery options, and key constraints like SMS cap and webhook signing secret. The main description mentions the return id, but the general response structure is only partially detailed (webhook secret is in schema). Given no output schema, this is a minor gap.

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%, including inline examples for all types and delivery constraints. The description adds interpretive value (e.g., items:['5.02'] = officer change, polymarket_edge definition) but largely repeats the schema's example payloads. This is a meaningful supplement, not just a restatement.

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 ('Create') and specific resource ('proactive monitoring subscription to a live-data event stream'). It explicitly states the return value (new subscription id), which distinguishes it from sibling tools like list_subscriptions, unsubscribe, and recent_alerts.

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

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

Provides strong context: requires a Pipeworx OAuth account, enumerates the supported subscription types, and explains delivery channels including how to pull the always-on feed. It does not explicitly name alternative tools or when-not to use it, but the creation role is clear versus read/list siblings.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context beyond these: the output shape (category-bucketed questions with exact tool + argument shape), the live catalog source, and the behavioral difference between no arguments vs. a topic override. No contradiction with annotations.

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

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

The description is longer than a single sentence but every clause earns its place: common user phrasings, the category list, the tool+argument detail, no-arg vs. topic behavior, and first-use guidance. It is front-loaded with the question variants and structured with dashes and commas for scannability.

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

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

With no output schema, the description clearly explains what will be returned (category-bucketed questions with exact tool+argument shape), compensating for the missing structured return type. The onboarding context, parameter behavior, and relationship to meta-tools make it complete for guiding an agent's initial exploration.

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

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

Schema coverage is 100% and the single optional `topic` parameter is well-documented in the schema. The description adds useful context by mapping topics to example categories (finance, pharma, betting) and clarifying the no-argument full-spread behavior, though it partially mirrors the schema’s own 'Omit for a cross-category spread' note.

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 specific resource (the Pipeworx tool catalog) and action (suggest/return example questions), and differentiates itself from siblings like ask_pipeworx and discover_tools by framing it as the onboarding entry point that teaches which meta-tools to call. The leading question variants and category list make the 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?

It explicitly instructs 'Use this FIRST when you do not yet know what Pipeworx can do for you' and 'to learn how to call the meta-tools,' naming alternatives like ask_pipeworx, entity_profile, and compare_entities. This provides a clear decision rule for when to choose this tool over its siblings.

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

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

The description adds substantial behavioral context beyond annotations: ownership restrictions, soft-delete behavior (deactivated not deleted), and the effect on historical events via recent_alerts. This aligns with the non-destructive annotation 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?

Three concise, purposeful sentences. The description is front-loaded with the core action, followed by two high-value clarifications. No redundant wording.

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

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

For a simple tool with one parameter and no output schema, the description covers ownership, data retention, and the link to recent_alerts. 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 schema already fully describes the single parameter 'id' as a uuid returned by subscribe. The description's 'by id' adds no new semantic information, so the baseline of 3 applies.

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

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

The description clearly states the action 'Cancel a subscription by id' with a specific verb and resource. The title 'Unsubscribe from Alerts' reinforces the purpose, and the action distinguishes it from siblings like subscribe and list_subscriptions.

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

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

The description implies when to use it (to cancel a subscription) and provides useful context like ownership enforcement and the distinction from deletion, but it does not explicitly name alternative tools or give when-not-to-use scenarios.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, lowering the bar. The description adds substantial behavioral detail: how financial vs. non-financial claims are routed, what each verdict means, and critically warns that 'could_not_verify means the check did not happen... must not be shown as one.' It also clarifies 'unsupported means we looked and cover no source for it.' This goes well beyond annotation-level disclosure.

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

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

The description is longer than average but every sentence earns its place: trigger phrases, routing rules, verdict list, critical caveats, and efficiency note. It is front-loaded with natural-language examples that make the tool instantly recognizable, and contains no filler or redundancy.

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

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

Given the tool's complexity, the description is thorough: it covers the full set of returned verdicts, the two execution paths, the meaning of error cases, and the return value format (actual value with pipeworx:// citation). No output schema exists, so this description carries the full burden—and it succeeds.

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

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

Schema coverage is 100% with both parameters well described. The description adds extra semantics, especially for tolerance_pct: 'Overrides the tolerance implied by the claim wording — set 1–2 for hallucination detection' and 'Default: implied by wording, capped at 5.' It also provides a concrete example for the claim param. This is meaningful added value beyond the schema.

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

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

The description clearly states the tool's function: 'natural-language claim verification against authoritative sources.' It uses a specific verb ('verify') and resource ('factual claims'), and distinguishes it from sibling tools by noting it 'Replaces 4–6 sequential calls' and providing example triggers. The two distinct paths (SEC EDGAR for financial claims, grounded pipeline for others) add specificity.

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 whenever the agent needs to check whether something a user said is factually correct,' which is a strong when-to-use. It also explains scope (company-financial vs. any other factual claim). However, it does not explicitly name alternative sibling tools like search or ask_pipeworx_grounded, nor state when not to use this tool—only implies it replaces a multi-step pipeline.

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