Data Nj

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

Annotations already declare readOnly, openWorld, idempotent, nondestructive. Description adds that default model is free, detailed API key handling (BYO key, passed to Anthropic directly), and return structure. 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?

Efficient 3-sentence description. First sentence states core purpose and output. Second sentence explains model options and API key. Third lists use cases. No wasted words, 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, but description explicitly states return structure: per-model {score, confidence, signals, raw_response} + combined view. All 4 parameters explained. Sufficient for selection and invocation.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. Description adds context like default model, free tier, and that _apiKey is passed straight through, complementing 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 uses a specific verb (probe, score) and resource (LLMs, visibility). It clearly distinguishes from sibling tools like ask_pipeworx by focusing on AI visibility scoring across multiple models. The output format is specified.

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 mentions use cases: AI-marketing audits, pre-launch checks, competitive monitoring. Does not explicitly state when not to use, but provides sufficient context for usage decisions.

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, destructiveHint. Description adds operational details: routes to 4,482 tools, fills arguments, returns structured answer with stable citation URIs, works on every tier, one fast call. 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?

Well-structured with clear front-loading: strong opening, then types of questions, routing explanation, usage hierarchy. Every sentence adds value, though slightly long. Could be tightened but effective.

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 high complexity (many sources, aliases) and no output schema, description covers routing, citation URIs, usage, and examples. Lacks explicit response format but mentions structured answer. For a single-call tool with good annotations, this is fairly complete.

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

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

Schema coverage is 100% (all 6 parameters fully described in schema). Description doesn't add new parameter semantics beyond listing aliases and stating natural language input. Per guidelines, 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 it answers factual questions by routing to many sources, with a specific verb ('ask') and resource ('Pipeworx'). It distinguishes from siblings like ask_pipeworx_grounded and deep_research, and provides numerous examples.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and 'START HERE for most questions'. Provides alternative tools for specific cases (grounded, deep search) and when to use them. Clearly defines when-not-to-use via the 'Step up only when needed' section.

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

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

Annotations already declare readOnly, idempotent, and openWorld, but description adds process details, return format with refusal reasons, and cost, with no contradictions.

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

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

Description is somewhat lengthy but each sentence adds value; front-loaded with purpose and use cases, 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?

Fully explains tool purpose, usage, return format, refusal reasons, and trade-off with sibling; no output schema needed given description's thoroughness.

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 description only repeats aliases; no additional parameter guidance beyond what schema provides, meeting baseline but not exceeding.

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?

Clearly defines the tool as a hallucination-resistant answer mode for high-stakes reads, distinguishes from sibling ask_pipeworx by emphasizing extraction only from tool results and explicit refusals.

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

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

Explicitly states when to use (answers to be quoted/cited/acted on) and when to prefer ask_pipeworx (casual lookups), including cost trade-off.

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?

Extremely transparent: covers resolver contract (market_match_confidence, alternatives), parent event extractor, news fallback mechanisms, safety (low-confidence suppression, closed markets), wide spread handling, and resolution-rule risk. Aligns with annotations (readOnly, idempotent).

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

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

The description is very long (several paragraphs with extensive detail on response shapes, resolver contract, edge cases). While valuable, it could be more concise. Front-loads purpose well but overall verbose.

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

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

Given no output schema and high complexity, the description is remarkably complete. It explains all major response fields (market, analysis, evidence), error/safety paths (low_confidence_match, market_closed_or_inactive), and even edge cases like cancellation rules. No gaps.

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

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

All three parameters have schema descriptions (100% coverage). The description adds context beyond schema, e.g., 'depth' quick vs thorough, 'include_raw' default false to keep responses small, and explains market input types. Adds meaningful nuance.

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 researches a Polymarket bet by pulling Pipeworx data. It specifies input types (slug, URL, question) and gives example usage phrases like 'should I bet on X'. It distinguishes from sibling tools by focusing on evidence gathering for a single bet.

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

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

Explicitly says 'Use for should I bet on X, what does the data say about Y, or is there edge in Z'. Provides classifiers and fan-out examples. Lacks explicit when-not-to-use or contrast with siblings like polymarket_edges or polymarket_arbitrage, but context suffices.

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

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

Annotations already provide read-only, open-world, idempotent, and non-destructive hints. The description adds significant behavioral context: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, inclusion of citation URIs, and sorting behavior. However, it does not cover potential edge cases like invalid identifiers or rate limits.

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 relatively long, the description is front-loaded with trigger phrases and every sentence adds unique value. It is well-structured: triggers, type-specific behavior, sorting, and efficiency claim. No wasted words.

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

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

Given the tool's complexity and lack of output schema, the description effectively explains what data is returned (financials for companies, adverse events for drugs) and mentions citation URIs. It covers key aspects needed for an agent to understand the tool's capabilities and results.

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

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

Schema coverage is 100% for both parameters, but the description adds substantial meaning: for the 'type' parameter, it details the specific financial metrics for 'company' and the counts for 'drug'; for 'values', it provides constraints (2-5 items) and examples (tickers vs. drug names). This goes well 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 performs side-by-side comparison of 2-5 companies or drugs in one parallel call. It provides trigger phrases like 'Compare X and Y' and explicitly contrasts with sequential single-pack lookups, distinguishing it from sibling tools like entity_profile.

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

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

The description gives explicit usage guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It explains what each type does (company vs. drug) and notes results are sorted by primary metric. It also quantifies efficiency by stating it replaces 8-15 sequential lookups.

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, so the safety profile is clear. The description adds value by specifying the returned fields and suggesting the follow-up tool, but does not disclose additional behavioral traits like rate limits or authentication needs.

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

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

The description is two sentences, front-loaded with the primary purpose, and every word adds value. No redundant or 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?

For a simple search tool with good schema coverage and annotations, the description covers the purpose, return fields, and usage hint. It does not mention default pagination details or error handling, but these are adequately handled by the schema and annotations.

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

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

Schema coverage is 100% with all three parameters described. The description does not add extra meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states the action (search), the resource (New Jersey Open Data catalog), and the return fields (resource_id, name, description, category, update date). It distinguishes from sibling tools like 'metadata' by hinting to pass the resource_id to that tool.

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

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

The description provides clear context for when to use the tool (keyword search for datasets) and implies the next step (pass resource_id to query/metadata). However, it does not explicitly state when not to use or provide direct alternatives among siblings.

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

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

Annotations already indicate readOnly=true, openWorld=true, idempotent, non-destructive. The description adds critical behavioral context: account needed (free, paid for thorough depth), 15-60s response time, returns gaps[] when data missing, never invents, and for non-structured topics returns mostly empty gaps. 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 front-loaded with critical prerequisites (account requirement) and structured with usage comparisons, operation explanation, best-use cases, and timing. Every sentence adds value; 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?

Despite no output schema, the description fully explains output: findings packet with verbatim evidence, confidence, source, fetched_at, citation, and explicit gaps. It also covers prerequisites, limitations, alternatives, and timing, making it complete for an AI 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?

Input schema covers 100% of parameters with clear descriptions. The description adds meaningful context: depth values mapped to facet counts (quick=3, standard=5, thorough=8) and clarifies that question is natural language and can be multi-part.

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

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

The description explicitly states it performs grounded multi-source research across Pipeworx's structured data sources, decomposes questions, and returns a findings packet. It distinguishes from siblings like ask_pipeworx by noting its broad/multi-part question scope and that it is not open-web search.

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

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

The description provides clear when-to-use (broad/multi-part questions over structured data) and when-not-to-use (single lookup: use ask_pipeworx; breaking news: prefer ask_pipeworx). It also names the alternative tool and explains the account requirement.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety is clear. The description adds value by disclosing that results are 'ready to call directly, no second schema lookup needed,' which is a behavioral trait beyond annotations. No contradictions.

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

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

The description is a single, well-structured paragraph that front-loads the key purpose and usage context. Every sentence adds value, and it avoids unnecessary detail. Length is appropriate given the tool's complexity.

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

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

Given the 6 parameters (mostly aliases) and no output schema, the description explains the output format (top-N tools with full schemas and examples) and that results are directly callable. It also lists domains covered. This is sufficient for an agent to understand what to expect and how to use the results.

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

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

Schema coverage is 100%, so the schema already documents all parameters with descriptions. The description reinforces the 'query' parameter's meaning as a natural language description and mentions aliases, but adds no new semantic information beyond what the schema 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 tool's purpose: to find tools based on a query describing data or task. It distinguishes itself by being the tool to call first to see the option set, and specifies the return format (top-N tools with full schemas). This is specific and actionable.

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 advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear guidance on when to use this tool versus directly calling a known tool. The list of domains also helps narrow scope.

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 significant behavioral context beyond annotations: it fans out across multiple sources, returns specific fields (filings, fundamentals, patents, news, LEI), and notes the patent soft-failure from May 2025. Annotations already confirm read-only and idempotent nature.

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

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

The description is dense but front-loaded with examples and contains no redundant sentences. It could be slightly broken into sections for readability, but it remains concise given the complexity.

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

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

The tool is complex with no output schema, but the description lists all returned components (cik, filings, fundamentals, patents, news, LEI) and mentions fallback behavior. It could specify the return structure more explicitly, but it is mostly complete.

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

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

Schema description coverage is 100% with clear parameter descriptions in the schema. The description further clarifies that 'type' is only 'company' and 'value' must be ticker or CIK, not names, and cross-references resolve_entity. This adds meaningful guidance.

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

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

The description explicitly states the tool provides a full cross-source profile of a US public company, with multiple example queries. It distinguishes itself from the sibling 'resolve_entity' by noting that names are not supported and that tool should be used first.

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

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

The description explicitly says 'ALWAYS PREFER over chaining single-pack... lookups when the user asks for a holistic view,' clearly defining when to use. It also provides exclusion criteria: names not supported, use resolve_entity first.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. Description adds 'clear sensitive data' context but doesn't specify behavior on missing key.

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

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

Two sentences, no wasted words. Purpose and usage clearly separated.

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?

Adequate for a simple deletion tool with one parameter. Covers purpose, usage, and pairing. Minor gap: no mention of return value or error handling, but acceptable.

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?

Single parameter 'key' with schema description 'Memory key to delete'. Tool description adds no further semantics beyond schema. Schema coverage 100%.

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

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

Clear verb-delete, resource-memory, method-by-key. Distinguishes from siblings remember and recall.

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

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

States when to use (stale context, task done, clear sensitive data) and pairing with remember and recall. Lacks explicit when-not-to-use but sufficient.

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 value by detailing the fetch-and-extract process ('Fetches the page, extracts title/description/key links, emits markdown'), which goes beyond annotations. No contradictions.

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

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

The description is three sentences, front-loaded with the main action, and every sentence adds value. No unnecessary words, making it highly efficient for an agent to parse.

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

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

Given the tool's simplicity (2 params, no nested objects, no output schema) and the annotations covering read-only and idempotent behavior, the description covers the key aspects: what it does, how it works, and use cases. Could mention error handling or limitations, but overall sufficient.

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

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

Schema coverage is 100%, and both parameters have decent descriptions in the input schema. The description does not add new meaning beyond what the schema provides (e.g., 'url' and 'max_links' are already explained). Hence, no extra value.

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 generates an llms.txt file for a URL, specifying the verb 'Generate' and resource 'llms.txt file'. It mentions AI crawlers and the output format. However, it does not explicitly differentiate from sibling tools like 'scan_competitor_ai_presence', which might also deal with AI indexing.

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 use cases ('getting a client's site indexed by AI, drafting llms.txt...') which imply when to use. However, it lacks explicit guidance on when not to use or alternatives, leaving the agent to infer usage context without exclusions.

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

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

Annotations already declare readOnlyHint and destructiveHint, so description need not restate. Adds value by listing exact return fields (id, type, params, timestamps, count) and clarifying 'active' scope, enhancing transparency beyond annotations.

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

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

Two sentences: first states action and output fields, second gives usage advice. No wasted words, front-loaded with purpose.

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

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

Despite no output schema, description fully documents return fields. Parameter is covered by schema. For a simple list operation, this is complete and leaves no gaps.

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

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

Schema covers the only parameter (include_inactive) with full description. Description adds no extra semantic information beyond that. Baseline 3 is appropriate as schema does the heavy lifting.

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

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

Description clearly states the tool lists active subscriptions and specifies exact return fields. Differentiates from siblings like subscribe/unsubscribe by focusing on listing for review/cancellation.

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 advises using the tool to review monitored subscriptions before adding more or to find an id to cancel. Could be stronger by noting when not to use, but context from description is sufficient.

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, non-destructive, idempotent, and open-world behavior. The description adds concrete return fields (columns, types, row count, category, last-updated), providing useful context 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?

Single sentence with 20 words, includes a concrete example, and efficiently conveys the tool's action and output. No wasteful language.

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 adequately explains return values (schema + metadata fields). For a simple read-only tool with one parameter, it covers essentials. Lacks details on error handling or rate limits, but these are minor gaps.

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

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

Schema coverage is 100% with a clear description and example for resource_id. The description repeats this example and ties it to the tool's function, adding marginal value. Baseline 3 is appropriate because the schema already documents the parameter well.

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?

Clearly states the tool retrieves schema and metadata for a New Jersey Open Data dataset by resource_id, including specific fields. The example clarifies the parameter format. However, it does not explicitly distinguish itself from the sibling 'datasets' tool, which might list datasets, missing an opportunity for differentiation.

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?

Implicitly suggests use when needing schema/metadata for a known dataset id, but provides no explicit guidance on when not to use or alternative tools. The 'datasets' sibling could be an alternative for discovering dataset ids, but this is not mentioned.

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

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

Annotations are all false, which is appropriate for a feedback tool that is a write operation but not destructive. The description adds behavioral context beyond annotations: 'The team reads digests daily and signal directly affects roadmap,' 'Rate-limited to 5 per identifier per day,' and 'Free; doesn't count against your tool-call quota.' These details disclose important behavioral traits not captured by annotations.

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

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

The description is a single paragraph that is well-structured and front-loaded: it starts with the main purpose, then usage guidance, then behavioral notes. Every sentence adds value without redundancy. It is concise yet comprehensive.

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

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

Given the simple structure (3 parameters, 2 required, no output schema needed for feedback), the description covers all necessary aspects: purpose, usage, behavior, and parameter semantics. It is complete for the tool's complexity.

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

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

Schema description coverage is 100% (all parameters have descriptions). The description adds significant extra meaning: it explains the enum values in detail ('bug = something broke...', etc.) and provides usage guidance for the message field (be specific, 1-2 sentences, 2000 chars max). This goes well beyond the schema.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies the verb 'tell' and the resource 'Pipeworx team'. It further distinguishes feedback types (bug, feature, praise) with specific triggers, making it distinct from sibling tools.

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

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

The description provides explicit when-to-use guidance: 'when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also advises on what to write ('describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt') and mentions rate limits and quota, giving complete usage context.

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

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

Adds valuable behavioral context beyond annotations: data source (CF analytics-engine), no PII, aggregation details, and caching freshness (5min-1h). Annotations already declare readOnlyHint, idempotentHint, etc., and description does not contradict 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?

Description is concise (three sentences) and front-loaded. Every sentence adds value: core function, use cases, and behavioral details. No redundancy or fluff.

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

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

For a simple read-only aggregate tool, the description covers all necessary context: what it returns, how it works, caching, and privacy (no PII). No output schema needed, and the description is sufficient for correct use.

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 one parameter. Description adds nuance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This clarifies the parameter's semantics beyond the schema.

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

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

Description clearly states the tool returns top tools, top packs, and total call volume over configurable windows. Uses specific verb 'returns' and specifies the resource, distinguishing it from sibling tools like ask_pipeworx or discover_tools.

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

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

Explicitly lists three concrete use cases (discovering hot data sources, confirming canonical tool, checking use case alignment). Does not explicitly mention when not to use it or alternatives, but the use cases provide clear guidance.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable context: explains the analysis methods (partition check, fill check), semantic anchor, partition filter, and conditions under which trades should not be executed (realizable edge <= 0). 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 structured with a clear requirement upfront, followed by detailed explanations of each mode. While slightly verbose given the complexity, every sentence adds value and it is well-organized.

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

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

Given no output schema, the description explains the response structure (opportunities[], partition_check) and fill check details. It references a sibling tool for custom sizing, making the documentation self-contained for a complex tool.

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

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

Both parameters have descriptions in the schema (100% coverage). The description goes well beyond, explaining the difference between event and topic modes, providing examples, and detailing additional logic like semantic anchor and partition filter.

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

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

The description clearly states the tool's purpose: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes two distinct modes (event and topic) with specific use cases, making it easily distinguishable from sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

The description explicitly requires one of `event` or `topic` and explains that calling with no args fails. It provides clear guidance on when to use each mode with examples. However, it does not explicitly state when not to use the tool beyond the failure condition.

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 thoroughly discloses behavioral traits beyond annotations: caching at 1h keyed on all knobs, placeholder-slug filters, partition skipping conditions, Fed bets exclusion, 24h-move warning, and the structure of diagnostics. No contradictions with annotations (readOnlyHint, idempotentHint, destructiveHint are all consistent).

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

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

The description is well-structured with clear sections by model family, response segments, and knobs. It is dense but front-loaded with the main purpose. A slight reduction in detail could improve conciseness without losing value, but 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?

Given the complexity (9 parameters, no output schema, multiple response segments), the description is exceptionally complete. It explains response top-level structure, caching, edge cases like Fed bets, diagnostics, and net edge calculation. No output schema exists, so the description fully covers what the agent needs to know.

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?

With 100% schema coverage, baseline is 3. However, the description adds substantial meaning: explaining min_kelly as skipping too-small opportunities, max_spread_pp as eating edges, min_liquidity as preventing book-walking, min_partition_leg_kelly as addressing why partition arbs don't respond to min_kelly, and slippage_pp rationale. This far exceeds the baseline.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It is built for 'what should I bet on today' and distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by focusing on model-driven, structural arbitrage, and concentrated longshot opportunities.

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 context for when to use the tool, such as 'agents discover opportunities without paging hundreds of markets.' It also explains tradeable-edge knobs like min_liquidity and max_spread_pp. However, it does not explicitly differentiate from closely related siblings like polymarket_arbitrage or polymarket_edge_tracker, but the detailed coverage compensates.

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 critical behavioral details: data comes from daily closes, not intraday, snapshots are written on cache-miss causing gaps, and the response includes trend indicators. This adds significant value beyond the structured annotations.

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

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

The description is well-structured: purpose first, then arguments, then response structure, then limits. It is front-loaded with the key idea. However, it is somewhat verbose with long sentences, which slightly reduces conciseness.

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

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

Despite lacking an output schema, the description provides a detailed breakdown of the return format (tracked, expired, snapshot_dates with fields) and explains the limitations (TTL, data generation). This fully informs the agent about what to expect.

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

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

Schema coverage is 100% with clear parameter descriptions. The description repeats defaults and clamps for 'days' and adds context about the 'window' parameter (snapshot family). However, it does not add new meaning beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It answers a specific user question ('how long has this edge existed and is it shrinking?') and distinguishes itself from the raw polymarket_edges tool by focusing on historical 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 explains when to use this tool (to differentiate fresh vs. old edges) and mentions limits (60-day snapshot TTL). It does not explicitly state when not to use it, but the context implies it's not for real-time data. Alternative sibling tools like polymarket_edges are implicitly contrasted.

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

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

Annotations already declare readOnly, idempotent, non-destructive. The description adds beyond annotations: explains ladder walking, return fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and risks of partial basket fills. 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?

Description is well-structured with sections for single-market and basket modes. Front-loaded with purpose. Though lengthy (~200 words), every sentence serves a purpose. Could be slightly more concise but effective.

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

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

Given no output schema, the description thoroughly explains return values for both modes (e.g., top_of_book, vwap_fill_price, capture_ratio, thin_legs, forced_directional_risk). It covers edge cases like thin books and partial fill risks. Context signals (4 params, high schema coverage) support completeness.

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

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

Schema description coverage is 100% (all 4 parameters described in input schema). The description adds extra context: default behavior for side (auto for basket), interpretation of size_usd as settlement notional for basket, and mode selection via market/event. This enhances but does not critically add missing info beyond schema.

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

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

Description clearly states it performs a realizable-vs-theoretical edge check against live CLOB order-book depth. It distinguishes between single-market and basket modes and explicitly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by stating 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal'.

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 advises when to use: before polymarket_arbitrage signals or polymarket_edges trades above ~$500. It also warns about partial basket fills converting arb into unhedged directional positions. Requirements (market or event) are clearly stated.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds significant behavioral context: compatibility_warning conditions (match shape mismatches, semantic irrelevance), temporal alignment checks, and detailed counter fields (skipped_cross_type/subtype). 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 informative but somewhat lengthy; however, every sentence adds value. It uses clear section headers (TWO MODES, RESPONSE, SAFETY FIELDS) and key terms in bold, aiding readability. Could be slightly more concise, but overall 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?

No output schema exists, so the description fully explains return fields, safety warnings, and edge cases (compatibility_warning, temporal alignment, skipped counters). It covers all aspects of the tool's behavior and handles the optional parameters and two-mode design completely.

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

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

Schema coverage is 100%, and the description adds meaning by explaining the two modes and how explicit parameters override topic-mapped ones. It lists all 10 macro shortcuts and provides examples. The description goes beyond the schema's property descriptions, justifying a score above 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 clearly states the tool computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It specifies two modes (topic shortcuts and explicit tickers) and distinguishes itself from sibling tools like polymarket_arbitrage by focusing on inter-venue spreads.

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

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

The description explicitly advises when to use the tool (e.g., for comparing venues) and warns about limitations: 'Real cross-venue spreads are rarer than the macro-shortcut list suggests — most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable.' It also explains how to interpret the output and when spreads are meaningful.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description is not required to reiterate safety. It adds context: results are returned as JSON, SoQL clauses omit the leading $, and default limit is 1000. 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?

Two sentences, each essential. Purpose is front-loaded, and every word earns its place. No redundancy or fluff.

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

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

For a 7-parameter query tool with no output schema, the description covers the core usage, parameter behavior, and return format. It could mention error handling or that resource_ids come from 'datasets', but is generally 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 coverage is 100%, baseline 3. The description adds meaning by explaining that where/select/group/order use SoQL clauses without the leading $, and mentions default limit. This helps the agent construct correct queries beyond the schema's property descriptions.

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

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

The description clearly states the tool runs a Socrata SoQL query against a New Jersey Open Data dataset, specifying the required resource_id, the filtering clauses (where/select/group/order), pagination (limit/offset), and return format (JSON rows). This distinctively separates it from sibling tools like 'datasets'.

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

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

The description implies usage for querying datasets, but does not explicitly state when to use it versus alternatives or provide exclusions. No guidance on when not to use it or mention prerequisites like valid dataset IDs.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description is not required to repeat those. It adds behavioral context like scoping to identifier and pairing with other tools, but does not significantly expand 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 concise (3 sentences), front-loaded with the primary action, and uses efficient wording without redundancy.

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

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

Given the tool's simplicity and full schema coverage, the description adequately explains purpose, usage, scoping, and relationships with siblings. No output schema is present, but the tool's return behavior is implied sufficiently.

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 with a clear description of the 'key' parameter. The description adds value by explaining the behavior when the key is omitted (list all keys), which is not directly in the schema.

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

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

The description clearly states the action ('Retrieve a value') and resource ('previously saved via remember'), and distinguishes from siblings like 'remember' and 'forget' by mentioning them. It also covers the alternative behavior of listing all keys when no argument is provided.

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 to look up context the agent stored earlier' and mentions scoping and pairing with remember/forget. It provides clear usage context but does not include explicit when-not-to-use guidelines or alternative tools beyond the siblings mentioned.

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 non-destructive and idempotent. Description adds that mark_read flags events read, a safe side effect. No contradiction.

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

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

Four efficient sentences, front-loaded with purpose. Every sentence adds value; no 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?

No output schema, but description details return fields (source, citation_uri, raw payload). Covers filtering, mark_read, and alternative access method. Complete for agent 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?

Schema has 100% coverage with descriptions. Description adds examples (e.g., 'sec_8k'), clarifies mark_read effect, default limit, and ISO timestamp format.

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?

Clearly states it pulls fired events from subscription feed, returns most recent alerts with specific fields. Distinct from siblings like 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?

Provides clear usage context: filtering by type/since, mark_read behavior, polling suitability, and alternative REST endpoint. Lacks explicit exclusions or comparisons with 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 indicate safety (readOnly, idempotent, not destructive). Description adds valuable behavioral details: fan-out to multiple sources, fallback logic, soft-fail for USPTO, and return structure. 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?

Description is front-loaded with example queries and structured logically. Slightly verbose but every sentence adds value; could be tightened without losing 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 complex tool with multiple data sources, fallbacks, and no output schema, the description thoroughly covers sources, parameter behavior, return structure (changes[], total_changes, citation URIs), and distinguishes from entity_profile, making it complete for an AI agent.

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

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

Schema covers all 3 parameters (100% coverage). Description enhances with examples for `since` (ISO or relative shorthand, recommended values), clarifies `value` can be ticker or CIK, and confirms `type` is limited to 'company'.

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

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

Description clearly states the tool provides a change feed for a company in a time window, listing specific sources and example queries. It distinguishes from sibling tool entity_profile, 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?

Explicitly advises when to use entity_profile instead, provides recommended values for `since` parameter, and explains fallback behavior between GDELT and GNews, offering clear decision guidance.

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

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

Discloses beyond annotations: key-value scoping by identifier, persistence duration for authenticated vs anonymous users, and non-destructive nature. No contradiction with annotations (idempotentHint=true, destructiveHint=false).

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?

Description is somewhat long but front-loaded with main purpose. Every sentence adds value, covering when to use, persistence details, and pairing. Could be slightly more concise but not verbose.

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

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

Given the simple nature of the tool and presence of sibling tools (recall, forget), the description fully covers purpose, usage hints, persistence, and scoping. No output schema needed; completeness is high.

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

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

Schema coverage is 100% with clear parameter descriptions. Description adds value by stating stored as key-value pair scoped by identifier, reinforcing purpose. Since schema already covers basics, the additional context justifies a 4.

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

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

Description clearly states the tool saves data for later reuse across conversations/sessions, with specific verb 'Save data... reuse later' and resource 'data'. Differentiates from siblings by mentioning recall and forget as complementary 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?

Explicitly says when to use: 'when you discover something worth carrying forward'. Provides context on persistence scoping and pairing with recall/forget, though lacks explicit 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 indicate safety (readOnly, idempotent, non-destructive). The description adds valuable behavioral context: it cascades through multiple lookup endpoints internally, replaces 2-3 manual lookups, and includes citation URIs. No contradiction with annotations.

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

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

The description is well-structured with examples and a clear list of types. It is slightly long but every sentence adds value. Front-loading with examples aids quick comprehension.

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

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

Given high schema coverage and informative annotations, the description fully covers what the tool returns for each input type, its use cases, and its internal behavior. No output schema is needed because the description explains the return values adequately.

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 both parameters have descriptions. However, the description enriches meaning by specifying the exact output format per type (e.g., ticker + CIK + company_name for companies, RxCUI + ingredient for drugs), auto-disambiguation behavior, and accepted input variants.

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 concrete examples ('What's the ticker for…') and explicitly states it resolves names to canonical/official identifiers. It distinguishes itself from sibling tools like 'entity_profile' by positioning itself as the first step for name-to-ID tasks, and lists supported entity types with details.

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 'Use FIRST whenever you have a name but need an ID,' providing clear when-to-use guidance. It does not explicitly exclude cases (e.g., when an ID is already known), but the directive is strong enough to guide the agent.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds behavioral details: it probes each entity by calling ai_visibility_check, ranks results, and returns a ranked list. This provides context beyond the annotations, such as the internal mechanism and output format.

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

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

The description is three concise sentences: first states purpose and mechanism, second provides use case, third describes output. It is front-loaded with the core action and is free of 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 no output schema, the description explains the return format (ranked list with score, confidence, signal density). With high schema coverage and annotations, the description covers the tool's behavior, inputs, and output adequately for agent invocation.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds value by clarifying that the first entity in the 'entities' array is treated as the subject for narrative, which is not in the schema. It also reiterates model options and context usage, enhancing the schema descriptions.

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

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

The description clearly states it compares AI visibility across multiple entities, specifying the action (compare, probe, rank) and the resource (AI visibility). It distinguishes from sibling ai_visibility_check by focusing on multiple entities and competitive audits.

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

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

The description explicitly provides a use case (competitive AI-marketing audits) and implies the context for using this tool over a single-entity check like ai_visibility_check. However, it does not explicitly state when not to use it or list alternatives beyond the sibling context.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description discloses important behavioral traits: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed listing. It also details the output structure, aiding the agent in interpreting 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 a single paragraph that fronts the main purpose, then adds details. While efficient, it could benefit from more structure (e.g., bullet points for the return fields). No unnecessary sentences.

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

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

Despite having no output schema, the description thoroughly explains the return values (summary block fields, per-advisory detail, links, alternative versions) and includes edge-case behavior (partial failures). Combined with annotations, it provides a complete picture for this two-parameter tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add significant new information about parameters beyond what the schema provides, though it confirms the default behavior for 'version'.

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 verb ('check') and resource ('npm package'), and highlights it as a composite call across two services. It distinguishes itself from siblings like 'scan_competitor_ai_presence' by explicitly scoping to npm dependencies.

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 ('whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'') and when not to ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly'), providing clear alternatives.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. The description adds critical behavioral details: embedding model (BGE-base-en), cosine similarity, 500-char overlapping windows, character offsets, 200K char cap with truncation flag. 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?

Four sentences, front-loaded with core purpose, then usage guidance, then technical details. Every sentence adds value; no redundancy. Well-structured for quick scanning.

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

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

All key aspects are covered: what it returns (top-N passages with offsets and scores), truncation behavior, pairing with sibling tool. No output schema exists, but description compensates fully. Complete for a search/retrieval tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds example queries and re-iterates the max character limit, but does not provide significant new meaning beyond what the schema already documents. Adequate but not exceptional.

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 (semantic search), the target resource (a fetched record), and the scope (inside the record). It distinguishes from siblings like ask_pipeworx_grounded by describing how they pair. The title and name reinforce the purpose.

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

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

Explicitly states when to use ('Use when the record is too big to cram into the prompt') and provides an alternative ('Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages...'). No ambiguity.

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 indicate it's not read-only, idempotent, and not destructive. The description adds critical behavioral details: returns subscription ID, requires verified phone for SMS with a 10/day cap, webhook auto-disabled after 10 failures, and signing secret returned once. 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 well-structured with clear sections (purpose, requirements, types, delivery) and uses dashes for readability. It is slightly lengthy but each sentence adds useful information; no 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?

No output schema, but the description covers return value, all parameter contexts, account requirements, type-specific params, delivery options with limitations, and failure behavior. It is fully adequate for the agent to use 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%, but the description adds significant value by explaining type-specific parameters (e.g., examples for sec_8k items), delivery options with format and constraints, and webhook HMAC signing details. This goes well 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 'Create a proactive monitoring subscription to a live-data event stream.' It uses specific verb plus resource, and the detailed type and delivery options distinguish 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?

The description provides explicit context: requires Pipeworx OAuth account, supported types with examples, and delivery channels with constraints. It does not explicitly mention when not to use this tool versus alternatives, but the requirements and scope are clearly conveyed.

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, destructiveHint=false, idempotentHint=true. The description adds valuable context: it returns example questions from a live catalog with exact tool+argument shapes, and explains that no arguments gives full spread while passing topic focuses. 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 relatively long but each sentence adds value: trigger phrases, output explanation, usage guidance, parameter details. It is front-loaded with common user queries. Could be slightly more concise but is 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 onboarding tool with 1 optional param and no output schema, the description fully explains what it returns (category-bucketed example questions) and how to use it. It also mentions meta-tools. No gaps remain.

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 one optional parameter. The description reinforces the parameter's purpose and lists example values ('finance', 'pharma', etc.), adding meaning beyond the schema's description. The baseline is 3 due to high coverage, but the description provides extra clarity.

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 'onboarding entry point' and specifies that it returns category-bucketed example questions with tool+argument shapes. It uses a specific verb ('suggest questions') and distinguishes from siblings like 'ask_pipeworx' and 'discover_tools' by being the first step to understand capabilities.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Provides clear context for when to use (onboarding) and implies when not (already familiar). Also explains the optional 'topic' parameter for focusing.

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?

Describes deactivation vs deletion and that historical events remain via recent_alerts, adding context beyond annotations.

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

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

Two sentences, no fluff, front-loaded with core action.

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?

Sufficient for a one-parameter tool; covers ownership and side effects. Could mention return value but not critical.

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 description adds that id is a uuid returned by subscribe, reinforcing its origin. Slight value added.

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?

Clearly states the verb 'Cancel' and the resource 'subscription by id'. Distinguishes 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?

Explicitly states ownership enforcement: 'you can only cancel your own subscriptions', providing clear guidance on when to use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds value by detailing the return format (verdict, structured form, citation, percent delta) and explaining that it replaces multiple sequential calls. No side effects or limits are disclosed, but the existing annotations cover safety.

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 informative but slightly verbose. It front-loads with example phrasings and purpose, but could be tightened. Still, it effectively communicates the tool's role without unnecessary fluff.

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

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

Given the tool has one parameter, no output schema, and comprehensive annotations, the description is complete. It covers purpose, usage, return type, and scope, leaving no major gaps for an agent to interpret.

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

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

Schema coverage is 100% with a description for the only parameter. The description supplements this with natural-language examples and contextual scope (company-financial), adding meaning beyond the schema.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources, specifically company-financial claims. It distinguishes itself from sibling tools by mentioning it replaces multiple sequential calls and specifying the domain.

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: 'whenever the agent needs to check whether something a user said is factually correct.' It also provides scope limitations (company-financial claims), guiding the agent on appropriate use cases.

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