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

No annotations are provided, so the description carries the full burden. It does disclose meaningful traits: the content must be Markdown, the note links to sources, and notes feed generate_outline. It omits whether sources must pre-exist, whether the note is mutable afterward, duplicate handling, and what the call returns.

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 tight sentences with zero padding. The core action is front-loaded, and the second sentence supplies useful workflow context rather than restating the name or title.

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 creation tool with no output schema and no annotations, the description should say more about results and constraints. It covers purpose, format and downstream use, but leaves the return value (e.g. a note id) and failure conditions unspecified, so it is adequate rather than 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 75%, close to the 80% threshold where the schema does the heavy lifting, so 3 is the appropriate baseline. The description adds only marginal meaning: 'Markdown' maps to content and 'link it to the sources' maps to sources, but title and tags semantics remain unaddressed.

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

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

The description states a specific verb and resource ('Write a research note') plus format ('in Markdown') and a linking behavior. It differentiates itself somewhat from siblings by naming the downstream consumer (generate_outline), but it never contrasts with update_note or add_quote, so an agent must infer those boundaries.

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 implied usage context by explaining that notes are the raw material for generate_outline, which hints at when this tool fits in a workflow. However, there is no explicit when-to-use guidance versus update_note/add_quote, no prerequisites (e.g. must sources already exist), and no 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?

No annotations are provided, so the description carries the full burden. It says what gets attached but not whether the source must already exist, what happens on duplicate quotes, whether the write is reversible, or what is returned. For a mutation tool with zero annotation coverage this is a real gap.

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 well-formed sentence that front-loads the core action and relegates optional detail to a parenthetical. 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?

With no output schema and no annotations, the description should at least cover preconditions and mutation behavior for a 4-parameter write tool. It covers the operation itself adequately but leaves the source-existence prerequisite and error/return behavior unstated.

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 all four parameters (source, text, page, note) are already documented in the schema. The description restates the optional ones (page/location, comment) without adding format or constraint detail beyond the schema. 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?

States a specific verb+resource: attach an excerpt to a source. The parenthetical lists the optional fields, making the operation concrete. It does not differentiate from siblings like add_note or add_source, which share nearly identical naming, so an agent gets no explicit routing help.

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?

There is no guidance on when to use this versus add_note, add_source, or the various update_* siblings. Usage is only implied by the word 'source'. No prerequisites (does the source need to exist?) are stated.

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

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

No annotations are provided, so the description carries the full behavioral burden, and it says nothing beyond the purpose. It does not disclose whether duplicate sources are detected, whether the write is idempotent, what happens to an existing source with the same DOI/URL, or what a successful call returns.

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 short sentences, zero filler, and the core purpose is front-loaded ahead of the routing hint. Every clause 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 9-parameter creation tool with no annotations and no output schema, the description covers purpose and sibling routing but omits duplicate handling, conflicts with cite_url/update_source, and post-create behavior. Adequate to invoke, incomplete for edge cases.

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 78%, so the schema already documents nearly every field (type enum, authors format, tags casing, dates). The description's 'book / paper / page' phrasing loosely gestures at the type enum but adds no real syntax or constraint detail, so baseline 3 is appropriate.

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

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

States a specific verb+resource ('Record a source by hand') and enumerates the cases it covers (book, paper with details, unfetchable page). It explicitly contrasts itself with the sibling cite_url, so an agent can pick between them without opening a schema.

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?

'Use this when cite_url is not possible' gives a clear triggering condition and names the primary alternative. It stops short of full routing guidance -- no mention of the relationship to update_source (avoid duplicates) or add_note/add_quote -- so it's clear context without exclusions.

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

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

Annotations show readOnlyHint=false and openWorldHint=true; the description adds valuable context by explaining deduplication behavior and that quotes/notes attach to existing sources. It doesn't discuss error modes or auth requirements, but the dedup behavior is a key non-obvious trait.

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, front-loaded with the core action and followed by the deduplication rule and the value proposition. No waste; every sentence carries distinct 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?

Given no output schema, the description covers the key behavioral outcomes (dedup, note/quote attachment). It doesn't describe what the saved source object looks like or any rate limits, but for a 5-param tool with full schema coverage, it is largely 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. The description adds meaning by explaining that quote/note are added to the existing source if the URL is already saved, and that the URL itself is deduplicated – semantics not evident from 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?

States a specific verb and resource: fetch a URL, extract bibliographic metadata, and save it as a source. Distinct from siblings like add_source and add_quote by naming the exact capture behavior.

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

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

Provides clear context: 'the fastest way to capture a citation while browsing.' Explains the deduplication behavior, which frames when to use it versus add_source. However, it doesn't explicitly name add_source as the alternative or state 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?

No annotations are provided, so the description carries the full load. It does disclose the meaningful side effect and its location ('write the result to references.bib next to the notebook'), which is useful context beyond the schema. However it omits whether the file is overwritten, whether auth is needed, and whether the BibTeX text is also returned.

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 tight sentences, front-loaded with what the tool does before the optional behaviors. No filler or redundancy; every clause carries 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 two-parameter export tool with no output schema and no annotations, the description covers the action, filtering, and file side effect, which is roughly adequate. It still leaves the return value (inline BibTeX string vs. file-only) and overwrite semantics unspecified, which an agent would need when no output schema exists.

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?

Two parameters at 50% schema coverage: the 'write' flag is documented in the schema, while 'tag' has none. The description compensates partially by explaining the filter-by-tag behavior and append the concrete output filename, which adds meaning beyond the bare 'write' boolean. This lands at the baseline 3 given the mixed 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?

States a specific verb and resource ('Render sources as BibTeX'), which is concrete enough to separate it from export_markdown in the sibling list. It does not explicitly name the sibling or contrast with it, so it stops short of a 5.

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 word 'Optionally' hints that filtering and writing are discretionary, but there is no statement of when to use this tool versus export_markdown or the other exporters, and no prerequisites. Usage must be inferred from the parameters alone.

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 no annotations, the description carries the full behavioral burden. It discloses that 'write' produces references.md next to the notebook, which is useful, but it does not state overwrite behavior, required permissions, or what the rendered output contains beyond annotated summaries and quotes.

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 short sentences, front-loaded with the core action and followed by parameter-specific notes. 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?

For a tool with four parameters, no annotations, no output schema, and low schema coverage, the description is too thin. It omits the 'title' parameter and any output/return details, leaving an agent incompletely equipped to 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 only 25% (just the 'write' parameter). The description compensates for 'annotated' (include summaries and quotes) and 'tag' (filter), but never explains the 'title' parameter. This is meaningful added value but incomplete for all four 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?

States a specific verb and resource: 'Render a Markdown bibliography.' This distinguishes it from the sibling export_bibtex by format, but the description never names or contrasts the alternative, leaving sibling differentiation implicit.

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 by noting optional filtering and writing, but it never says when to choose this tool over export_bibtex or any other sibling. Guidance is implied rather than explicit.

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 no annotations the description carries the burden, and it does disclose the output structure and the optional write side effect ('write outline.md next to the notebook'). It omits whether an existing outline.md is overwritten, whether the write requires permissions, and any size or rate constraints.

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

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

A single dense sentence that front-loads the main action and enumerates the artifact contents in a scannable order. No filler, though the optional-filter/write clause is packed into the same sentence rather than separated.

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

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

No output schema, yet the description explains what the returned scaffold contains, which is exactly what is needed. For a zero-required-parameter, read-plus-optional-write tool it is nearly complete; only the 'title' parameter and overwrite behavior are unaddressed.

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 only 33% ('write' has a description). The description compensates for 'tag' (filter) and 'write', adding scenario-level meaning, but gives no hint about 'title', which is undocumented everywhere.

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?

Specific verb ('Assemble ... into a Markdown literature-review scaffold') plus resource and a detailed enumeration of what the artifact contains (theme grouping, cite keys, References, not-yet-written-up list). Clearly distinguishable from siblings like export_markdown or list_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?

The scenario is implied — turn existing notes into a review outline — but no explicit when-to-use or when-not-to-use guidance, and no sibling is named even though export_markdown and notebook_stats sit in the same space and could plausibly be confused with 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?

The readOnlyHint annotation already establishes this as a safe read. The description adds the meaningful detail that the full content (not a summary) is returned, which helps distinguish it from list/search results, but says nothing about missing-note behavior or return size.

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?

One short sentence, front-loaded with the action and resource, with no filler. It is efficient, though terse to the point of omitting needed context.

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

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

There is no output schema, so the description should ideally indicate what fields/format the note content takes; 'full content' gives only a partial picture. For a simple single-param getter, it is minimally adequate but does not fill the gaps left by the undocumented parameter and absent 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 0% and the single 'id' parameter has no description in either the schema or the description text. The description does not clarify whether the id is a note identifier, does not state format, and leaves the agent to infer it from the tool name 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?

States a specific verb ('Show') and resource ('research note') plus scope ('full content of one'), so the agent knows it's a single-item content retrieval. It does not distinguish itself from siblings like get_source or search, leaving differentiation to inference.

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 versus search, list_notes, or get_source. The phrase 'one research note' implies single-item lookup, but there is no explicit when/when-not or alternative routing.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description adds that the response includes quotes, which is useful behavioral context, but it says nothing about failure modes (e.g. unknown id/cite key) or output shape. With annotations covering the safety profile, this is adequate but thin.

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 with no filler; the scope detail (includes quotes) is placed where it is most useful.

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 annotation and full schema coverage, the description covers purpose and return scope adequately. No output schema exists, but 'full detail including quotes' gives a reasonable expectation of what comes back.

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 the single parameter is fully documented in the schema, including both id and cite-key forms. The description adds nothing beyond this, so the baseline 3 applies.

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

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

The description gives a specific verb (show) and resource (one source) plus the notable scope detail that quotes are included. It does not explicitly differentiate itself from siblings like list_sources or search, but the singular 'one source' makes the retrieval-by-id intent clear.

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?

There is no explicit guidance on when to use this versus list_sources, search, or get_note. Usage can be inferred (fetch detail for a known source identifier), but no alternatives or exclusions are named.

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 the safe-read profile is covered. The description adds the scoping constraint that results are notes (not sources), but says nothing about ordering, pagination, or whether an empty filter returns everything.

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 with no filler; the resource is named first and the optional filters follow. Every clause carries 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 zero-required-parameter list tool with no output schema, the description covers purpose and filtering but omits return behavior, ordering, and pagination limits, which an agent would need to call it confidently.

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 50% – `source` is documented in the schema but `tag` is not. The description names both filters and clarifies that source means a 'linked source', adding some meaning, but it gives no matching semantics (exact tag, case sensitivity, cite key format).

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

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

States a specific verb (List) and resource (research notes) plus the filtering scope, so the agent knows exactly what this returns. It does not differentiate itself from the sibling `search` or `list_sources`, leaving the boundary to inference.

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 word 'optionally filtered' implies this is the unfiltered-enumeration entry point, but the description never states when to prefer this over `search` or when a filter is required versus optional. Usage is implied rather than explicit.

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 declaring a safe read, the description adds the filtering capability but no return format, pagination, or ordering details. Adequate given annotations cover safety, but leaves notable behavioral gaps.

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?

One tight sentence with the core action and the optional filter front-loaded. No waste.

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 listing tool with one optional param and no output schema, the description is minimally viable. It's missing pagination/volume expectations and any routing context to siblings, which would help an agent choose 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 only 1 optional parameter at 0% schema description coverage, the description compensates by explaining that 'tag' acts as an optional filter. This adds meaning beyond the bare schema, though it doesn't specify format or matching semantics.

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

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

States a specific verb (list) and resource (sources) with scope (all saved sources). Distinguishes from siblings like get_source (singular retrieval) and search, though it doesn't explicitly name an alternative.

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

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

The description offers no when-to-use guidance and doesn't mention alternatives like search. An agent must infer that this is a broad listing versus targeted search or singular get.

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=true already establishes this is a safe read, so the description's obligation is low. It adds the useful detail that five specific aggregate categories are computed, partially standing in for the missing output schema, but it does not say which notebook is summarised (there are no parameters to scope it) or what the response shape looks like.

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 names the action and then the exact quantities produced. No filler, no repetition of the title or annotations.

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

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

For a zero-param read-only tool this is close to sufficient, but with no output schema the description is the only source for the return contract, and it does not specify the output format, the scope of the notebook being summarised, or whether counts are global or per-notebook 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?

The tool takes zero parameters, so there is no per-parameter semantics to convey; the baseline for a parameterless tool is 4. The description does not need to compensate for any schema gap 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?

States a specific verb (Summarise) plus the resource (the notebook) and enumerates exactly what is counted: sources, notes, quotes, tags, types. No sibling tool does this; the rest are list/get/add/remove/update/export operations, so an agent can distinguish it immediately.

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?

Usage is implied by the purpose — you call this when you want aggregate counts rather than a listing. But there is no explicit statement of when to prefer this over list_sources/list_notes or any exclusion/alternative, so an agent must infer it from the purpose alone.

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 destructiveHint=true, so the safety profile is known. The description adds nothing beyond that: it does not say whether deletion is permanent, whether it cascades to quotes or citations, or whether any confirmation/permission is required. With the annotation bar lower, this is a thin but non-contradictory entry.

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 with no waste. It is appropriately sized for the tool's simplicity, though it is arguably too terse to carry any real 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?

A destructive mutation with no output schema, an undocumented identifier parameter, and no annotation beyond destructiveHint. The description leaves critical questions unanswered: irreversibility, side effects on related data, and expected response.

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?

One parameter ('id') has 0% schema description coverage and the description never explains what kind of identifier it expects — note id vs. source id is genuinely ambiguous given sibling tools like get_note and remove_source. The description provides no compensating detail.

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

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

States a specific verb ('Delete') and resource ('research note'), which cleanly separates it from siblings like remove_source, update_note, and add_note. It never names an alternative, but the purpose itself 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?

No guidance on when to use this instead of update_note (to clear content) or remove_source (to delete a source and its notes). No prerequisites, no warning about irreversibility, no statement of what happens to notes attached to deleted 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 flag destructiveHint=true, yet the description adds real side-effect detail beyond that: linked notes retain their text and the broken link is dropped and reported. This is exactly the kind of consequence disclosure an agent needs before calling a destructive tool. It stops short of stating permanence/undo or required permissions.

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 short sentences, front-loaded with the destructive action followed immediately by the consequence. Every clause earns its place with 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?

For a single-parameter destructive tool with no output schema, the description covers the operation and its key side effect, and the annotation covers destructiveness. Minor gaps remain around reversibility and failure behavior, but an agent has enough to call 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% and the single parameter is fully documented (source id or cite key) in the schema itself. The description adds no additional format or matching semantics, 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?

States a specific verb ("Delete") and resource ("a source"), which cleanly separates it from siblings like remove_note, update_source, and add_source. An agent can identify the operation without opening the schema.

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 delete semantics imply usage, but no explicit when-to-use guidance or alternatives (e.g., update_source for edits, get_source for inspection) are given. Nothing is misleading, but routing conditions are left to inference.

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 establish readOnlyHint=true, so the safety profile is covered. The description meaningfully adds the searchable surface and the return contract (cite keys and note ids), which an agent needs to interpret results. It stops short of noting ranking order, result caps, or case/matching 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, no filler, with the searchable facets front-loaded and the return values trailing. Every clause carries 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?

With no output schema, the description rightly discloses what comes back (cite keys and note ids), which is the key missing piece for a caller. For a one-parameter read tool this is nearly sufficient; only ranking/limit behavior is unstated.

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 single 'query' param is documented as 'Text to search for.'), so the baseline is 3. The description's enumeration of which fields are matched adds useful scope context but no syntax or matching semantics beyond what the schema already 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?

States a specific verb (full-text search) and enumerates the exact resource facets searched — sources by title/authors/journal/tags/quotes/summary and notes by title/content/tags. It also names the return shape (cite keys and note ids), so an agent can distinguish it from list_sources, list_notes, and get_source/get_note without opening a schema.

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

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

The description implies the use case (you have a text query and want matching entities), but never states when to prefer this over the sibling list_* tools for browsing or get_* for known keys, and gives no exclusions, prerequisites, or scope limits. Adequate but leaves routing to inference.

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 no annotations provided, the description carries the full behavioral burden. It helpfully discloses partial-update semantics ('Omitted fields are unchanged'), which is meaningful beyond the schema. However, it omits permission requirements, whether changes are destructive/reversible, and any response or side-effect 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?

Two short sentences, front-loaded with the action and affected fields, with no wasted wording. The partial-update rule is compactly stated.

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 mutation tool with no annotations and no output schema, the description covers the essential field list and partial-update behavior. It still leaves out permissions, error behavior, and what a successful update returns, so it is only minimally 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 60%, so the description should add meaning beyond the schema. It lists the updatable fields and adds partial-update behavior, but does not explain the required id, tag format, or that sources replacement is destructive to prior links. It is adequate but not fully compensating for the uncovered 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 states a specific verb ('Edit') and resource ('a note') and enumerates the updatable fields: title, content, tags, linked sources. It clearly distinguishes update_note from read/list/add/remove sibling tools, though it does not explicitly name those siblings.

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

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

The description gives no when-to-use guidance, no prerequisites, and no alternatives. It implies mutation of an existing note but does not say when to choose update_note over update_source or other 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?

With no annotations, the description must carry the behavioral burden. It does disclose the important partial-update semantics ('Omitted fields are unchanged'), which is real value for a mutation tool. It says nothing about auth requirements, failure behavior, or whether changes are reversible.

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 tight sentences with the partial-update rule front-loaded and, in fact, stated as the second sentence where it matters most. No filler, nothing that fails to earn 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 10-parameter mutation tool with no annotations, no output schema, and 30% schema coverage, this is thin: it omits which fields are updatable, whether id-like fields (doi, url) can be changed, and any failure or permission behavior.

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 only 30% across 10 parameters, so the schema leaves seven fields undocumented. The description offers only the generic phrase 'bibliographic fields' with no per-field meaning, so it does not compensate for the coverage 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 states a specific verb set ('correct or enrich') and a clear resource ('a source's bibliographic fields'), which cleanly separates it from update_note, add_source, and get_source. It lacks any explicit sibling reference, but the resource scope 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?

'Correct or enrich' implies this is for fixing or augmenting an existing source rather than creating one, which implicitly distinguishes it from add_source. Nothing states when to prefer update over re-adding, preconditions, or what happens if the source id is unknown.

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