research_mcp

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

Annotations already declare readOnlyHint=true, so no contradiction. The description adds valuable behavioral context beyond annotations: it explains the appraisal methodology (classifies design, applies RoB frameworks, assesses magnitude/precision rather than significance alone, rates certainty with GRADE, judges applicability). This is substantial added 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?

Three sentences with zero fluff. The first sentence gives the core purpose, the second details the methodology, and the third provides input guidance. Every sentence earns its place.

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

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

For a complex appraisal tool with no output schema, the description does a strong job of explaining what the tool does and what the scorecard includes (design, risk-of-bias, result interpretation, certainty, applicability). It covers the full scope of the tool's behavior sufficiently for an agent to select and invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minimal param-specific meaning beyond the schema, though it does clarify that 'study' should be the abstract or full text. This aligns with schema descriptions, so no extra compensation is needed.

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

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

The description states a specific verb+resource: 'Critically appraise a single study and return a structured scorecard.' It clearly distinguishes from siblings like 'appraise-source' by focusing on a single study and enumerating the appraisal components (RoB 2, GRADE, applicability).

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

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

The description provides clear context for when to use: when you have a single study to appraise, and it suggests feeding an abstract or full text (e.g., from fetch-url). However, it does not explicitly name alternatives or exclusions, so it doesn't earn a 5.

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

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

The annotations already provide readOnlyHint=true, so the agent knows it is a safe read operation. The description adds valuable behavioral detail by describing the internal process: 'Places it in the 7-tier source-quality cadence, runs CRAAP and SIFT checks, flags interest/bias, and recommends a weight...' This gives the agent a clear picture of what the tool will do beyond the annotation alone.

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

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

The description is three sentences, each earning its place: first sentence states the action and scope, second explains methodology/output, third gives usage context. It is front-loaded with the core purpose and contains no filler or repetition.

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 what the tool does, how it does it (CRAAP, SIFT, 7-tier cadence), and when to use it. It also describes the output in terms of a weight and provenance label, which partially compensates for the lack of an output schema. A minor gap is not explicitly detailing the response structure or edge cases, but for a read-only appraisal tool this is sufficient.

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

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

The input schema covers 100% of parameters with descriptions (url, claim, source), so the baseline is 3. The tool description itself does not add additional parameter-level detail beyond the schema's own descriptions; it only reinforces that 'source' is the key input by referring to it as 'the source to appraise.'

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

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

The description opens with a specific verb and resource: 'Appraise a non-study source... for credibility and provenance.' It explicitly distinguishes itself from the sibling tool 'appraise-evidence' by calling itself 'the companion' and listing example source types (press release, analyst note, legislation, etc.), making the tool's scope unmistakable.

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

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

The description gives explicit usage guidance: 'Use for grey literature and for novel or fast-moving topics where peer-reviewed evidence is thin.' It also names the alternative tool (appraise-evidence) as the companion, implying a clear division of labor between appraising studies versus non-study sources.

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, so no contradiction. The description adds valuable behavior context by stating it 'Returns a structured assessment with required approvals, risk flags, and mitigations' and lists the ethical frameworks applied, going beyond 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?

Three dense, front-loaded sentences. The long list of ethical frameworks is necessary for a tool this complex, and every clause contributes information without filler or redundancy.

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

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

Despite lacking an output schema, the description states the return format ('structured assessment with required approvals, risk flags, and mitigations'). With all parameters documented and a clear scope, it is complete for an ethics-review tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds contextual meaning beyond the schema, particularly for uses_ai and involves_humans, by linking them to responsible-AI disclosure and data-governance/privacy checks.

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

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

The description opens with the specific action 'Run a research-ethics and integrity review' and names the resource. It enumerates the ethical frameworks and assessment outputs, making it clearly distinct from siblings like governance-check and peer-review.

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 specifies when to use: 'as a pre-study ethics pre-check and within peer-review.' It provides clear usage context but does not mention when not to use or directly compare with overlapping sibling tools.

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

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

Annotations already signal readOnly and openWorld, and the description adds behavioral context by listing the exact returned data elements (e.g., h-index, ORCID, most-cited works). This goes beyond the annotation's safety profile, though it doesn't discuss ambiguity resolution for common names or pagination 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 sentences, front-loaded with the core function and value, then a compact list of outputs and use cases. No filler or redundancy.

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

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

Given the output schema exists (return values are handled elsewhere), the description sufficiently covers the tool's purpose, key behaviors, and typical use. It doesn't mention potential edge cases like ambiguous author names, but the existing schema and annotations make this 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%, but the description adds meaning by clarifying that works_limit refers to 'most-cited works,' which sharpens the schema's vague 'top works.' The name parameter is already well-documented in the schema, so the description provides a small but meaningful improvement.

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

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

The description uses a specific verb ('Look up a researcher') and clearly identifies the resource (OpenAlex) and the output fields (works count, citations, h-index, affiliation, ORCID, most-cited works), distinguishing it from sibling tools like search-literature or citation-graph.

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 the tool ('to gauge a source author's expertise and track record, or to find a researcher's key papers'), giving clear context. It doesn't name alternative tools or exclusions, but the use cases are sufficiently distinct.

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, so no contradiction. The description adds valuable transparency by detailing the output (each item marked Reported/Partial/Not reported/N/A with location and gap, plus critical omissions), which goes beyond annotations. It does not mention any side effects or limitations, but the read-only profile is covered.

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

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

Two sentences, front-loaded with the key action and outcome. The checklist list and report format are packed into efficient phrasing with no filler or redundancy.

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

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

With only 2 parameters and full schema coverage, the description thoroughly explains the tool's purpose, selection mechanism, and return format. It gives an agent enough to decide when to use it and what to expect, even without an output schema.

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

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

Schema description coverage is 100%, so both parameters are already documented. The description only reinforces the study_type-to-checklist selection logic, adding no syntax or format 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?

Description opens with 'Validate a manuscript or draft against the right reporting checklist' — a specific verb+resource. It enumerates the exact checklist standards (PRISMA, CONSORT, etc.) and notes automatic selection by study design, which clearly distinguishes it from sibling tools like peer-review or appraise-evidence.

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

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

States 'Use before submission or as part of peer review,' giving a clear context for when to invoke. It also mentions selection by study design but does not explicitly contrast with alternative sibling tools or list exclusions, so it stops short of a 5.

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

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

Annotations already indicate readOnlyHint=true and openWorldHint=true, lowering the bar for behavioral disclosure. The description adds valuable context beyond these: results are 'ranked by citation count' and the seed can be resolved via 'DOI, OpenAlex ID, URL, or title'. This meaningfully enriches the behavioral profile without contradicting annotations.

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

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

The description is three sentences, each with a distinct purpose: definition, use cases, and identifier resolution. It is front-loaded with the primary verb 'Map', contains no redundant phrasing, and every sentence earns its place. Excellent 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?

With an output schema present and detailed parameter descriptions, the description does not need to explain return values. It covers the tool's purpose, use cases, and identifier resolution, which is sufficient for a 3-parameter tool with good annotations. A minor gap is lack of explicit mention of limitations or alternative tools, but overall it is complete.

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

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

Schema coverage is 100%, so the baseline is 3. However, the description adds important parameter-related semantics: 'each ranked by citation count' clarifies that the 'limit' parameter refers to top-N results by that ranking, which is not stated in the schema. This extra information enhances the interpretation of the limit parameter.

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 a specific action: 'Map the citation neighbourhood of a seed paper using OpenAlex', and defines exactly what that entails (backward and forward citations). It distinguishes itself from siblings like search-literature or fetch-paper by focusing on the citation graph structure rather than general search or retrieval.

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

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

The description provides explicit use cases: 'Use to snowball a literature search, trace a finding to its origins, or surface the most influential follow-on work.' However, it does not explicitly mention when not to use this tool or name alternative sibling tools, so it falls short of the 5-level 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?

With readOnlyHint=true already signaling a read-only operation, the description adds meaningful behavioral detail by outlining the returned scaffold: question-type classification, candidate designs, validity threat checklist, sampling considerations, and recommendation. It does not contradict annotations and goes beyond what annotations alone 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 two sentences, front-loaded with the primary purpose and followed by a compact list of return components. Every sentence earns its place with no redundancy or filler.

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

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

Given the tool's complexity and lack of an output schema, the description thoroughly explains what the tool returns (the scaffold components) and when to use it (after scope-question). It provides enough detail for an agent to understand the tool's role and expected outputs.

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 parameters are already well documented. The description adds minimal semantic value beyond the schema, merely restating 'research question and its constraints' and indicating that the question should be sharpened via scope-question. This meets the baseline for high schema coverage but does not exceed it.

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

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

The description clearly states the tool's function: 'Recommend a fit-for-purpose study design for a research question and its constraints, then surface the validity threats it must address.' It specifies the verb (recommend), the resource (study design), and the scope (research question + constraints), making it distinct from sibling tools like appraise-evidence or plan-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 explicit usage context: 'Use after scope-question.' This clearly positions the tool in a workflow. However, it does not mention when not to use it or provide alternative tool names, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, establishing safety. The description adds behavioral depth by disclosing the methodology: it walks the DeVellis sequence, includes item-writing rules, response-format choice, reliability/validity strategy, and total-survey-error control for quantitative work, and a trustworthiness plan for qualitative work. This goes beyond a simple 'develops instrument' claim, though it does not disclose potential limitations (e.g., that it only produces plans, not statistical validation).

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 tightly written with no filler. The first sentence states the core purpose; the second explains quantitative/qualitative behaviors; the third clarifies an alternative usage. All sentences contribute directly to understanding, and the structure is logical 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?

For a complex generative tool, the description reasonably covers both major modes (quantitative/qualitative) and the critique path. It implies the outputs (draft instrument, interview guide, plans) without needing to detail them, especially since there is no output schema. It could be more complete by explicitly noting that the tool produces a written instrument plus a validity/reliability plan, but the description is sufficiently sufficient given no output schema and good parameter documentation.

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

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

Schema coverage is 100% with parameter descriptions, giving a baseline of 3. The tool description adds extra semantics by explaining that 'mode' changes the underlying methodology (quantitative vs qualitative) and that 'existing_items' can be provided for critique rather than starting fresh. This reinforces and expands on the schema descriptions, providing genuine added 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 opens with 'Draft or critique a measurement instrument' and enumerates concrete types (survey/scale, interview protocol, observation schedule), making the tool's purpose unambiguous. It also differentiates from siblings by focusing specifically on instrument development with reliability/validity planning, rather than study design or 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 clearly indicates when to use the tool: when drafting or critiquing an instrument, and even distinguishes between quantitative (DeVellis sequence) and qualitative (trustworthiness plan) approaches. It also mentions the 'provide existing items to critique' usage scenario. However, it does not explicitly name sibling alternatives or state when NOT to use this tool, so it falls short of full exclusion guidance.

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

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

Beyond the readOnlyHint and openWorldHint annotations, the description discloses the source-selection behavior: it uses DOI content negotiation for publisher-grade entries and falls back to OpenAlex metadata when no DOI exists. It also describes output compatibility with common reference managers and LaTeX/Pandoc pipelines. This adds meaningful behavioral context, though it does not cover all edge cases like error handling or rate limits.

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

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

Four sentences, each adding value: purpose, source behavior, output compatibility, and companion tool. No fluff or repetition. The most important information is front-loaded in the first sentence.

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

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

Given no output schema, the description adequately explains what the tool produces (a bibliography) and where it can be used. It covers input types, formats, fallback behavior, and integration with other tools. It does not explicitly describe error conditions or output structure details, but those are largely unnecessary for a bibliography export tool with this schema and annotation profile.

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 both parameters (identifiers and format) already well described. The description adds minimal parameter-specific detail beyond restating the input types and formats; its main added value is behavioral context rather than parameter semantics. Baseline 3 is appropriate given the schema coverage.

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

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

The description begins with 'Build a bibliography from a list of papers'—a specific verb and resource—and lists accepted input types (DOIs, OpenAlex IDs, URLs, titles) and output formats (BibTeX, RIS, CSL-JSON). This clearly differentiates it from siblings like fetch-paper (single paper retrieval) or zotero-save (saving to Zotero), establishing it as the bibliography-generation step.

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 clear usage context: use this tool to create a bibliography in standard formats for reference managers or LaTeX/Pandoc. It also suggests pairing with search-literature to assemble a reference set. However, it does not explicitly state when not to use it or contrast with alternative tools (e.g., zotero-save), so it lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint and openWorldHint, and the description adds substantial behavioral context: server-side retrieval via the fetch-url ladder, support for paywalled/bot-protected PDFs, and in-process text extraction without external converters. This enriches the annotations with actionable operational details.

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

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

The description is three sentences that are front-loaded with the core action and each sentence provides distinct value: purpose and input types, retrieval/behavior details, and pairing recommendation. There is no filler or redundancy.

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

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

For a simple extraction tool with no output schema, the description covers input source types, retrieval mechanism, return value, and a follow-up tool suggestion. It is sufficiently complete for an AI agent to know what to expect and how to use the tool.

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

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

The schema provides 100% coverage for both parameters, so the baseline is 3. The description adds meaning by explaining that URLs are retrieved server-side via a special ladder and that protected PDFs work, which goes beyond the schema's simple mention of 'retrieved server-side first' for 'source'. It does not discuss 'max_pages', but the schema fully covers it.

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

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

The description opens with a specific verb-resource pair ('Extract text from a PDF') and clarifies the intended use case ('for appraisal or data extraction'). It differentiates from sibling tools like fetch-url by emphasizing PDF-specific extraction and mentions the in-process return behavior, making its purpose unmistakable.

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

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

It states when to use the tool ('for appraisal or data extraction') and suggests pairing with appraise-evidence, providing clear contextual guidance. However, it does not explicitly state when not to use it or name alternative tools like fetch-url for non-PDF sources, so it lacks full exclusion guidance.

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

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

The description adds substantial behavioral detail beyond the annotations: it explains the OpenAlex lookup, use of the fetch-url ladder, in-process PDF parsing, and the paywalled fallback. This gives the agent a strong sense of what will happen, aligning with the readOnlyHint and openWorldHint.

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

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

The description is three well-structured sentences: the first states the core purpose, the second explains the mechanism, and the third covers edge cases and downstream use. Every sentence earns its place, with key information 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?

Despite lacking an output schema, the description covers inputs, processing steps, the paywalled edge case, and downstream integration, making it sufficiently complete for an agent to decide when and how to invoke the tool.

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

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

The input schema already thoroughly documents both parameters (identifier and include_full_text) with descriptive text, so the description adds no new meaning. The baseline for 100% schema coverage applies here.

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 ('resolve', 'return') and identifies the resource (a paper) with four supported identifier types. It clearly distinguishes this from siblings like fetch-url by emphasizing metadata and full-text retrieval, and even mentions downstream tools, making its role unambiguous.

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

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

The description implies when to use the tool by stating it resolves paper identifiers and suggests feeding results to appraise-evidence or export-bibliography. However, it does not explicitly state when to prefer this over sibling tools like search-literature or fetch-url, though the context is clear.

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

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

The description discloses the retrieval ladder (curl → wget → headless Chrome), the reproduction of user's IP/VPN and User-Agent, and the output transformations for different content types (HTML to Markdown, JSON/text as-is, PDFs/binaries saved to disk). This goes well beyond the readOnlyHint and openWorldHint annotations, providing concrete behavioral context without contradiction.

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

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

The description is three sentences, tightly structured: first sentence states purpose and key access behavior, second explains the retrieval process and output formats, third gives usage guidance. No redundant words 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?

Despite no output schema, the description adequately explains return behavior for different content types, mentions file saving with a reported path, and covers usage context. This is complete for a tool of this complexity.

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

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

Input schema coverage is 100%, with detailed descriptions for all four parameters (url, method, cookie_file, timeout_seconds). The tool description adds no additional parameter-level semantics beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description clearly specifies the verb 'Retrieve' and the resource 'a web page or file from the user's own machine', and distinguishes itself from siblings like web-search and fetch-paper by emphasizing arbitrary URL retrieval with the user's access context.

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 states when to use this tool ('Use this to read sources that a direct client cannot reach') and how it pairs with web search ('pair it with web search'). The method parameter description also advises forcing 'chrome' for JS-heavy or bot-protected pages, giving clear alternative guidance.

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

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

Annotations mark readOnlyHint=true, and the description consistently portrays a read-only review action. It adds behavioral context by listing the checklist dimensions, the escalation flag, and the decision path. It also discloses that it doesn't replace committee ToR, which is useful. No contradictions or hidden side effects are described.

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

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

The description is two sentences, front-loaded with the core purpose. The second sentence is dense with checklist items and outputs, which is somewhat heavy but informative. It earns a 4 because the density is purposeful and avoids fluff, though the checklist enumeration could be trimmed.

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 tool's return value: a recommendation path, risk classification, checklist, and escalation flag. It also situates the tool within a governance process and points to a complementary tool. For a 2-param review tool, this is comprehensive.

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

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

The schema already provides full descriptions for both parameters (100% coverage), so the tool description doesn't need to repeat them. It only loosely references 'use case' in the opening sentence, without adding new meaning beyond the schema. The baseline of 3 is appropriate given the schema's completeness.

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 reviews AI or people-data use cases against governance dimensions, with specific outputs like risk tier, checklist, and recommendation path. It distinguishes itself from siblings by focusing on governance (not ethics) and explicitly references assess-ethics as a complementary 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?

It provides clear usage context: use for governance review of AI/data use cases, and explicitly recommends pairing with assess-ethics. It also notes the tool complements rather than replaces committee ToR, giving a boundary. However, it doesn't enumerate explicit when-not-to-use scenarios, so it stops short of a 5.

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

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

The annotations already mark it readOnly=true and openWorldHint=false. The description adds that it produces a structured report with specific sections and that it composes other tools, which is useful behavioral context about internal orchestration. 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?

Two sentences, front-loaded with the primary purpose, followed by a compact list of report contents and composition behavior. No filler.

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

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

The description covers the output structure, recommendation scale, and relationship to sub-tools. Since there is no output schema, this description carries the burden well. It doesn't mention edge cases but is largely complete for selection and invocation.

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

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

Schema description coverage is 100%, and each parameter (manuscript, venue, study_type, review_type) has a clear description. The tool description does not add further parameter-level detail, so baseline 3 applies.

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

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

The description opens with a specific verb ('Run') and resource ('peer-review pass over a manuscript'), and enumerates the report contents (summary, significance, issues, methodological critique, etc.), distinguishing it from sibling sub-tools that it composes.

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 states that the tool composes appraise-evidence, check-reporting, plan-analysis, and assess-ethics for deep dives, implying it is the umbrella tool for a full review. However, it does not explicitly list exclusion criteria or when to prefer an alternative.

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

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

Annotations already mark this as read-only, and the description adds valuable context about what it returns: 'construct definition, validated instruments to license, example metrics, design considerations, common pitfalls, data sources, and people-data governance flags.' It also notes the handoff behavior, making the tool's behavioral scope clear.

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

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

Three sentences deliver a complete picture: what it does, what it returns, and when to use it. The description is front-loaded with the core action, and every clause adds value without unnecessary filler.

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

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

For a 2-parameter tool with no output schema, the description is fully self-sufficient. It explains the full set of returned content, the domain coverage, and the downstream workflow, so an agent has complete context to invoke and interpret 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%, and both parameters already have meaningful descriptions in the schema. The tool description merely restates the enum values for 'topic' and does not add any new semantic detail about parameter usage or constraints 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 opens with a specific verb and resource: 'Frame a people-analytics study with a domain preset,' and lists all six topic areas. It clearly distinguishes itself from siblings by framing it as the starting point that hands off to design-study, develop-instrument, and assess-ethics.

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 'Use to start any HR/workforce research,' giving a clear when-to-use directive. It also contextualizes the workflow by naming downstream tools, which implies when this tool is not needed (after framing is complete).

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

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

Annotations already mark it read-only, but the description adds substantial behavioral detail: it lists assumptions to check, insists on effect sizes with confidence intervals over bare p-values, flags p-hacking/HARKing/multiplicity risks, and handles missing data. It clarifies that the tool produces a strategy/plan rather than performing actual analysis, which is valuable 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 three sentences, front-loaded with the core purpose. The first sentence states the main function, the second elaborates on quantitative and qualitative modes, and the third gives usage timing. 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?

The description is fairly complete for a planning tool with 3 parameters and no output schema. It covers both quantitative and qualitative branches, mentions key rigor aspects, and provides temporal context. However, it does not explicitly describe the output format (e.g., a structured plan, a list of assumptions), which would be helpful given the lack of an output schema.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds context by explaining how the 'question' drives the test/model family and how 'variables' (key variable types) are matched, and it mentions that for qualitative data 'variables' describes the nature of the data. This goes beyond the schema's individual field descriptions.

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

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

The description opens with a specific verb+resource: 'Recommend an analysis strategy and keep the inference honest.' It clearly distinguishes from sibling tools by detailing quantitative and qualitative functions (matching test/model families, listing assumptions, flagging p-hacking) and by positioning itself 'after design-study, before collecting or analysing data.'

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

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

It explicitly states when to use this tool: 'Use after design-study, before collecting or analysing data.' This gives clear contextual timing, though it does not name specific alternative tools for when not to use it, which is a minor gap.

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, covering safety. The description adds valuable behavioral context by listing the detailed output scaffold (FINER appraisal, framework elements, constructs, scope boundaries, question type). This clarifies what the tool returns without contradicting annotations.

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

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

The description is three sentences, front-loaded with the primary purpose, and packs essential output details into a compact list. 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?

With no output schema, the description must explain return values, and it does so thoroughly by enumerating the scaffold's components. Combined with a clear usage context and readOnlyHint, it provides sufficient orientation for an agent to invoke and interpret the tool.

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

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

Schema description coverage is 100%, and each parameter (idea, context, paradigm) has its own description. The tool description doesn't add parameter-specific semantics beyond the schema; it reinforces the 'idea' role but doesn't compensate further, consistent with the baseline for full schema coverage.

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

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

The description specifies the tool's core function with a clear verb and resource: 'Turn a fuzzy idea into one or more sharp, researchable questions.' It enumerates the returned components, making the purpose precise and well-differentiated from sibling tools like design-study, which it explicitly positions itself before.

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

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

The description gives explicit guidance: 'Use at the very start of a research effort, before design-study.' This provides clear temporal context and informally names a related sibling, but it doesn't explicitly cover when not to use the tool or mention alternative tools beyond the temporal pointer.

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?

With readOnlyHint=true already present, the description adds valuable behavioral context: results are merged and de-duplicated by DOI/title, ranked to prioritize cited peer-reviewed work over zero-citation preprints, tagged with source, and include specific fields. It also notes the indexes are free and keyless. It does not cover nuances like rate limits or pagination quirks, but the added ranking and dedup detail goes beyond annotations.

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

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

The description is well-structured and front-loaded, opening with the core purpose, then covering result behavior, output fields, and usage guidance. Each sentence earns its place and there is no filler. It is appropriately sized for a tool with 8 parameters and multiple sibling alternatives.

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 moderate complexity, the description is complete: it covers what the tool does, which sources are searched, how results are ranked and formatted, and how to hand off results. An output schema exists, so not detailing return values is acceptable. The description also gives clear cross-tool context with siblings, making it self-contained for an agent.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds some framing for the `sources` parameter but largely repeats what the schema already states (e.g., source-specific scope). It does not add new parameter-level syntax or format details beyond the schema, so it does not exceed the baseline.

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

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

The description states a specific action ('Search the scholarly literature') with a clear resource scope (four named indexes: OpenAlex, Crossref, arXiv, OSF). It distinguishes from siblings by explicitly contrasting with web-search for non-academic sources. The scope, default, and result contents are precisely described, making the tool's purpose unmistakable.

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

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

The description provides explicit usage guidance: it says to use the `sources` array to widen reach, to pass results to downstream tools (appraise-evidence, fetch-paper, export-bibliography), and directly names web-search as the alternative for open-web/grey sources beyond academia. This makes the decision boundary 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?

With readOnlyHint=true, the bar is lower, but the description adds rich behavioral detail: it 'assesses clinical/methodological/statistical heterogeneity before any pooling,' 'rates certainty... with GRADE,' and 'identifies gaps.' This goes beyond the annotation and describes the analytical process.

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 run-on paragraph with many clauses. It is front-loaded with the main purpose but could be more scannable with bullet points or shorter sentences. Every sentence earns its place, but the structure is not ideal.

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

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

For a complex synthesis tool with no output schema, the description covers essential aspects: input modes (studies provided or scaffolded), method selection, heterogeneity assessment, GRADE, and gap identification. It does not explicitly describe the return format, but the output is sufficiently implied by the listed deliverables.

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 meaningful context by explaining that 'studies' is optional and that omitting it scaffolds the full pipeline from protocol onward, which is not stated in the schema. It does not mention the 'review_type' parameter, but the enum descriptions already cover it.

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

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

The description uses a specific verb ('Structure a synthesis') and clearly identifies the resource ('evidence across multiple studies'). It details exact activities (recommends review type, synthesis logic, heterogeneity assessment, method selection, GRADE, gap identification), distinguishing it from siblings like appraise-evidence or scope-question.

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

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

The description gives clear usage context: 'Provide the studies, or use it to scaffold a systematic review from the protocol stage.' It implies when to use (when synthesising multiple studies) but does not explicitly exclude alternatives or mention when not to use 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?

ReadOnlyHint already signals a non-mutating operation; the description adds useful behavioral context about evidence-based management framing, honest confidence communication, and the BLUF-led output scaffold. 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?

Three tightly written sentences front-load the core purpose, then add method/philosophy and output/companion guidance. No wasted words.

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

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

The description is complete given the tool complexity: it explains inputs, audience options, decision sharpening, output type (BLUF-led scaffold), and next step (pair with internal-comms). No output schema is needed because the deliverable is well characterized.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces what audience and decision do (shaping emphasis and the ask) but does not add new parameter-level details 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 uses a specific verb phrase ('Convert research findings into a decision-maker brief') and names exact audience types. It clearly distinguishes the tool from siblings like synthesise-evidence by focusing on translation to practice and outputting a BLUF-led brief scaffold.

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

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

It gives concrete context (when to use: research findings to decision-maker brief) and explicitly recommends pairing with the internal-comms skill for final formatting. It does not explicitly state when not to use or contrast with upstream tools like appraise-evidence, but the intended use case 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=true and openWorldHint=false, so the safe-read nature is covered. The description adds meaningful context beyond annotations: it requires the RESEARCH_MCP_OBSIDIAN_VAULT environment variable and restricts the tool to Markdown notes. It does not contradict the annotations, though it does not cover not-found or error behavior.

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

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

The description is two short sentences. The first immediately states the action and object, and the second adds the only prerequisite. There is no filler, redundancy, or unnecessary detail.

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

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

For a simple one-parameter read tool with strong annotations and a fully described schema, the description adequately covers purpose, path format, and configuration requirement. It does not explicitly state the return format or error behavior, but these are intuitive for a note-reading tool and the complexity is low; overall it is sufficiently 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 schema has 100% coverage for the single 'path' parameter with an example ('research/burnout-review.md'), and the description only repeats the 'vault-relative path' concept. Since the schema already documents the parameter fully, the description adds no extra semantic value, aligning with the baseline of 3.

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

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

The description uses a specific verb 'Read', identifies the resource as 'Markdown note from the configured Obsidian vault', and specifies the method 'by vault-relative path'. This clearly distinguishes it from sibling tools like vault-search (find notes by query) and vault-write-note (write/update notes).

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

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

It provides clear context by stating the requirement for RESEARCH_MCP_OBSIDIAN_VAULT and the need for a vault-relative path, but it does not explicitly say when to use this tool versus alternatives such as vault-search for locating a note. Usage is implied rather than directly contrasted with siblings.

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

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

The annotations already declare readOnlyHint=true, so the description only needs to add context beyond that. It adds the requirement of RESEARCH_MCP_OBSIDIAN_VAULT, the fact that it searches Markdown notes, and the return format (line numbers and snippets). This provides useful behavioral detail without contradicting annotations.

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

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

The description is two sentences: the first front-loads the action and output, the second adds usage guidance and a prerequisite. Every sentence provides distinct value with no fluff or repetition of schema details, making it tightly written and easy to scan.

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

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

For a simple search tool with only two parameters and no output schema, the description covers the essential context: what is searched, what is returned, when to use it, and a required environment variable. It could potentially explain match behavior (e.g., case sensitivity) or clarify that results are capped by limit, but these are minor given the low tool complexity.

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

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

Schema description coverage is 100%, and both query and limit have clear descriptions in the schema. The tool description does not add further parameter-level meaning, but with full schema coverage the baseline of 3 is appropriate. It doesn't need to compensate for schema gaps.

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

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

The description states a specific verb ('Search'), a clear resource ('the configured Obsidian vault (Markdown notes)'), and an explicit output ('matching files with line numbers and snippets'). This uniquely distinguishes it from sibling tools like vault-read (reading a specific note) and web-search (searching the web), as it narrows to the local Obsidian vault.

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

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

The description explicitly says when to use it: 'Use to find existing notes, lit reviews, or evidence tables before creating new ones.' It also notes the environment variable prerequisite. However, it does not explicitly name alternative tools or state when not to use it, so it stops short of a full when-to-use/when-not-to-use contrast.

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?

With annotations already indicating a non-read-only operation, the description adds valuable behavior details: three write modes (create, overwrite, append), fail-if-exists behavior, and path confinement to the vault. It also discloses a configuration requirement. These go beyond what annotations alone 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 two sentences with no fluff. It front-loads the core action ('Write a Markdown note'), then quickly covers modes, path safety, and a requirement. Every sentence earns its place.

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

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

Given the tool's moderate complexity, the description covers purpose, modes, path restrictions, and a prerequisite. It does not mention return values or directory creation behavior, but those are not critical for a simple write operation, and no output schema is provided expecting such details.

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

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

The input schema already describes all parameters thoroughly (path is vault-relative, .md is appended, content is Markdown, mode has an enum with explanations). The description adds nothing about parameter semantics beyond the schema, so the 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 verb 'Write' and the resource 'Markdown note into the configured Obsidian vault', with concrete examples of use cases. It implicitly distinguishes from sibling tools like vault-read and vault-search by focusing on write operations.

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 a clear context for when to use the tool (e.g., writing literature notes, evidence tables, research summaries) and mentions a prerequisite (RESEARCH_MCP_OBSIDIAN_VAULT). It does not explicitly compare with alternatives, but sibling names make the distinction obvious.

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

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

Annotations already declare readOnlyHint and openWorldHint. The description adds valuable behavioral context beyond that: 'Keyless (DuckDuckGo) and retrieved server-side' and 'Returns title, URL, and snippet per result.' It also hints at the need to assess source quality, which is a behavioral trait not captured elsewhere.

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

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

The description is three sentences, each earning its place: purpose, use case, and operational/return details plus follow-up chain. It is front-loaded with the core action and maintains a tight, information-dense structure without redundancy.

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

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

With a full output schema, return values are already documented. The description covers launch context (novel topics), alternatives (search-literature), operational characteristics (keyless, server-side), and post-processing (fetch-url, appraise-source). It is remarkably complete for a search 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 each parameter already well-documented (e.g., site restriction, limit range, recency enum). The description adds minimal parameter-specific meaning beyond what the schema provides, 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 opens with a specific verb and resource: 'Search the open web for sources scholarly indexes miss,' enumerating concrete content types (grey literature, official/regulatory documents, press releases, analyst commentary, news). It explicitly differentiates from the sibling search-literature by noting 'For peer-reviewed work, prefer search-literature.'

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 clearly states when to use this tool: 'Essential for novel or fast-moving topics... where peer-reviewed literature is thin.' It also names alternatives and follow-up steps: 'prefer search-literature' for peer-reviewed work, and 'retrieve with fetch-url and weigh with appraise-source (mind the source-quality cadence).'

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, but the description goes further by explaining which output components are included (items, response scales, validated instrument each block is modelled on) and adding critical caveats: items are illustrative and need licensing for defensible measurement, plus survey-hygiene and people-data governance notes. This pragmatic caution is not present in annotations and is highly valuable for safe use.

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

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

The description is three sentences, front-loaded with the primary purpose, and structured logically: assembly, output contents, and caveat/next-step. No filler or redundancy; every sentence earns its place.

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

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

Although there is no output schema, the description explicitly lists return contents (items, scales, instrument references, notes), which gives the agent a solid expectation. It also covers licensing governance and points to the sibling tool for refinement. For a template-assembly tool with good annotations, this is complete.

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

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

Schema description coverage is 100%: both parameters (constructs and population) already have clear descriptions, and constructs are fully enumerated. The description adds no additional parameter-level meaning beyond restating the construct names, so the baseline of 3 applies.

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

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

The description clearly states the tool assembles a workforce survey from specific construct blocks (engagement, inclusion, etc.), lists the outputs (items, response scales, validated instrument references), and distinguishes itself from the sibling tool 'develop-instrument' by positioning that as a refinement step. The verb 'Assemble' plus resource is specific and non-generic.

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

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

The description gives a clear when-to-use context: assembling from pre-defined validated-style blocks. It explicitly points to develop-instrument for refinement, which helps with alternatives. However, it does not mention when not to use other sibling survey-related tools like design-study or people-analytics-preset, so it lacks a full exclusion set.

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

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

Beyond the annotations (readOnly=false, destructive=false), the description elaborates that the tool writes a journal-article item with specific fields (title, authors, year, venue, DOI) and requires Zotero 7+ for writes. This gives practical insight into the write behavior and system dependency, which is valuable context not captured by the annotations.

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

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

The description is two sentences: the first delivers the core function, the second covers prerequisites and usage pairing. It is front-loaded and contains no redundant or filler content, earning a 5.

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

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

For a one-parameter tool with no output schema, the description covers the essential context: input types, what is saved, system requirements, and related tools. It does not specify the return value or error behavior, but for this simple save operation that is a minor gap, so a 4 is given.

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 single parameter 'identifier' is fully described in the schema with the same list of accepted formats (DOI, OpenAlex ID, URL, title). The description repeats these formats but adds no new semantics beyond confirming that the tool resolves the identifier to a paper, so the baseline of 3 is appropriate.

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

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

The description explicitly states the action ('save it to the user's local Zotero library') and the input types (DOI, OpenAlex ID, URL, title), clearly distinguishing it from sibling tools like search-literature and fetch-paper by naming the resource and operation.

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 contextual usage by stating 'Pair with search-literature or fetch-paper to capture a source you want to keep,' indicating when to use the tool (after finding a paper). It also notes the prerequisite (Zotero running with local API enabled), but does not explicitly list when-not-to-use scenarios, so it fits just below 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 indicate readOnlyHint=true and openWorldHint=true, and the description is consistent with these. It adds meaningful behavioral context beyond annotations, including the local API requirement, the return fields (title, authors, year, type, DOI, Zotero key), and the local-library scope. This enriches the agent's understanding without contradicting the annotations.

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

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

Three concise sentences with zero waste. The purpose, usage context, return values, and prerequisite are all front-loaded and clearly structured. Every sentence earns its place without fluff or redundancy.

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

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

For a simple 2-parameter read-only tool, the description is complete: it states the data source, the prerequisite, the return fields, and the use case. No output schema exists, so the explicit list of returned fields is valuable. Given the annotations and schema richness, no critical 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 description coverage is 100%: both query and limit have descriptive text in the schema. The tool description doesn't add new parameter-level semantics beyond what the schema already provides; it restates that matching covers titles and authors but doesn't introduce format, syntax, or edge-case details. Baseline 3 is appropriate because the schema does the work.

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 'Search' and the specific resource 'user's local Zotero library via the Zotero desktop app's local API.' It also distinguishes this tool from broader literature searches by framing it as answering 'what do I already have on X?' before searching the wider literature, setting it apart from sibling tools like web-search and search-literature.

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

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

The description provides clear usage context: use this before searching the wider literature to check what the user already has. It also gives a crucial prerequisite (Zotero running with local API enabled). However, it does not explicitly name alternatives or state when not to use it, stopping short of full when/when-not guidance.

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