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?

The description discloses internal routing behavior, auto-filling of arguments, response format with 'stable pipeworx:// citation URIs,' and performance characteristics ('one fast call', 'works on every tier'). This adds context beyond annotations (readOnly, openWorld, idempotent) 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?

Although long, the description is front-loaded with the most critical guidance ('PREFER OVER WEB SEARCH'), then provides concrete examples, and concludes with alternatives. Every sentence provides actionable information; no filler or repetition of schema/annotations.

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

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

With no output schema, the description still explains the return format ('structured answer with stable pipeworx:// citation URIs') and covers when to use alternatives, expected question domains, and triggers. It's thorough for a meta-tool with broad scope.

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

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

Input schema already provides 100% coverage describing the 'question' parameter and aliases. The description adds examples and notes the tool auto-fills arguments, but these are usage/behavioral details rather than new parameter semantics, so the baseline 3 applies.

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

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

The description clearly identifies the tool as a question-answering router that 'routes the question to the right one of 5,564 tools across 1462 verified sources, fills arguments, returns the structured answer with stable pipeworx:// citation URIs.' It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by naming them and explaining when to use each.

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

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

Provides explicit 'PREFER OVER WEB SEARCH' and lists specific domains (SEC filings, FDA drug data, FRED/BLS, etc.). It gives trigger phrases ('what is', 'look up', 'find', 'get the latest') and alternative tools with conditions: 'for a hallucination-resistant single answer with verbatim evidence + confidence use ask_pipeworx_grounded; for a broad/multi-part question that should fan out across many sources at once use deep_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 cover read-only, non-destructive, idempotent, and open-world aspects. The description adds context about the beta nature, that exactly one experimental candidate may be live, and that currently it matches ask_pipeworx exactly. It also clarifies it's a full working router, not a stub, which goes beyond annotations without contradiction.

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

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

The description is a single coherent paragraph that efficiently covers beta status, current behavior, usage guidance, and a clarifying note. It's not overly verbose, and every sentence contributes value, though it could be slightly tighter by merging some clauses.

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 question-to-response router with no output schema, the description is complete enough. It references the response shape via 'same response shape' and gives sufficient context about its experimental nature and current parity with the stable version. Missing details about what routing improvements might entail are minor given the tool's simplicity.

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

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

Schema coverage is 100%, and the schema already describes the 'question' parameter and its aliases. The description only says 'same arguments' without adding any new semantic detail, so it relies on the schema's existing documentation. Baseline 3 is appropriate.

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

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

The description clearly states this is a beta version of ask_pipeworx, a universal router, and explicitly mentions it handles the same 5,564 tools with identical arguments and response shape. It distinguishes itself by being the experimental edge with routing improvements under test, making its purpose unmistakable.

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

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

It provides explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing' and notes results are compared against the stable router to decide merges. This gives a clear when-to-use instruction and implies when not to use (when you want stable routing).

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description goes far beyond these by detailing the return structure (evidence, confidence, source, refusal_reason) and all possible refusal reasons, plus the extra LLM call cost. No contradictions with annotations.

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

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

The description is dense but every clause adds value: purpose, routing mechanism, return format, refusal reasons, usage guidance, and cost comparison. It is front-loaded with the core purpose and structured logically. 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 high complexity (routing through thousands of tools, grounding, refusal handling) and lack of an output schema, the description fully explains return values and refusal behavior. It also covers cost implications and appropriate use cases, making it complete for agent decision-making.

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

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

The schema provides 100% coverage, documenting all six parameters as aliases for 'question'. The description does not add additional parameter-specific semantics beyond what the schema already states. Baseline 3 is appropriate since the schema fully documents the parameter behavior.

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

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

The description clearly states the tool's purpose: a hallucination-resistant answer mode that extracts answers grounded in tool results. It explicitly distinguishes itself from the sibling ask_pipeworx by mentioning 'Same routing' and adding a grounding layer. The verb 'extracts' and resource 'answer mode' are specific and unambiguous.

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

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

Provides explicit usage guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts...' and contrasts with the cheaper alternative: 'prefer ask_pipeworx for casual lookups.' Also lists concrete refusal scenarios. This fully satisfies the when/when-not criterion.

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?

Beyond the readOnly/idempotent/destructive annotations, the description adds critical operational behavior: account requirement and paid tier for thorough, explicit gaps[] for unanswered facets, contradictions[] on standard/thorough, hop and citation_uri semantics, semantic excerpting, and latency ranges. This is far richer than annotation-only 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 long but densely packed and front-loaded with the most critical operational gate (ACCOUNT REQUIRED). Some repetition around ask_pipeworx and depth behaviors exists, but every sentence adds a useful constraint or expectation for a complex tool; slight pruning could tighten it.

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

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

For a complex tool with no output schema, the description fully covers input semantics, result packet shape (verbatim evidence, confidence, source, fetched_at, citation), failure behavior (gaps[]), contradiction handling, citation fetchability, latency, and sibling alternatives. Nothing important appears 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?

Though schema coverage is 100%, the description materially extends parameter understanding: depth:'thorough' requires a paid plan, standard adds a gap-recovery hop plus contradiction scan, thorough chases leads, and the question parameter is clarified as accepting broad/multi-part natural-language input. This goes beyond the enum descriptions in the schema.

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

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

The description opens with a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources in ONE call', and explicitly frames what it is not ('this is NOT open-web search'). It clearly differentiates from siblings by naming ask_pipeworx as the single-lookup and current-news alternative.

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

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

Provides explicit when-to-use guidance ('Best for broad/multi-part questions over structured data'), exclusions ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'), and an account/auth gate with fallback ('If you are not signed in, use ask_pipeworx'). It also maps depth levels to usage 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=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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds substantial behavioral context beyond this: it fans out across multiple sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), specifies the exact return structure (cik, recent_filings with URIs, fundamentals sorted by period_end DESC), and discloses known limitations (USPTO PatentsView API sunset May 2025 with soft-fail, GDELT→GNews fallback). This is rich transparency for a read-only 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 long but every sentence earns its place: trigger examples, preference directive, output schema summary, fallback behaviors, and input constraints. It could be slightly better structured with bullets or section breaks, but it remains efficient and front-loads the most important information.

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

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

Despite having no output schema, the description fully enumerates the return payload including field names, ordering, counts, and URI format. It covers data-source fallbacks, limitations (US public companies only, patent API sunset), and input edge cases. An agent can confidently invoke the tool and parse its results based on this description alone.

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

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

Schema description coverage is 100%, and both parameters are fully documented in the schema. The description repeats the same ticker/CIK guidance and 'names not supported' note but does not introduce any new parameter semantics beyond the schema. Baseline 3 is appropriate since the schema already carries the 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 opens with concrete example prompts ('Tell me about X', 'research Acme') and immediately defines the tool's core function: 'full cross-source profile of a US public company in ONE parallel call.' It clearly distinguishes itself from sibling tools by stating 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' making the purpose and 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?

Explicit usage guidance is provided: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' for holistic views, and 'names not supported (use resolve_entity first if you only have a name).' This tells the agent both when to use this tool and what to do when the input doesn't match, naming the alternative tool.

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

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

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?

Despite annotations already declaring readOnlyHint, idempotentHint, and destructiveHint, the description adds rich behavioral context: it explains the two cases where compatibility_warning fires (non-equivalent bet shapes vs unrelated events), the meaning of temporal_alignment, and the semantic of skipped_cross_type/subtype counters. This goes far beyond the annotations and fully clarifies the tool's safety and output semantics without contradiction.

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

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

Although lengthy, the description is exceptionally well structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and a clear progression. Every sentence adds domain-relevant insight—no filler. The first sentence establishes purpose, and subsequent content appears exactly where the reader expects it.

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

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

For a complex cross-venue tool with no output schema, the description is remarkably complete: it describes the response structure (leg-by-leg prices, matched spread, top_spreads_pp), safety fields and their triggering conditions, temporal alignment significance, and the interpretation of skip counters. It also includes a caution about real-world rarity, ensuring the agent understands the tool's practical reliability. No output schema is needed because the description effectively documents key return fields.

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

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

Even though schema coverage is 100%, the description adds significant meaning: it explains the 'pre-mapped' topic list, clarifies that explicit kalshi_event_ticker and polymarket_event_slug 'override' the topic-mapped side, and that the two modes are mutually complementary. The description also provides examples and warns about the tradeability of mapped topics, which the schema alone does not convey.

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

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

The description opens with a precise definition: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly identifies the resource (cross-venue spread) and the verb (compute/imply), and distinguishes itself from sibling tools by focusing on inter-venue comparison rather than intra-venue arbitrage or edge tracking.

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 outlines TWO MODES ('topic' vs explicit ticker/slug) and explains when each is appropriate, including override behavior. It also warns that 'pre-mapped ≠ tradeable' and that 'most pre-mapped topics return compatibility_warning today,' guiding against over-reliance on shortcuts. However, it does not explicitly mention alternative tools from the sibling list (e.g., polymarket_arbitrage) for comparison, so it lacks direct differentiation.

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 indicate read-only, idempotent, open-world. Description adds rich behavioral details: internal cascading through multiple lookups, graceful degradation when LEI/FIGI sources unavailable, and labeling of identifier sources with explicit `unresolved` field. Goes well beyond the annotations.

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

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

The description is lengthy but each sentence adds unique value. Front-loaded with example queries to quickly convey purpose. Slightly verbose in the company type explanation, but still efficient for the complexity it covers.

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 explains what identifiers are returned per entity type, how resolution works across sources, and what happens when enrichment fails. Covers both supported types and edge cases (graceful degradation). Complete for a lookup tool of this complexity.

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

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

Schema coverage is 100%, but description adds extensive context: explains the meaning of 'company' and 'drug' types, acceptable input formats (ticker, CIK, ISIN, names), output structure (identifiers, sources, unresolved), and special behavior like ISIN-to-LEI mapping. Greatly enriches 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 clearly defines the tool's verb (resolve) and resource (user-spoken names to canonical identifiers). Examples like 'find the ticker for...' and 'look up the ID for...' make the purpose concrete. Distinguishes well from sibling tools like entity_profile and compare_entities by focusing on name-to-ID conversion.

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

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

Explicitly states 'Use FIRST whenever you have a name but need an ID.' Provides supported types and hints at when not needed (e.g., if already have ID). Does not explicitly name alternatives, but the context of sibling tools plus 'replaces 2-3 manual lookups' offers strong implicit 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 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.