Osf

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows it's safe. The description adds value by explaining the probing mechanism, per-model returns (score, confidence, signals, raw_response), and combined view, going beyond annotations.

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

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

The description is two sentences: first introduces the main purpose and default, second provides details on models and returns. No wasted words, well-structured and front-loaded.

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

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

Given 4 parameters and no output schema, the description adequately explains the return format and use cases. It could detail scoring methodology, but overall 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%, but the description adds meaning: default model is Workers AI Llama-3.3-70b (free), _apiKey enables Anthropic probing, and context parameter disambiguates. This enhances understanding beyond the schema descriptions.

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

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

Description clearly states the tool probes LLMs for knowledge about an entity and scores visibility (0-100). It distinguishes from siblings by specifying AI-marketing audits, brand checks, and competitive monitoring as use cases, setting it apart from related tools like scan_competitor_ai_presence.

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

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

Description explicitly mentions use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains default model vs. BYO key for Anthropic. However, it does not explicitly state when not to use it or contrast with alternatives like scan_competitor_ai_presence.

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=false. Description adds that it routes to 3,567 tools across 828 sources and returns structured answers with pipeworx:// citation URIs, providing useful behavioral 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?

Every sentence adds value: preference statement, domain list, routing explanation, usage triggers, and examples. Front-loaded with key guidance. No wasted words despite length.

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

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

Given the tool's complexity as a router to many sources, the description covers when to use, what it does, and output format. Lacks details on failure modes or limitations, but overall sufficient for an agent to invoke correctly.

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

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

Schema coverage is 100% with detailed descriptions for each alias. Description adds context on what kinds of questions to ask and provides examples, enriching the understanding beyond the schema's bare parameter definitions.

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 answers factual questions using authoritative structured data with citations, and explicitly positions itself as a preferred alternative to web search. It lists numerous domains and examples, distinguishing it from sibling tools like search_preprints or validate_claim.

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

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

Strongly advises to prefer over web search and provides explicit triggers: factual questions about real-world entities, events, numbers. Includes examples like 'current US unemployment rate'. Lacks explicit when-not-to-use scenarios but the preference is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. Description adds beyond: return format with refusal reasons, extra LLM call cost. 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?

Description is front-loaded with purpose, then explains behavior, return format, use cases, and trade-offs in a structured way. Every sentence is informative 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 complexity (grounded retrieval from 3567 tools), description covers when to use, return fields, refusal reasons, and cost trade-off. No output schema but return format is described.

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 parameters are aliases for 'question' with description 'Your question in natural language'. Description does not add meaning beyond schema, but 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 is a 'hallucination-resistant answer mode for high-stakes reads' and specifies it extracts answers using only tool results. It distinguishes itself from sibling 'ask_pipeworx' by emphasizing grounded extraction and refusal reasons.

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: 'whenever an answer will be quoted, cited, or acted on' and when not: 'prefer ask_pipeworx for casual lookups'. Lists specific high-stakes scenarios like financial verdicts, legal claims, etc.

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

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

The description extensively details behavioral traits beyond annotations: market resolution, classification, parallel fan-out to data packs, response shapes (market, analysis, evidence), safety mechanisms (low-confidence handling, closed markets, wide spread warnings), and resolver contract. This far exceeds the annotated hints (readOnly, openWorld, idempotent) and provides critical context for correct invocation.

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

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

The description is long and detailed, which is warranted for the tool's complexity, but it lacks structural elements like bullet points or clear sections. Some content (e.g., extensive fan-out examples) could be reorganized for easier scanning. While every sentence adds value, the density reduces readability.

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 3 parameters, no output schema, and varied behavior, the description is remarkably complete. It covers input specifications, processing logic, response shapes with field-level detail, error states (low_confidence_match, market_closed_or_inactive), and actionable advice (inspect market_match_confidence). No significant gaps are apparent.

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

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

Schema description coverage is 100% for all three parameters, and the description adds significant meaning beyond schema definitions. It explains acceptable formats for the market parameter (slug, URL, question text), the behavior of depth (quick vs thorough), and the nuance of include_raw (response size control). This enriches the agent's understanding of parameter usage.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb (research), resource (Polymarket bet), and action (pulling data). It effectively distinguishes from sibling tools such as ask_pipeworx or polymarket_edges by focusing on a single bet with comprehensive data gathering.

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 usage scenarios: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also includes contextual examples and safety notes (low-confidence resolutions). However, it does not explicitly state when not to use the tool, missing a small but valuable exclusion guideline.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. Description adds extensive context: handles off-calendar fiscal years, returns sorted by primary metric, provides citation URIs, and states it replaces 8-15 sequential lookups. 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 information-dense and front-loaded with trigger phrases. However, it could be slightly more structured (e.g., bullet points) to improve scanability. Still, 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?

No output schema exists, but description explains return format (paired data + citation URIs, sorted by primary metric). It covers all necessary context: when to use, how parameters work, data sources, and behavioral details. 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 has 100% coverage but description adds meaningful detail: explains that 'values' should be tickers/CIKs for companies and drug names for drugs, and describes the constraints (2-5 items). This clarifies parameter semantics beyond schema alone.

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 explicitly states the tool compares 2-5 entities (companies or drugs) in a single parallel call, with trigger phrases like 'compare X and Y' and 'head to head'. It clearly distinguishes from sequential lookups, making 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?

Explicit guidance says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities'. It also differentiates between company and drug types, providing criteria for each (e.g., 'type="company" pulls LATEST 10-K...').

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, making this a safe, idempotent read operation. The description adds value by stating it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and that results are ready to call directly, providing behavioral 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?

The description is around six sentences, starting with a clear purpose statement. It is efficient, listing example domains and emphasizing the tool's role as a first-step discovery tool. Some redundancy exists (e.g., listing aliases already in schema), but overall it 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?

Given the tool's complexity as a meta-tool and the absence of an output schema, the description sufficiently explains the return value: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly.' This 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?

Schema description coverage is 100%, so the schema fully documents all 6 parameters. The description mentions aliases (e.g., 'Accepts task, q, description, search as aliases') and provides domain examples, but these are already implied by the schema descriptions. Baseline of 3 is appropriate as the description adds marginal 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 uses a specific verb+resource combination: 'Find tools by describing the data or task.' It clearly distinguishes itself from sibling tools by being a meta-discovery tool, explicitly stating 'Call this FIRST when you have many tools available and want to see the option set.'

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

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

The description provides explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist for: [list of domains]' and suggests calling it first. While it doesn't list when not to use, the context of being a discovery tool makes usage clear.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds that it fans out across multiple sources, soft-fails for patents due to USPTO API sunset, and returns specific fields. Could mention rate limits or latency.

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 example queries, purpose, usage guidance, return details, and input constraints. Every sentence adds value, but could be slightly more concise by reducing repeated example pattern.

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 (multiple data sources, fallbacks), description covers main return fields, data sources, and input limitations. Lacks output schema but describes returns adequately. Might need more detail on news count or pagination.

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 for both parameters. Description adds context: example values ('AAPL', '0000320193'), restriction to ticker/CIK, and note to use resolve_entity for names. Adds value beyond schema.

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

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

The description clearly states the tool provides a 'full cross-source profile of a US public company in ONE parallel call' and includes example queries like 'Tell me about X' and 'company profile for Microsoft'. It distinguishes itself from chaining single-pack lookups.

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

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

Explicitly states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' for holistic views and specifies when not to use: 'names not supported (use resolve_entity first if you only have a name)'. Clear guidance on 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 destructiveHint=true and idempotentHint=true. Description adds 'clear sensitive data' as behavioral context but does not disclose effects like irreversibility or handling of non-existent keys. Adds moderate value beyond annotations.

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

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

Two sentences, front-loaded with the action, followed by use cases and related tools. Every sentence is essential; 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?

For a simple one-parameter delete tool with good annotations, the description adequately covers action, usage, and relationships. Minor missing detail: behavior on non-existent key, but annotations hint at idempotency.

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 description 'Memory key to delete.' The tool description only repeats 'by key' and adds no new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the action 'Delete a previously stored memory by key.' It identifies the resource ('memory') and the operation ('delete'). It pairs with siblings 'remember' and 'recall', distinguishing this as the deletion 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 explicitly says when to use: 'when context is stale, the task is done, or you want to clear sensitive data.' It also mentions pairing with 'remember and recall,' offering context on alternatives.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral details: it fetches the page, extracts title/description/key links, and outputs a markdown text blob. This provides a complete picture of the tool's behavior beyond the annotations.

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

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

The description is two sentences long, front-loading the main action and resource, then adding detail and usage scenarios. Every sentence adds value without repetition or unnecessary 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?

Given the simplicity of the tool (2 params, no output schema), the description is fully complete. It explains the output format, the extraction process, and the intended use cases, leaving no gaps for an AI agent to misunderstand.

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

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

The input schema has 100% description coverage, so the baseline is 3. The description does not add significant new meaning to the parameters beyond what the schema provides; it reiterates the purpose of the URL and mentions max_links but no additional semantics.

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

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

The description uses a specific verb 'Generate' and resource 'llms.txt file', clearly stating the tool's function. It distinguishes from sibling tools by targeting AI crawler indexing, which is unique among the listed siblings.

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

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

The description lists three specific use cases (getting a client's site indexed, drafting for own project, auditing competitor) providing clear context for when to use the tool. However, it does not explicitly mention when not to use it or suggest alternative tools, which would elevate it to a score of 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds value by listing returned fields (title, description, category, dates, tags, public flag) but does not elaborate on other 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 a single, efficient sentence with no wasted words. It front-loads the key action and resource, then lists returned fields succinctly.

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

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

For a simple read-only tool with one parameter and no output schema, the description provides all necessary information: what it does, how to identify the project, and what data is returned. It is fully adequate for an AI 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% and the schema describes the 'id' parameter. The description adds an example ('abc12') and context about its meaning ('OSF node id'), going beyond the schema's minimal description.

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 verb 'fetch', the resource 'metadata for a single public research project (node)', and the identifier format 'OSF id (e.g. "abc12")'. It lists returned fields, making it specific and distinguishable from sibling search 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 implies usage when you have a specific OSF ID and need full metadata. It does not explicitly mention when not to use or name alternatives, but the context of sibling tools like 'search_projects' provides implicit guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description doesn't need to repeat safety traits. However, it adds value by specifying the fields returned and noting that include_inactive controls whether cancelled subscriptions appear. 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 two sentences, front-loaded with purpose and key details. Every sentence is useful: the first states what it does and what is returned, the second gives usage guidance. 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?

For a simple list tool with one optional parameter and no output schema, the description is complete. It covers purpose, returned fields, usage guidance, and the optional parameter's effect. No gaps remain for effective 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?

With 100% schema description coverage, the baseline is 3. The description adds context beyond the schema: it clarifies that the default list shows only active subscriptions (implied by 'active') and that the include_inactive parameter can be used to see cancelled ones. This helps the agent understand the parameter's effect.

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 lists the caller's active subscriptions, explicitly distinguishes itself from sibling tools like subscribe and unsubscribe, and specifies the returned fields (id, type, params, etc.). This provides a specific verb and resource with unique scope.

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: use to review monitoring before adding more subscriptions or to find an id to cancel. This tells the agent when to use this tool vs alternatives like subscribe or unsubscribe.

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 (which are all false), the description discloses key behaviors: rate-limited to 5 per identifier per day, free, doesn't count against quota, and that team reads digests daily. This provides valuable context for tool invocation decisions.

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

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

The description is five sentences, front-loaded with the core purpose, and structured efficiently. Every sentence adds value 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 no output schema, the description fully addresses input parameters, usage guidelines, behavioral constraints (rate limit, quota), and context. No gaps remain for an agent to effectively use the tool.

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

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

Schema coverage is 100% with all parameters described. The description adds value by explaining the meaning of each 'type' enum value and specifying a 2000-char limit for 'message', not present in schema. However, the schema already provides adequate descriptions.

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

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

The description clearly states the tool's purpose: to tell the Pipeworx team about broken, missing, or needed things, enumerating specific categories (bug, feature, data_gap, praise). This distinguishes it from sibling tools which serve other functions like asking questions or discovering 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 describes when to use the tool (e.g., wrong data, missing tool, praise) and what not to do (don't paste end-user prompt). Includes details about team reading frequency and roadmap impact. However, it does not explicitly mention when not to use it compared to alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds caching behavior (5min-1h), data source (CF analytics engine), and privacy statement (no PII), which provides useful behavioral context beyond structured fields.

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

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

The description is front-loaded with the core function and uses a numeric list for use cases. While packed with information, it remains clear and avoids redundancy. Minor improvement could tighten phrasing.

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

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

For a simple, single-parameter tool without output schema, the description fully explains return values (top tools, top packs, volume), caching, use cases, and data provenance. Nothing essential is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the trade-off between shorter windows (hot right now) and longer windows (steady-state), which goes beyond the enum values and baseline description.

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

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

The description starts with a clear verb ('Returns') and resource ('top tools, top packs, and total call volume') and distinguishes itself from siblings by focusing on trending usage data from other agents, not direct queries or discovery.

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?

Three explicit use cases are provided (hot data sources, canonical tool confirmation, alignment check). No explicit when-not-to-use, but the context signals and sibling list imply alternatives. Slight gap in exclusion guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive nature. The description adds extensive behavioral context: the algorithm steps (monotonicity checks, partition sums), failure conditions, internal filtering (Jaccard similarity, placeholder detection), and the response structure. 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 thorough and well-structured, starting with a requirement line, then detailing modes and filters. While lengthy, every sentence adds essential information for a complex tool. Could be slightly more concise by grouping some filter details, but overall it earns its length.

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

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

Given the lack of an output schema, the description fully explains the response structure (opportunities array with gap_pp, suggested_trade, etc.; partition check object). It covers all behavioral aspects: both modes, internal checks, and edge cases (e.g., placeholder fraction >20% returns null). For a tool this complex, 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%, but the description significantly enriches meaning beyond the schema: it explains the two modes, provides example inputs like 'fed-decision-may-2026', describes the internal processing triggered by each parameter, and clarifies the difference between event and topic usage.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks, distinguishing between single-event and cross-event modes. It contrasts with siblings like polymarket_edges and polymarket_kalshi_spread by its specific focus on arbitrage detection.

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 warns that no-args calls fail. It recommends the `event` mode for specific markets and explains that cross-event mode catches patterns missed by single-event mode, providing concrete examples. It also details internal filters like semantic anchor and partition filter.

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

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

The description goes well beyond annotations by detailing the three model families (crypto_price, news_momentum, partition_overround, concentrated_longshot), how edge is calculated after slippage, Kelly fractions, diagnostics structure, and caching ('Cached 1h at the KV level'). No contradictions with annotations (readOnlyHint, openWorldHint, idempotentHint). This provides comprehensive behavioral insight.

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 detailed and informative, but excessively long (over 500 words). It has a logical structure with segments highlighted, but many sentences could be trimmed or combined without losing essential information. The verbosity 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?

Given the tool's complexity (9 parameters, no output schema), the description is remarkably complete. It explains the response top-level, diagnostics, caching, and model families. An AI agent can fully understand when to call and how to interpret results.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra context beyond the schema, e.g., explaining why min_kelly does not filter partitions and how min_partition_leg_kelly works as an alternative. This additional semantic value merits a 4.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It is specific about scanning and returning opportunities, and the 'Built for what should I bet on today' clarifies its use case. While not explicitly differentiating from siblings like polymorpharket_arbitrage, the purpose is distinct enough for an agent to distinguish.

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

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

The description provides clear usage context: 'Built for what should I bet on today — agents discover opportunities without paging hundreds of markets.' It also describes knobs like min_liquidity and max_spread_pp for filtering tradeable edges. However, it does not explicitly state when not to use this tool or mention alternatives for different scenarios, which would improve the score.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, indicating safe read-only operations. The description adds substantial behavioral context: it explains how the spread is calculated (Kalshi minus Polymarket), describes safety fields like compatibility_warning with specific triggers (non-equivalent bet shapes, semantically unrelated events), temporal alignment checks, and skipped_cross_type/subtype counters. This goes well beyond what annotations provide.

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

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

The description is relatively long but highly information-dense, with every sentence providing necessary detail. It is well-structured with clear sections (mode, response, safety fields). Minor redundancy could be trimmed (e.g., repeating 'pre-mapped' multiple times), but overall it is appropriately sized for 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?

Given no output schema, the description thoroughly covers the response structure: leg-by-leg prices, matched spread with top_spreads_pp, and safety fields including compatibility_warning conditions and temporal_alignment. It also explains the meaning of skipped_cross_type/subtype counters. The tool is complex with multiple edge cases, and the description handles them comprehensively.

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 three parameters have descriptions). The description adds meaning by explaining how topic maps to events, how explicit tickers override topic, and provides examples (e.g., 'KXFED-26OCT' for kalshi_event_ticker). It clarifies parameter interactions and usage context, adding value beyond the schema alone.

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 computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It specifies two modes (topic shortcuts and explicit tickers) and details what the response contains. This distinguishes it from sibling tools like polymarket_arbitrage and polymarket_edges, which focus on single-venue or different cross-venue analysis.

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

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

The description explains when to use each mode (topic vs explicit) and warns that pre-mapped topics often return compatibility warnings, advising they are not necessarily tradeable. It provides context on when spreads are meaningful (e.g., temporal alignment). However, it does not explicitly state when not to use this tool (e.g., if only one venue's data is needed), leaving some room for 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 already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds context on scoping (identifier-based) and pairing with other tools, but does not contradict annotations.

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

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

Two concise sentences, no fluff. Every sentence adds value: first states function, second provides use cases and context.

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 low complexity (1 optional param, no output schema, thorough annotations), the description is complete. Covers primary use, variations, scoping, and relationships with sibling tools.

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. Description explains the behavior when key is omitted (list all keys), adding value beyond the schema's property description.

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

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

The description clearly states the tool's function: retrieve a saved value or list all keys. It distinguishes itself from siblings 'remember' and 'forget' by specifying the pairing, and from listing vs. specific retrieval.

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

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

Provides explicit use cases (user's target ticker, address, research notes) and explains when to omit the key argument. Could be strengthened by stating when not to use, but context from siblings 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?

Description adds behavioral context beyond annotations: mentions polling is safe, describes return fields (source, citation_uri, raw payload), and notes external endpoint. 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?

Concise (~100 words), front-loaded with purpose, each sentence adds meaningful detail without redundancy. 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?

Covers tool purpose, return data, filtering, mark_read behavior, and alternative access. Limit parameter not mentioned in description but covered in schema. Slightly incomplete on unread_only but overall comprehensive.

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

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

Schema coverage is 100%, but description adds value with examples (type 'sec_8k') and explains mark_read effect on subsequent calls, enhancing understanding beyond 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?

Description clearly states 'Pull fired events from your subscription feed' with specific verb and resource, and distinguishes from siblings like list_subscriptions by focusing on event retrieval.

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 context on filtering (type, since), mark_read behavior, and alternative REST endpoint for scripts/dashboards. Lacks explicit when-not-to-use or comparison to other tools but sufficient for understanding usage.

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

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

Discloses fan-out to multiple sources, fallback mechanism (GDELT→GNews), USPTO soft-fail, and return format (grouped changes, total count, URIs). Annotations already indicate readOnly, openWorld, idempotent; description adds rich behavioral context 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?

Information-dense but slightly verbose with multiple query examples. Could trim examples while preserving clarity. Well-organized, 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?

Given multi-source complexity, no output schema, and 3 parameters, the description covers sources, fallback, date formats, return structure, and sibling differentiation. Fully adequate 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?

Input schema covers all 3 parameters (100% coverage). Description adds: 'since' accepts ISO or relative shorthand with typical values, 'value' can be ticker or CIK, 'type' only supports company. Adds practical guidance 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 provides a 'change feed for a company in the last N days/weeks/months in ONE parallel call' and lists query paraphrases. It distinguishes from sibling entity_profile, which is for static profiles.

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

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

Explicitly says 'Use entity_profile instead when you want the static profile...' providing clear alternative for different use cases. Could be stronger with 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 idempotentHint true and destructiveHint false. The description adds valuable behavioral context: scoping by identifier, persistent memory for authenticated users, 24-hour retention for anonymous sessions, and pairing with recall/forget. 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 four sentences, well-structured: first sentence states purpose, second gives usage guidance, third adds behavioral details, fourth mentions complementary tools. No unnecessary words.

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

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

Given no output schema and a write operation, the description adequately covers purpose, usage, behavior, and storage details (persistence, scope). It is complete for an agent to decide to use this 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% with descriptions for key and value. The description adds context (key-value pair scoped by identifier) and examples, providing additional 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 saves data for later reuse across conversations or sessions, provides examples of what to store (resolved ticker, target address, user preference, research subject), and distinguishes from siblings like recall and forget.

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

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

It explicitly says when to use ('when you discover something worth carrying forward') and mentions pairing with recall and forget. It does not explicitly state when not to use, but the guidance is clear enough.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds that it cascades through several lookup endpoints internally and replaces 2-3 manual lookups, plus details on return fields (ticker, CIK, citation URIs). 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?

Single paragraph with clear structure: example calls, usage instruction, supported types detailed. Every sentence adds value; no fluff.

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

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

No output schema, so description must cover return values—and it does comprehensively for both types. Also explains input variations, auto-disambiguation, and the citation URIs. Complete for a lookup tool with moderate 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 covers 100% but description provides rich detail beyond schema: for each type, it enumerates output fields and citation URIs, and explains input formats (e.g., ticker, CIK, or name for company). This adds significant semantic 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?

Clearly states it resolves names to IDs for multiple types (company, drug) with specific examples. Distinguishes from sibling tools like search_preprints or ask_pipeworx by providing a specific use case and directive 'Use FIRST whenever you have a name but need an ID.'

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 ('Use FIRST whenever you have a name but need an ID') and lists supported types. Lacks explicit 'when not to use' but context of siblings and directive imply it's the go-to for entity resolution.

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

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

The description goes beyond annotations by detailing the internal behavior (probes each entity with ai_visibility_check, ranks by score) and output shape (ranked list with score, confidence, signal density per entity). It also notes that the first entity in the array is treated as the subject. No contradiction with annotations (readOnlyHint, idempotentHint are 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 concise at two sentences plus an example, with no redundant information. The main purpose is front-loaded, and each sentence adds meaningful detail. It is well-structured for quick comprehension.

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

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

Given the complexity of comparing multiple entities and the absence of an output schema, the description adequately explains the output format (ranked list with score, confidence, signal density). It also mentions the internal dependency on ai_visibility_check, providing sufficient context for an AI agent to understand the tool's function 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% with all parameters having descriptions. The description adds marginal value by clarifying that the first entity is treated as the subject and that context is for disambiguation. This is a typical case where the schema already does the heavy lifting, so a baseline of 3 is appropriate.

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

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

The description clearly states the action (compare, probe, rank, surface), the resource (AI visibility across entities), and distinguishes it from siblings by explaining it aggregates results from ai_visibility_check and provides a side-by-side comparison. A practical example ('does Claude know about us as well as our competitors?') reinforces 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?

The description provides clear usage context for competitive AI-marketing audits with an illustrative question. It implicitly suggests that for single-entity checks one would use the sibling tool ai_visibility_check, but does not explicitly state when not to use this tool or mention alternative selection criteria for siblings.

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

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

The description adds valuable behavioral context beyond annotations, including partial failure handling, timing details (bundlephobia first measurement 5-30s), and output structure for failures (sources_failed). Annotations already indicate read-only, idempotent, non-destructive properties; the description supplements without contradiction.

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

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

The description is moderately long but each sentence adds unique value: purpose, usage triggers, return fields, ecosystem scope, and failure handling. The structure is logical and front-loaded with the primary purpose. Minor redundancy could be trimmed but overall efficient.

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 thoroughly explains the return payload (summary block fields, per-advisory detail, links, alternative versions) and covers edge cases like partial failures and ecosystem limitations. This fully compensates for the lack of an output schema.

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

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

Input schema has 100% coverage with clear descriptions for both parameters. The description adds context that the package field targets npm packages and that version defaults to latest, and explains the composite nature of the call. This goes beyond the schema, justifying a score above baseline.

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

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

The description clearly defines the tool as a composite check for adding npm packages to a project, using specific verbs like 'scan' and specifying the resources (npm package) and data sources (deps.dev, bundlephobia). It distinguishes from sibling tools by its composite nature and unique output.

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 (e.g., when an agent asks about safety, popularity, size, or cost of adding a package) and provides usage examples. It also notes the current NPM-only scope and directs users to other deps.dev endpoints for other ecosystems, offering 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 declare readOnlyHint, idempotentHint, and destructiveHint, so the description adds useful behavioral context: it lists the return fields (compensating for the lack of output schema) and mentions typical slowness. This provides valuable beyond-annotation information.

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?

Extremely concise and front-loaded: two sentences that convey purpose, source, return fields, and usage consideration without any redundant information. Every word adds value.

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 low complexity and full schema coverage, the description is quite complete. It specifies the return fields (no output schema exists), notes keyless access, and warns about slowness. It could mention ordering or pagination, but it covers essential information for an API call.

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 are adequately described in the schema. The description does not add additional semantic details beyond the schema, so a baseline score of 3 is appropriate.

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

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

Clearly states it searches public preprints by title, identifies the source (OSF), and lists the returned fields. This distinguishes it from sibling tools, none of which specifically target preprints.

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 context on when to use (searching public preprints by title), notes keyless public access, and warns about API slowness. However, it does not explicitly state when not to use or suggest alternatives, but this is mitigated by its unique scope 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, non-destructive, and open world. The description adds value by stating 'Keyless public data' (no auth needed) and 'API can be slow' (performance trait), which annotations do not cover.

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 concise sentences: first specifies action and return fields, second provides key usage context. 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?

Includes return fields and performance caveat. With no output schema, the description reasonably covers what the agent needs. Could mention pagination or rate limits but still 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%, so baseline is 3. The description mentions searching by title (matches 'query' param) but adds no extra meaning beyond schema descriptions for limit and query.

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

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

The description clearly states the tool searches for public research projects (nodes) by title, specifying the resource (OSF projects) and action. It differentiates from sibling 'search_preprints' by targeting projects.

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 notes 'Keyless public data' indicating public access and warns of slow API. It implicitly contrasts with sibling 'search_preprints' but lacks explicit when-not or alternative 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 internal mechanism (BGE-base-en embeddings + cosine over 500-char windows), limits (200K chars with truncation flag), and return format (offsets, scores). Adds value beyond annotations (readOnly, idempotent) with these details.

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 dense paragraph with no wasted words. Front-loaded purpose, then details. Efficient and informative.

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

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

Covers purpose, use case, technical details, limits, and relationship to sibling tool. Despite no output schema, describes return format 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?

Schema coverage is 100%, so baseline is 3. Description adds examples for query and default for limit, but no new semantic meaning beyond what schema already provides.

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

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

The description clearly states it performs semantic search inside a fetched record, specifying the use case (when record is too big for prompt) and distinguishing from siblings like ask_pipeworx_grounded.

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

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

Explicitly says 'use when the record is too big to cram into the prompt' and pairs with ask_pipeworx_grounded, providing clear context. Lacks explicit when-not-to-use, but sufficient for guidance.

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

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

The description indicates a mutable operation (creating a subscription), but annotations set readOnlyHint: true, which contradicts the description. The contradiction is flagged.

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 the main purpose upfront, and each sentence adds necessary context 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?

No output schema, but the description states 'Returns the new subscription id.' It covers OAuth requirements, delivery options, and limits, making it complete for a creation tool.

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

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

With 100% schema coverage, baseline is 3. The description adds value by explaining type with examples, items defaults, and delivery validation/limits.

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.', which is a specific verb+resource. It distinguishes from siblings like list_subscriptions and unsubscribe.

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 the requirement for a Pipeworx OAuth account and that anonymous/BYO cannot persist subscriptions, but does not explicitly compare with sibling tools for when to use 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?

The description contradicts the 'readOnlyHint: true' annotation by stating the tool cancels a subscription, which is a mutation. While it truthfully discloses ownership enforcement and deactivation, the annotation conflict undermines trust and transparency.

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

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

Two sentences with no wasted words, front-loaded with the action. Every sentence contributes value: action, ownership rule, and deactivation effect.

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

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

The description covers the core purpose and an important behavioral nuance (deactivation vs deletion), but the annotation contradiction leaves incomplete context. Also, no mention of return value or idempotency, though hints exist in 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?

The input schema already fully describes the 'id' parameter with a UUID note. The tool description adds no new semantic meaning beyond 'by id', so it meets the baseline for 100% schema coverage.

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

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

The description clearly states the action ('Cancel a subscription by id'), specifies the resource (subscription), and distinguishes from siblings like 'subscribe' and 'list_subscriptions' by mentioning ownership enforcement and deactivation behavior.

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

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

The description notes that ownership is enforced (only own subscriptions can be canceled) and explains the deactivation effect, helping the agent decide when to use this tool. However, it lacks explicit exclusions like 'do not use for deleting' or alternatives for different scenarios.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, indicating safe deterministic reads. The description adds value by detailing the return format (verdict options, structured form, citation, percent delta) and data source (SEC EDGAR + XBRL), providing behavioral 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?

The description is well-structured, front-loaded with trigger phrases, and every sentence adds value covering purpose, usage, scope, and output. It is appropriately sized 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 complexity, the description provides complete context: purpose, usage, scope, output format, data source, and efficiency benefits. No output schema exists, so the description adequately covers return values.

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

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

Schema coverage is 100% and the schema already describes the 'claim' parameter with an example. The description adds example claim formats but does not significantly improve semantic understanding 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 starts with trigger phrases and clearly states it is for natural-language claim verification against authoritative sources. It specifies the scope (company-financial claims for public US companies) and distinguishes it from general-purpose tools by noting it replaces 4-6 sequential calls.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and provides example trigger phrases. It does not explicitly state when not to use it, but the scope (company-financial claims) implies limitations.

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