Orcid

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

Annotations already indicate safe read-only, idempotent, non-destructive behavior. The description adds valuable context: per-model return structure, the BYO key and direct billing arrangement for Anthropic, and the scoring range (0-100). No contradictions with annotations.

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

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

Four sentences, all essential. Front-loaded with purpose, then model options, return contract, and use cases. No redundant phrases or filler. Perfectly sized for an agent to parse quickly.

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, no output schema, and moderate complexity, the description covers inputs, return format, and usage scenarios. It could add a note about error handling or rate limits, but annotations cover safety. Still, it's sufficient 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%, but the description adds meaning beyond schema labels. It clarifies the default model, the optional nature of models and _apiKey, and the role of context in disambiguation. This helps the agent understand parameter dependencies and typical 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 uses specific verbs ('probe', 'score') and clearly identifies the resource: LLMs + visibility scoring. It provides concrete use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) that distinguish it from generic 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 explains when to use the tool via listed use cases and provides model-specific guidance (default free model, Anthropic with API key). It lacks explicit 'when not to use' or comparison to siblings like scan_competitor_ai_presence, but still gives clear 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds behavioral details: routes to the right tool, fills arguments, returns structured answer with stable citation URIs. This enriches the agent's understanding beyond annotations without contradiction.

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

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

The description is relatively long but well-structured with clear prioritization, bullet points, and examples. Every sentence adds important context; no filler. The key guidance is front-loaded.

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

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

Given the vast scope of the tool (over 4,000 tools), the description is remarkably complete. It covers purpose, when to use, alternatives, examples, and expected output format (citations). No output schema is needed, and the description fully compensates.

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 each alias. Description adds value by explaining that the question should be in natural language and providing example queries. This helps the agent formulate effective inputs beyond what the schema alone conveys.

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 routes questions to thousands of tools for authoritative structured data, and distinguishes from siblings like ask_pipeworx_grounded and deep_research. Specific verb ('routes') and resource ('4,482 tools across 1129 verified sources') make 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 says to prefer this over web search for factual questions, provides many examples, and gives clear conditions when to use alternatives ('Step up only when needed...'). No ambiguity about when to invoke.

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, and non-destructive behavior. The description adds critical context: extra LLM call cost, explicit refusal reasons ('not_in_source', 'no_tool_match', etc.), and the guarantee of not inventing facts. This goes well 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 comprehensive yet well-structured: purpose first, followed by process, output format, and usage guidance. Every sentence adds value, with no fluff. Front-loaded with the core value proposition.

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 details the return format, including all possible refusal reasons. The complexity of the tool is fully addressed: cost trade-off, behavior, and examples are all covered. 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 all parameters being aliases for 'question'. The description mentions the aliases in the schema but adds no new semantic meaning beyond what the parameter descriptions already provide. 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 as a 'Hallucination-resistant answer mode for high-stakes reads.' It specifies the process of routing, fetching data, and extracting answers only from tool results, effectively distinguishing it from its sibling tool 'ask_pipeworx'.

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

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

Explicit guidance on when to use ('whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts') and when not to use (prefer 'ask_pipeworx' for casual lookups due to extra cost). Includes concrete examples like financial verdicts and medical 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?

The description goes far beyond annotations, detailing fan-out mechanisms, response shapes, resolver contract with confidence levels, parent event extractor, news fallback fields, safety shortcuts for low-confidence and closed markets, wide-spread indicators, and resolution-rule risk. All annotations are consistent (readOnlyHint, etc.).

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 (over 600 words) and includes extensive detail like fan-out examples and response shapes. While comprehensive, it lacks conciseness and structure, making it harder to parse quickly. It could be broken into sections.

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 including result.market, result.analysis, result.evidence, resolver contract fields, parent event extractor, news fields, and error scenarios. It covers all critical aspects for a complex tool with 3 parameters.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add extra meaning to individual parameters beyond what the schema already provides. It focuses on overall behavior rather than parameter details.

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 'Research' and the resource 'Polymarket bet'. It details the process: pulls Pipeworx data, resolves market, classifies, fans out, returns evidence. It distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on research for a specific 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?

Provides explicit use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. Also explains acceptable inputs (slug, URL, question). While it doesn't explicitly state when not to use, the context and examples are 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?

Description adds substantial behavior beyond annotations: for companies it explains pulling latest 10-K financial data with fiscal year handling, for drugs it details FAERS counts, FDA approvals, active trials. Also notes sorting by primary metric and 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?

Description is moderately detailed but every sentence adds value. It front-loads common query patterns and then explains behavior. Could be slightly trimmed but no wasteful 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?

Given no output schema, the description adequately explains return data (financial fields, FAERS counts, citation URIs) and sorting. Missing details on pagination or max result size, but max 5 entities makes that negligible. Fiscal year handling adds important context.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by explaining the meaning of each type (company vs drug), the data fields returned, and the format of values (tickers/CIKs for company, names for drug). Provides concrete examples like 'AAPL', 'MSFT', 'ozempic'.

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 does side-by-side comparison of 2-5 companies or drugs in one parallel call, with specific examples like 'X vs Y' and 'rank these companies'. It distinguishes from siblings by explicitly preferring over sequential single-entity lookups.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-entity lookups when comparing entities' and provides clear context for company vs drug types. It does not explicitly state when not to use, but the entity types and data sources are clearly scoped.

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, openWorldHint, idempotentHint, destructiveHint false. Description adds account requirement, pricing, parallel decomposition, findings packet with gaps, latency 15-60s. 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 ~200 words but each sentence adds value. Front-loaded with critical info (account, alternative). Could be slightly shorter but very efficient 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 complexity (2 params, 100% schema, no output schema), description covers auth, speed, scope, return format, limitations. Comprehensive and actionable.

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 100%. Description adds meaning: depth enum explained with numeric equivalents, question parameter described as natural language and broad. Adds significant 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's purpose: grounded multi-source research across structured data sources, not open-web search. It distinguishes well from siblings like ask_pipeworx and pipeworx_trending.

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 (broad/multi-part questions over structured data) and when not to (single lookup use ask_pipeworx, breaking news prefer ask_pipeworx). Also mentions 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=true, idempotentHint=true, destructiveHint=false. Description adds return behavior: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas... each result is ready to call directly, no second schema lookup needed.' 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?

Well-structured: purpose first, then usage context, then return value. No redundant sentences; every sentence adds value. Slightly long but appropriate given 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?

Fully covers purpose, usage, parameters (via schema and examples), and return behavior. No output schema but description explains what is returned. Parameter count 6, required 1, all described. Sufficient for a discovery 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 3. Description adds context about aliases for query parameter and includes examples, but does not significantly augment schema meanings beyond what is already documented.

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+resource: 'Find tools by describing the data or task.' Distinguishes from sibling tools like search and search_within by focusing on tool discovery rather than data querying.

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 you need to browse, search, look up, or discover what tools exist for...' and instructs 'Call this FIRST when you have many tools.' Provides domain examples. Lacks explicit when-not-to-use but context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds no behavioral context beyond the annotations. For example, it does not disclose that the tool is read-only or non-destructive, nor does it mention 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 extremely short but lacks substance. It is not concise—it is under-specified. A concise description efficiently conveys necessary information; this one does not.

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 (one parameter, output schema exists), the description should clarify what the tool returns or what 'education summary' means. It is incomplete and does not enable an agent to make an informed decision.

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 0% schema description coverage, the description must compensate by explaining the parameter 'orcid_id'. It does not provide any meaning, format, or example beyond what is in the schema. This is a critical gap.

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 'Education summary.' is almost a tautology with the title 'Education'. It does not specify a clear verb/action or what the tool does (e.g., retrieve, display). It is vague and fails to distinguish from siblings like 'employment' or 'work'.

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

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

No usage guidelines are provided. The description gives no indication of when to use this tool versus alternatives such as 'entity_profile' or 'employment'. No exclusions or prerequisites are 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 readOnlyHint=true, destructiveHint=false. Description adds no behavioral context beyond what annotations provide, missing opportunity to explain other traits like data scope or return 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 extremely short (two words) but lacks structure and substantive content. It is under-specified rather than concise.

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

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

Given the tool has one parameter, annotations, and an output schema, the description is completely inadequate. It does not explain what entity's employment, the output format, or any usage context.

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

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

Schema coverage is 0%. The description does not mention the single parameter 'orcid_id', its purpose, format, or usage. Despite only one parameter, the description fails to add any 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 'Employment summary' is a noun phrase, not a verb+resource. It vaguely indicates the tool deals with employment data but lacks a clear action or differentiation from siblings like 'education' or 'work'.

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

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

No guidance on when to use this tool versus alternatives. With many sibling tools covering similar topics, the description provides no context or 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?

Adds significant context beyond readOnlyHint/openWorldHint: describes fanning across multiple sources, details each return field, flags USPTO sunset soft-fail. 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?

Informative and front-loaded with examples, but slightly long. Every sentence earns its place, but could be slightly more 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?

Comprehensive for a 2-param tool with no output schema: covers return fields, sources, edge cases (USPTO sunset, name handling), and parallel execution.

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

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

Despite high schema coverage (100%), description adds crucial semantics: value can be ticker or zero-padded CIK, names not supported; type enum currently only '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?

Clearly states it provides a full cross-source profile of a US public company in one parallel call, with example queries. Distinguishes from sibling tools by advertising preference over 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 says when to use (holistic 'tell me about X' queries) and when not (names not supported; directs to resolve_entity). Also states to always prefer over chaining.

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, so the destructive nature is clear. The description confirms deletion but adds no further behavioral context beyond what annotations provide. 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?

Two sentences, front-loaded with purpose, followed by usage guidelines. No unnecessary information, every sentence is valuable.

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

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

For a simple single-parameter tool with no output schema, the description covers what the tool does, when to use, and related tools. No gaps given the tool's simplicity.

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

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

Schema coverage is 100% with parameter 'key' described as 'Memory key to delete'. The tool description does not add additional semantic meaning beyond the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states 'Delete a previously stored memory by key', specifying the verb (delete) and resource (memory identified by key). It distinguishes from sibling tools like remember and recall by focusing on deletion.

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 lists when to use: when context is stale, task done, or to clear sensitive data. It also suggests pairing with remember and recall, providing clear alternatives and 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?

Annotations already indicate read-only, open-world, and idempotent behavior. The description adds value by explaining the process (fetches page, extracts title/description/key links, emits markdown) and output format (text blob ready for site-root/llms.txt). 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 a concise single paragraph with three sentences, each adding value: main action/benefit, process/output, use cases. No superfluous words, front-loaded with the core purpose.

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

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

For a simple tool with two parameters, no output schema, and informative annotations, the description fully covers purpose, behavior, output, and usage scenarios. It leaves no ambiguity about what the tool does or how to use it.

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 parameter descriptions. The description goes beyond by providing an example for 'url' (full URL or landing page) and stating default (25) and max (50) for 'max_links'. This adds useful context 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?

The description clearly states it generates a production-ready llms.txt file for any URL, specifying the verb 'generate' and resource 'llms.txt'. It also names specific AI crawlers (ChatGPT, Claude, Perplexity) and provides use cases, making it distinct from sibling tools that focus on visibility checks, searches, or entity 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?

The description explicitly lists scenarios where the tool is useful (indexing a client's site, drafting own project, auditing competitor crawling). While this provides clear context, it lacks explicit exclusions or when not to use, which would elevate to a 5.

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

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

Annotations already provide readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. The description adds value by specifying the default behavior (active only) and listing returned fields, which aids in understanding the response structure.

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

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

Two sentences cover what it does and when to use it, without any redundant or extraneous information. Efficient and front-loaded.

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

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

With no output schema, the description lists the return fields, which is essential. It could elaborate on ambiguous fields like 'params', but overall it provides sufficient context for the tool's usage.

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

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

The input schema has 1 parameter with full description coverage. The tool description restates the default (active) but does not add new semantic details 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 'List the caller's active subscriptions' with a specific verb and resource, and lists the return fields. It differentiates from siblings 'subscribe' and 'unsubscribe' by indicating retrieval vs. creation/deletion.

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 concrete use cases: 'review what you're monitoring before adding more' and 'find an id to cancel'. It implies when to use, but does not explicitly exclude alternative approaches or mention when not to use, which would be helpful.

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?

Disclosures beyond annotations include rate limits (5 per identifier per day), free usage (no quota consumption), and signal processing frequency. Annotations are all false, so 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?

Concise (~100 words), front-loaded with purpose, then use cases, then writer guidance, then team workflow and limits. Every sentence earns its place with 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?

Given the tool's simplicity, the description covers all necessary aspects: purpose, usage, behavioral constraints, and parameter semantics. No output schema exists, so return values need not be explained.

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?

Adds meaning beyond the full schema coverage: explains feedback categorization, emphasizes specificity, advises on length (1-2 sentences, 2000 max), and warns against pasting user prompts.

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: sending feedback about Pipeworx tools, including specific categories (bug, feature, data_gap, praise). It uses a clear verb-resource structure and distinguishes itself from sibling tools by being the only feedback 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?

Provides explicit guidance on when to use: for bugs, features, data gaps, praise. Also instructs on what not to do (avoid pasting user prompts) and mentions developer roadmap impact. No sibling tool serves the same purpose.

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 readOnly, idempotent, and non-destructive hints. The description adds value by explaining the data source (CF analytics-engine), privacy (no PII), and caching behavior (5min-1h). 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 a clear lead sentence, then use cases, and technical details. Every sentence adds value, though it could be slightly more concise.

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

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

For a simple read-only tool with no output schema, the description explains return values, use cases, data source, caching, and privacy. No gaps evident given 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 coverage is 100% with the 'window' parameter having an enum and description. The description adds some context about short vs long windows, but does not significantly supplement the schema's own documentation.

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

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

The description clearly states what the tool does: returns top tools, packs, and call volume over selectable windows. It distinguishes itself from sibling tools (like discover_tools or ask_pipeworx) by focusing on trending data derived from agent usage.

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 concrete use cases are listed, with window-length guidance. However, it does not explicitly state when NOT to use the tool or what alternatives might be better, which would elevate it to a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint as true and destructiveHint as false. The description adds extensive behavioral details: algorithms (monotonicity, partition-sum), semantic anchor (Jaccard similarity), partition filter (placeholder fraction), fill check against live depth, and response structure. 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 lengthy but well-structured and front-loaded with the requirement ('REQUIRES one of event or topic'). Every sentence serves a purpose, covering modes, algorithms, filters, response format, and references. Minor redundancy could be trimmed, but given the tool's complexity, it is appropriately detailed.

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

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

With no output schema, the description fully explains the response structure (opportunities[], partition_check), including fields like gap_pp, suggested_trade, reasoning, and fill check conditions. It covers all behaviors for both modes and edge cases (e.g., skipped_low_similarity, placeholders_filtered). The reference to polymarket_fill_risk ensures completeness for custom sizing.

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% (both event and topic described). The description significantly augments schema: clarifies that exactly one is required, gives example values ('fed-decision-may-2026'), explains mode behavior differences, and adds constraints like Jaccard similarity and placeholder filtering. This adds substantial 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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes two modes ('event' and 'topic') with specific use cases, and the verb 'find arbitrage opportunities' is precise. Sibling tools like polymarket_fill_risk and polymarket_edges are referenced, showing 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?

The description explicitly advises when to use each mode: 'event (recommended for a specific market)' and 'topic (for cross-event scanning)'. It warns that calling with no arguments fails, and provides conditional behavior like fill check and when not to trade. It also directs to polymarket_fill_risk for custom sizing, offering 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 indicate read-only, idempotent, non-destructive. The description adds extensive behavioral detail: caching (1h KV), response structure with diagnostics, model specifics (e.g., lognormal barrier, GDELT ratio, partition_overround with sport-specific α), and edge calculation including slippage and 24h-move warning. 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 long but front-loaded with the core purpose. Every sentence adds value given the tool's complexity (9 parameters, multiple model families). Could be slightly more concise, but is well-structured and efficient for the level of detail needed.

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 the response structure (by_segment, fed_candidates, diagnostics), caching behavior, edge components, and filter effects. For a tool of this complexity, the description is complete enough for an agent to understand inputs, outputs, and caveats.

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. The description adds substantial nuance beyond the schema, such as explaining when to adjust slippage_pp ('drop to 0 if you have a smarter fill model'), the relationship between min_kelly and min_partition_leg_kelly, and practical filter thresholds. While the baseline is 3 due to high coverage, the extra 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?

The description clearly states the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, specifically for 'what should I bet on today'. It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by focusing on edge detection across multiple model families.

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 positions the tool for discovering betting opportunities without manual paging, and provides guidance on tradeable-edge knobs like min_liquidity and max_spread_pp. However, it does not explicitly name alternatives or state when not to use this tool versus specific siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable context beyond annotations, such as the 60-day snapshot TTL, decay numbers from daily closes (not intraday), and snapshot 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 well-structured, starting with the core question and then detailing response format in a bullet-like style. It is detailed but efficient for the information density, though it could be slightly more concise.

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

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

With no output schema, the description fully explains the response structure (tracked[], expired[], snapshot_dates[]) and limits. It covers all necessary context for an agent to understand and use the tool correctly.

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

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

Schema description coverage is 100% for both parameters. The description repeats default values (days default 14, max 30; window default '1wk') but does not add new meaning beyond what the input 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: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and answers the question 'how long has this edge existed and is it shrinking?'. It distinguishes from sibling tools like polymarket_edges by focusing on historical trend 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 provides context by explaining that a fresh wide edge differs from a 3-week-old one, and mentions limits like 60-day snapshot TTL and gaps. However, it does not explicitly state when to use this tool versus alternatives or provide when-not-to-use guidance.

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

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

The description discloses extensive behavioral details beyond the annotations: it walks the ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and for baskets returns additional metrics like capture_ratio and profit_usd. It warns about risks such as forced directional risk and the danger of partial fills. There is no contradiction with annotations.

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

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

The description is lengthy but well-structured, starting with a summary, then requirements, then mode-specific details, and ending with usage context. Each sentence adds value, and the length is justified by the tool's complexity. Slightly less concise than ideal 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?

The description covers all aspects: input requirements, behavior in both modes, output fields, usage context with sibling tools, and risks. It does not require an output schema because it describes the return values. The tool is well-contextualized within the polymarket ecosystem.

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

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

The description adds significant context to the parameters beyond the input schema: it explains that 'side' has different defaults per mode, 'size_usd' is interpreted differently for buys vs sells and baskets, and that exactly one of 'market' or 'event' is required. This enriches the schema descriptions, which are already 100% covered.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It explicitly distinguishes between single-market and basket modes, and differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by specifying when to use this 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 explicit usage guidelines: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why it's necessary (theoretical overround not capturable on thin books, partial fills create directional risk) and specifies requirements (one of 'market' or 'event').

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

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

Annotations already indicate readOnly, idempotent, not destructive. The description adds extensive behavioral context: modes, response structure, safety fields (compatibility_warning, temporal_alignment), skipped counters, and caveats about real spreads being rare. 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 well-structured and front-loaded. Every sentence adds value given the complexity of the tool. Minor deduction for verbosity in the safety fields section, but still clear and 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 the tool's complexity (multiple venues, modes, edge cases) and lack of output schema, the description fully covers response fields, error conditions, and practical limitations. It is complete enough for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, but the description adds meaning: lists the 10 topic shortcuts, explains that explicit params override topic-mapped sides, and describes how the two modes interact. This goes beyond what the schema provides.

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

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

The description clearly states the tool computes cross-venue spread between Polymarket and Kalshi for the same resolving question, with two modes (topic shortcuts and explicit event tickers). It distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by its cross-venue focus.

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 (finding spread/arb between venues) and when not: compatibility_warning indicates non-equivalent bet shapes or temporal misalignment, making spreads meaningless. Also notes that most pre-mapped topics return warnings, managing expectations.

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 context about listing when key is omitted, scoping to identifier, and pairing with remember/forget. It does not contradict annotations and provides useful behavioral context beyond what annotations convey.

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

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

The description is four sentences, front-loaded with the core purpose. Every sentence adds value: functionality, use cases, scoping, and pairing. No redundant or extraneous information.

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

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

For a low-complexity tool (one optional param, no output schema, good annotations), the description is fully complete. It covers what it does, how to use it, when to use it, and how it relates to sibling 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 a single optional parameter. The description adds practical meaning by explaining that omitting key lists all saved keys and giving examples of stored values (e.g., user's ticker, address). This goes beyond the schema's basic description, providing richer semantic context.

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

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

The description clearly states it retrieves a saved value or lists all keys, distinguishing it from sibling tools like remember and forget by explicitly pairing with them. The verb 'retrieve' and 'list' are specific, and the resource ('saved via remember') is unambiguous.

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

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

The description provides concrete use cases (look up user's ticker, address, notes) and scoping info. It implies when to use (retrieve stored context) and pairs with remember/forget, but does not explicitly state when not to use or provide alternative tools beyond the pairing. Lacks explicit exclusion criteria.

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, but description describes mark_read parameter that flags events as read, which is a state mutation, contradicting the annotation.

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 at 3-4 sentences, front-loaded with purpose, each sentence adds essential information without 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?

Explains return fields and provides usage context, but lacks explanation of ordering and does not mention the unread_only parameter in description. With no output schema, more detail would help.

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?

Adds valuable context beyond schema descriptions, such as explaining that mark_read makes next call show only newer events and gives an example filter ('sec_8k'). Schema coverage is 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?

The description clearly states the tool pulls fired events from subscription feed and returns recent alerts with specific fields. However, no explicit differentiation from sibling tools like 'search' or '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 context for usage: polling works, and an alternative endpoint for scripts. But does not explicitly state when to avoid this tool or compare 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?

The description discloses behavioral details beyond annotations: fans out to multiple sources (SEC EDGAR, GDELT→GNews, USPTO), explains fallback and API sunset issues, and describes the return structure (changes[] grouped by source, total_changes count, citation URIs). Annotations already indicate readOnly, openWorld, idempotent, and non-destructive; 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 slightly long but every sentence provides useful context. It is front-loaded with common query patterns. Could be slightly more concise without losing clarity, 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?

Given the complexity (multiple data sources, fallback mechanisms, no output schema), the description is remarkably complete. It explains all sources, fallback behavior, parameter syntax, return structure, and known limitations (USPTO soft-fail). 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 coverage is 100%, so baseline is 3. The description adds value by explaining 'since' accepts ISO dates or relative shorthand (e.g., '7d', '30d'), 'value' supports ticker or CIK, and 'type' is currently limited to 'company'. This enriches the schema.

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

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

The description clearly states the tool provides a change feed for a company within a time window, using explicit verb-resource phrases like 'What's new with X' and 'latest on Y'. It distinguishes from the sibling tool 'entity_profile' which provides 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?

The description explicitly tells when to use this tool vs the sibling 'entity_profile', provides usage examples, and explains fallback logic (GDELT → GNews). It also suggests typical monitoring windows like '30d'.

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 that the record is 'full' and 'public', which provides context about scope and accessibility 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?

A single, front-loaded sentence that immediately conveys the core functionality. 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 the simple parameter set, existing annotations, and presence of an output schema, the description is nearly complete. It could be improved by explicitly stating it is a read operation, but annotations already cover that.

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 0% description coverage for the parameter, but the description adds the parameter's format via an example (e.g., '0000-0001-5109-3700') and implies the expected structure. This goes beyond the bare 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 it returns a 'Full public record by ORCID iD', specifying the resource (record) and the unique identifier. It distinguishes from siblings like 'search' or 'entity_profile' by emphasizing the exact ORCID iD lookup.

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

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

No guidance is provided on when to use this tool versus alternatives. The description implies use only when an ORCID iD is available, but does not mention exclusions or alternative tools for different identifiers.

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 key behavioral traits beyond annotations: scoped by identifier, persistent vs. 24-hour retention for authenticated vs. anonymous sessions. Annotations already indicate idempotent and non-destructive, which the description does not contradict.

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 purpose, usage, and technical details. 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?

Given only 2 simple parameters, no output schema, and good annotations, the description fully covers what the agent needs: what it does, when to use, lifetime, and companion 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%, so baseline is 3. Description adds helpful examples for key ('subject_property') and value ('any text'), improving usability 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?

Clearly states the tool saves data for reuse across conversations/sessions, with specific examples like ticker, address, preference. Distinguishes from siblings by naming 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?

Provides explicit use cases ('when you discover something worth carrying forward') and examples. Mentions pairing with recall and forget, but does not state when not to use; however, the guidance is clear enough for a simple tool.

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

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

Annotations already provide readOnly, openWorld, idempotent, and non-destructive hints. The description adds valuable behavioral context: it mentions internal cascading through multiple lookup endpoints, auto-disambiguation for company names, and that the tool replaces 2-3 manual lookups. 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 a single dense paragraph but is well-structured: it begins with example queries, states the purpose, gives usage guidance, and lists supported types with details. Every sentence adds value. Slightly more formatting (e.g., bullet points) could improve readability, but it is appropriately concise.

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

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

Given no output schema, the description fully explains return values for each type (ticker, CIK, company_name for company; RxCUI, ingredient, brand for drug) and mentions citation URIs. It also covers internal behavior (cascading lookups) and the tool's role in replacing multiple manual steps. No gaps remain for a tool of this simplicity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining the type parameter (company or drug) and the value parameter (ticker, CIK, name vs. brand/generic name). It also details the return fields for each type, providing context that the schema alone does not.

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: resolving user-spoken names to canonical identifiers. It provides concrete examples ('What's the ticker for...'), lists supported entity types (company, drug) with specific output details, and distinguishes itself from siblings by advising '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?

The description explicitly advises when to use the tool ('Use FIRST whenever you have a name but need an ID') and gives example queries. It does not explicitly mention when not to use it or cite specific alternatives, but the context is clear and the sibling tool list is broad.

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 safe, idempotent, open-world behavior. The description adds substantial behavioral context: it probes each entity with ai_visibility_check, ranks by score, surfaces most/least recognized, and returns a ranked list with score, confidence, and signal density. 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 concise (3-4 sentences) and front-loaded with the core purpose. Every sentence adds value, and there is 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?

Given the tool's complexity (4 parameters, no output schema), the description fully covers what the tool does, how it works (calls ai_visibility_check), what it returns (ranked list with metrics), and the optionality of models and API key. It is complete for an agent to understand 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 description coverage is 100%, but the description adds meaningful semantics beyond the schema, such as treating the first entity as the 'subject' for narrative and explaining the role of context for disambiguation. This enriches understanding of how parameters affect behavior.

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

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

The description clearly states the verb 'compare' and the resource 'AI visibility across multiple entities'. It distinguishes from siblings like ai_visibility_check (single entity) by emphasizing multi-entity side-by-side comparison, and provides a concrete use case ('competitive AI-marketing 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 offers clear context for when to use this tool (competitive audits) with an example question ('does Claude know about us as well as our competitors?'). However, it does not explicitly mention when not to use it or directly name alternatives like compare_entities, though the sibling list implies differentiation.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: partial failures degrade gracefully, bundlephobia first measurement may take 5-30s, and sources_failed lists timeouts. 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 well-structured with front-loaded purpose. Each sentence provides useful context. Minor length is justified by the tool's complexity and lack of output schema.

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 adequately explains the return structure and behavior. It covers ecosystem scope, degradation modes, and timing caveats, making it sufficiently complete for a complex tool.

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

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

Schema description coverage is 100% with clear parameter descriptions. The tool description does not add significant new information about parameters beyond what the schema already provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's composite nature ('should I add this npm package' check) and specifies the two data sources. It lists the return fields, distinguishing it from sibling tools like entity_profile or compare_entities.

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 guidelines: 'Use whenever an agent asks 'is X safe / popular / small'' and specifies NPM-only in v1, directing other ecosystems to a different tool. This helps the agent decide when to invoke it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering safety. The description adds 'Solr-style query' as behavioral context but does not disclose additional traits like pagination limits or response size beyond what the schema provides.

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

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

The description is a single, front-loaded sentence with no redundant words. It efficiently conveys the core purpose without wasted space.

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 output schema exists, the description does not need to explain return values. The combination of description, schema, and annotations is adequate for a simple search tool, though additional context about the ORCID Registry could be beneficial.

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 includes descriptions and examples for all three parameters. The description adds no extra semantic meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool performs 'Expanded search (Solr-style query)' across the 'ORCID Registry', specifying the verb and resource. However, it does not differentiate from sibling tools like 'search_within' or 'deep_research', which would help an agent choose correctly.

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 complex queries via 'Solr-style query' but provides no explicit guidance on when to use this tool versus alternatives, nor any conditions or exclusions. The agent must infer from the name and 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?

Annotations already declare readOnlyHint, idempotentHint, and no destructiveness. The description adds value by detailing the embedding model (BGE-base-en), window size (500-char overlapping), character cap (200K with truncation flag), and output (passages with offsets and similarity scores). 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 sentences, no wasted words. The core action is stated first, then the use case, pairing advice, and technical details. Front-loaded and 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?

For a tool with moderate complexity, the description covers key behavioral traits (embeddings, truncation, offsets, scores). No output schema exists, but the description adequately describes return format. Sufficient for effective agent 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%. The description enriches semantics by providing examples for query (e.g., 'supply-chain risk'), clarifying that limit defaults to 5 with range 1-20, and confirming text max as ~200K chars. Adds value beyond the schema.

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

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

The description clearly states it performs semantic search inside a fetched record, using specific examples like SEC 10-K body or article. It distinguishes from sibling tool 'ask_pipeworx_grounded' by explaining the pairing use case.

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

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

It explicitly says to use when the record is too big for the prompt and pairs with ask_pipeworx_grounded. Though it doesn't list when not to use, the context is clear enough for an 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 indicate mutability (readOnlyHint=false) and non-destructiveness (destructiveHint=false) but not idempotency. Description adds: auth requirements (OAuth account), caps (SMS 10/day), return behavior (subscription id), and delivery details. 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?

Well-structured: starts with purpose, then requirements, types, delivery channels. Length is justified by complexity. Could slightly reduce redundancy (e.g., repeated SMS cap) 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?

Given 3 params with 100% schema coverage and no output schema, the description fully covers type, params, delivery, and return id. No gaps for a subscription 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?

Schema coverage is 100%, but description adds value with examples for each type's params, clarifies required vs optional fields for clinical_trial, and explains delivery channels with specifics like webhook HMAC. Enhances understanding 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 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This is a specific verb+resource that distinguishes it 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?

Provides explicit context: requires Pipeworx OAuth account, not for anonymous/BYO users. Lists supported types with examples. Implicitly signals when to use (proactive monitoring) vs one-off queries. Lacks explicit when-not-to-use or alternatives but context is strong.

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, openWorldHint, idempotentHint, and destructiveHint, which are all safe. The description adds behavioral context: it returns example questions with tool+argument shapes, can be called with no arguments for full spread or with topic for focus. 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 long but well-structured, front-loading key phrases and packing necessary information without redundancy. Every sentence contributes meaning, though minor trimming could improve 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 simplicity (1 optional param, no output schema) and rich annotations, the description fully covers purpose, usage, input details, and examples. It provides all information an agent needs to use the tool correctly.

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

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

With 100% schema description coverage, baseline is 3. The description adds value by listing example values for the topic parameter (finance, pharma, etc.) and explaining the behavior when omitted, going beyond the schema's generic 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 explicitly states the tool is the onboarding entry point for a new agent to discover what Pipeworx can answer, with clear verbs and resource ('return category-bucketed example questions'). It differentiates from sibling tools like ask_pipeworx and discover_tools by naming them as meta-tools to learn about.

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 this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools', providing clear when-to-use guidance. However, it does not explicitly state when not to use it or list alternatives beyond naming sibling tools in 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?

Disclosures beyond annotations: explains that the row is deactivated not deleted, and that historical events remain available. Annotations provide idempotentHint and destructiveHint, but description adds valuable detail about data behavior.

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

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

Two concise sentences with front-loaded purpose followed by behavioral and constraint details. 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 a simple tool with 1 parameter, no output schema, and strong annotations, the description covers purpose, ownership, and deactivation behavior. Lacks return value info but is adequate.

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

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

Schema coverage is 100% for the single parameter 'id', with description repeating the schema's explanation ('Subscription id (uuid) returned by subscribe'). No additional semantic value beyond what the schema provides.

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

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

The description clearly states the action ('Cancel a subscription by id'), with a specific verb and resource. It distinguishes from sibling tools 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?

Specifies ownership enforcement ('you can only cancel your own subscriptions'), providing clear context for usage. Lacks explicit alternatives or when-not-to-use guidance, but the constraint is helpful.

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 the annotations: it explains the output includes a verdict (with specific categories), extracted structured form, actual value with citation, and percent delta. It also notes the efficiency gain. This complements the readOnlyHint and idempotentHint annotations well.

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 lengthy, containing multiple example queries and a detailed output explanation. While it is front-loaded with the purpose, it could be more concise by separating the purpose from the implementation details.

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 a single parameter, no output schema, and moderate complexity, the description covers the claim format, domain constraints, output structure, and performance benefit. It provides sufficient context for the agent to use the tool correctly.

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

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

With 100% schema coverage, the parameter is already described. The description enhances this by providing natural-language examples of valid claims and clarifying the domain (company-financial claims), adding practical guidance for the agent.

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 specifies the tool's purpose: verifying natural-language claims against authoritative sources, particularly company-financial claims. It provides example queries and distinguishes itself from other tools by noting it replaces 4-6 sequential calls, making its unique value evident.

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 states to use this tool whenever the agent needs to check factual correctness of a claim, and it clearly limits the domain to company-financial claims. However, it does not explicitly list when not to use it or provide alternative tool names, but the context is clear enough for an AI 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds no behavioral details beyond restating the purpose. No mention of permissions, rate limits, or error handling.

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 at 6 words. No wasted sentences. Front-loaded with the core 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?

The tool is simple with two required params, and annotations cover safety. The output schema exists to document return values. However, the description lacks explanation of what a 'work record' is and the role of orcid_id, making it only moderately 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 0%. The description only mentions put-code, leaving orcid_id unexplained. It adds minimal meaning to the parameters.

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

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

The description clearly indicates the tool retrieves a single work record using put-code. It distinguishes from the sibling tool 'works' (plural) which likely lists multiple works. However, it lacks an explicit verb like 'get' or 'retrieve'.

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

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

No guidance on when to use this tool versus alternatives. The description does not mention usage context, prerequisites, or 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, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds minimal behavioral context (e.g., 'with put-codes'), but does not mention result pagination, order, or any side effects. With strong annotations, the bar is lower, and a 3 reflects adequate but unremarkable transparency.

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

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

The description is extremely concise (one phrase), which saves tokens but lacks sentence structure and clarity. It could be slightly expanded without becoming 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 simplicity of the tool (one parameter, output schema exists), the description provides minimal context but does not cover critical aspects like the meaning of 'put-codes' or how the summaries are returned. It is adequate for a trivial tool but not fully complete.

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

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

The parameter 'orcid_id' has no description in the schema (0% coverage), and the tool description does not elaborate on its format or purpose. The agent must infer meaning from the name alone, which is insufficient for confirming correct 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 indicates the tool returns 'Works (publication) summaries with put-codes', which gives a basic idea but lacks specificity. It does not differentiate from sibling tool 'work' (singular) or clarify the verb (e.g., list, search). The purpose is vague but not tautological.

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

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

No guidance is provided on when to use this tool versus alternatives like 'work', 'education', or 'employment'. There is no mention of prerequisites, context, or when not to use.

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