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 the categories of structural problems checked, but does not clarify whether the tool is read-only, whether it reports or fixes issues, or what side effects or output the agent should expect.

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

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

The description is a single front-loaded sentence with no wasted words. It is appropriately concise for the information it chooses to include.

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 annotations, no output schema, and 0% parameter description coverage, the one-sentence description is insufficient. It leaves important context about parameter usage, read-only behavior, and expected outcomes unspecified.

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

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

Both parameters ('file' and 'name') have zero schema description coverage, and the description does not mention either parameter or explain their roles or defaults. There is no compensation for the missing schema semantics.

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

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

The description uses a specific verb ('Check') and resource ('references.bib') and enumerates the structural problems detected (brace balance, duplicate or empty keys). It is clear what the tool does, but it does not distinguish itself from siblings such as paper_lint or paper_doctor.

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 tool versus alternatives like paper_lint or paper_doctor, nor are prerequisites or exclusions stated. Usage must be inferred 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not explain whether an existing references.bib is overwritten, what the 'force' parameter does, what 'starter' content is generated, or what prerequisites exist.

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

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

The description is a single front-loaded sentence with no wasted words. However, its extreme brevity leaves important invocation details unstated, though that is better assessed under contextual completeness.

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 file-creation tool with no annotations, no output schema, and undocumented parameters, this description is far too sparse. An agent cannot confidently determine overwrite behavior, required context, or parameter meaning from the definition alone.

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 description says nothing about the two parameters. It does not clarify what 'name' refers to (paper name, file name, or identifier) or what 'force' controls.

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: 'Create a starter references.bib'. It is clear what the tool does, but it does not explicitly distinguish itself from siblings like paper_bib_check or paper_init.

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 tool versus alternatives such as paper_init, paper_templates, or paper_bib_check. The description gives only a bare statement of purpose with no context or exclusions.

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

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

With no annotations, the description has to carry the behavioral burden. 'Resolve' implies a lookup that returns a BibTeX key, but the description does not explicitly confirm read-only behavior, failure handling, ambiguity behavior, or whether any state changes occur.

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 tightly written sentences, with the core action stated first and the usage condition second. There is 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 identifies the return value as a BibTeX key and gives a clear use case, which is helpful given there is no output schema. However, it leaves the 'name' parameter unexplained and does not describe what happens when resolution fails or is ambiguous.

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 50%, and the description mostly repeats the identifier examples already present in the schema. It does not explain the undocumented 'name' parameter and omits that 'key' is also accepted by the schema description.

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

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

The description gives a specific verb and resource: 'Resolve a DOI/arXiv id/title ... to its BibTeX key.' That is clearly a citation-key lookup rather than a generic paper operation, but it does not explicitly distinguish this tool from nearby siblings such as paper_bib_check or paper_bib_init.

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 a clear usage condition: 'Use this before citing a record whose key you do not know.' That is strong positive guidance, though it does not mention when not to use it or name an alternative tool for related cases.

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 does disclose the key state change: the session corpus is discarded and discovery mode reverts to cwd/config. It does not say whether closing an already-closed corpus is an error, whether the corpus state is recoverable, or what is returned, which matters for a state-clearing operation.

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 short sentence with the action front-loaded and the effect trailing. No filler, nothing to trim.

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-parameter, no-output-schema tool, the description covers what it does and what state changes. A brief note on what happens if no corpus is active would make it fully self-contained.

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 nothing for the description to disambiguate. Baseline 4 applies; no parameter information is missing or 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?

States a specific action (close/forget the session corpus) and its consequence (return to cwd/config discovery). It implicitly contrasts with the sibling paper_open_corpus, but never names it, so the pairing has to be inferred rather than read.

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 only implied: an agent can infer this is used when finished with a session corpus or wanting to fall back to path-based discovery. There is no explicit when/when-not guidance and no sibling named. Adequate but leaves the routing decision 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, the description must carry behavioral disclosure. It usefully states that the response is compact and bounded by `budget` tokens, but it does not explicitly confirm read-only behavior, side effects, permissions, or error handling.

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

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

Two sentences, front-loaded with what the tool returns, followed by the key invocation guidance. There is no wasted wording.

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 no output schema, the description adequately summarizes the return payload's major components and notes the token budget. It could be slightly more complete about optional corpus/name behavior, but the schema covers that parameter detail.

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 `name` and `budget` are already documented in the schema. The description reinforces that `budget` bounds token usage but adds little beyond the schema's own parameter documentation.

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

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

The description states a specific resource and enumerates its contents: front matter summary, outline, citation keys, diagnostics, and house style. It also distinguishes itself as the best first call, which helps it stand apart from the many paper_* 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?

It gives clear usage context by calling itself 'the best first call,' which helps an agent choose it before section-level or linting tools. It does not name specific alternatives or when-not-to-use conditions, so it falls short of full explicit 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?

With no annotations, the description carries the full behavioral burden. It does valuable work by defining the meaning of a successful result ('ok means a render actually succeeded, not just that quarto exists'), which is exactly the kind of context annotations could not provide here. It does not disclose side effects such as where the minimal document is written, whether artifacts are left behind, or how failure is reported.

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 sentence with no filler; the action comes first and the crucial interpretation of the result follows the semicolon. Every clause adds 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?

For a zero-parameter diagnostic with no output schema, the description covers the essentials: what is run and how to interpret success. It stops short of describing the failure shape or any filesystem effects, which the agent would still have to discover by calling it.

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

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

The tool takes zero parameters, so the baseline is 4 and there is nothing in the schema that the description needs to compensate for. Nothing in the description conflicts with the empty parameter list.

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: probe the render toolchain by rendering a minimal document. It implicitly distinguishes itself from paper_render by framing the render as a probe rather than a real build, though it never names paper_render as the alternative. The agent can tell what the tool does 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?

Usage is implied by the diagnostic framing ('probe', 'ok means a render actually succeeded'), suggesting this is a sanity-check tool to run before real renders. However, there is no explicit when-to-use statement, no mention of when to prefer paper_render instead, and no note about when this check should be repeated.

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 burden, and it does disclose the concrete side effect of writing config, _quarto.yml and a papers/ directory. It does not say whether existing files are overwritten, what happens on a non-empty directory, or what the `force` flag changes, so the destructive/overwrite profile stays unstated.

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 compact sentence with the action front-loaded and no filler. It is arguably too terse for a 4-parameter mutating tool, but every word present 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 file-creating initializer with four undocumented parameters, no annotations and no output schema, the description is missing overwrite/force behavior, engine selection meaning, target directory semantics, and what the tool reports back. The agent cannot call this confidently without guessing.

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%, so the description must compensate, but three of four parameters (force, engine, directory) get no mention at all. Only 'papers/' loosely hints at papers_dir, leaving the enum choice for engine and the semantics of force entirely undocumented.

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 ('Initialise a paper corpus') and enumerates the artifacts produced (config, _quarto.yml, papers/ directory). This implicitly separates it from paper_open_corpus/paper_close_corpus, though it never names those siblings explicitly.

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 indication of when to call this versus paper_open_corpus, paper_new, or paper_bib_init, and no noted prerequisites (e.g. must the corpus be absent or already exist). The agent must infer positioning from the name 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 burden, and it does disclose one genuinely useful behavioral trait: output is truncated to `max_issues` while the counts remain complete, which tells the agent how to interpret partial results. It omits much else — that this is a read-only diagnostic, what document/scope is linted when no `name` is supplied, and roughly what the issues look 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?

Two sentences, zero filler: the check list comes first and the truncation semantics second. Every clause carries information the agent can act on.

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 no annotations, no output schema, and zero schema description coverage, the description should clarify target selection and result shape. It leaves `name` undefined and never says what an issue record contains or what scope is linted by default, so an agent could call it with the wrong target.

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%, so the description must compensate and only partly does. `max_issues` is well explained (cap on returned issues, counts unaffected), but the `name` parameter is never mentioned at all, leaving the agent guessing whether it targets a paper, a section, or the active corpus.

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 names a specific operation (lint) and enumerates the exact checks performed: placeholders, heading hierarchy, missing sections, paragraph/sentence length, abstract length, undefined citations, readability. That is far more specific than the bare name. It stops short of differentiating itself from the sibling paper_doctor, which plausibly overlaps, so an agent cannot be fully sure which to pick without opening both.

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 when-to-use guidance, no exclusions, and no named alternative despite paper_doctor and paper_bib_check being close siblings. The agent must infer that this is the thing to run after writing content, but nothing in the text says so.

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. 'List' strongly implies a read-only operation, and the description adds useful cost context, but it does not explicitly confirm no side effects, pagination behavior, or access requirements.

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 tightly written sentences with no wasted words. The core action is front-loaded, and the usage hint directly follows in a natural reading order.

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-parameter listing tool with no output schema, the description adequately states the returned fields and the tool's intended primary role. Minor gaps like ordering or pagination are not covered, but they are low-risk for this simple operation.

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 has zero parameters, so per the baseline rule a 4 is appropriate. There are no parameter semantics to clarify, and the description correctly avoids implying any inputs.

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 ('List the papers in the corpus') and enumerates the returned fields (title, status, engine, render state, word count), making the tool's scope immediately clear. It also distinguishes itself from paper-reading siblings by saying it is cheaper than reading any paper.

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 explicit usage context with 'Start here' and a clear cost-based comparison ('much cheaper than reading any paper'), which routes the agent away from read tools. It does not name specific alternative sibling tools or state when not to use it, so it falls short of a perfect 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?

No annotations are provided, so the description carries the full behavioral burden. It discloses the important fallback behavior when key is omitted and clearly frames this as a read operation, but it omits error behavior for missing keys, permissions, and what the name parameter does.

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 sentence with no wasted words. The core action and the key-omitted behavior are front-loaded 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?

With no annotations, no output schema, and zero schema description coverage for two parameters, the description is too thin. It leaves the name parameter unexplained and provides no return-value or error context for a tool whose behavior is otherwise undocumented.

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%, so the description must compensate. It explains the key parameter and the omit-key fallback, but it entirely ignores the second parameter, name, leaving an undocumented required piece of invocation 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 and resource: read a front-matter key or the whole front matter. This clearly distinguishes it from the write counterpart, paper_meta_set. It is slightly domain-specific but still understandable 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 description implies when to use it and clarifies the omit-key behavior for reading all front matter. However, it does not name alternatives, prerequisites, or when not to use it compared with 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 carries the full burden. It usefully discloses that values are parsed as YAML and gives conversion examples, which is meaningful behavioral context. However, it does not state whether setting an existing key overwrites it, what permissions are required, or what happens on parse failure.

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 followed by a useful parsing rule. 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 mutation tool with no annotations, no output schema, and 0% schema description coverage, the description is too sparse. It omits the optional 'name' parameter, overwrite behavior, error handling, and output expectations.

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%, so the description must compensate. It explains value semantics well through YAML parsing examples and implies key meaning, but it never mentions the optional 'name' parameter at all, leaving one of three parameters undocumented.

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: 'Set a front-matter key.' This clearly distinguishes it from paper_meta_get by action, though it does not explicitly name alternatives. The added YAML parsing note reinforces what operation is being performed.

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 tool versus alternatives such as paper_meta_get, nor any prerequisites or exclusions. Usage is only implied by the imperative 'Set a front-matter key.'

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 burden. It helpfully discloses the return value ('Returns the entry path'), but says nothing about the destructive potential of the `force` parameter, what happens on name collision, or where templates come from — all critical for a scaffolding mutation.

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 immediately followed by the return contract and next step. Nothing is wasted.

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?

It covers the return value, which matters since there is no output schema, so the tool is callable for the happy path. But for a five-parameter mutation with no annotations, the silence on overwrite/force behavior and template enumeration leaves real gaps.

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

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

Schema description coverage is only 20% (just `name`), and the description adds no meaning for the other four parameters. `force`, `title`, `engine` (enum typst/latex/both), and `template` are left entirely to inference, and the description does not even point at paper_templates as the source of template values.

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 ('Scaffold a new paper from a template') and names the follow-up sibling paper_write_section. However, it never distinguishes itself from paper_init or paper_templates, which an agent would plausibly consider for the same intent.

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 second sentence implies a workflow ('then write it section by section with paper_write_section'), which hints this is step one of a sequence. There is no explicit guidance on when to pick this over paper_init, or what to do if the paper already exists.

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 usefully discloses that the pinning is scoped to 'this MCP session' and that the path may be either a corpus root or a papers/ directory. However, it does not explain override behavior, validation failures, or whether a prior pin is required before other tools, leaving meaningful gaps for a stateful operation.

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 with no wasted text. The core action and accepted path forms are front-loaded, followed immediately by the usage condition.

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 state-setting tool with no annotations or output schema, the description gives enough to select and invoke it: what it does, accepted path forms, and the triggering condition. It could be stronger by noting what happens if the corpus is already pinned or if the path is invalid, but 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 description coverage is 0%, so the description must compensate for the sole parameter. It adds useful domain meaning by saying 'path' may be 'a corpus root or a papers/ directory', but it does not specify whether the path should be absolute, relative, or a concrete example.

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 and resource: 'Pin a corpus for this MCP session', and clarifies the accepted forms ('a corpus root or a papers/ directory'). It is distinguishable from sibling tools like paper_close_corpus by its session-pinning action, though it does not explicitly name or contrast with that sibling.

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 a clear trigger for use: 'when the server was launched outside the corpus.' This tells the agent the condition under which the tool is needed. It does not explicitly state when not to use it or name paper_close_corpus as the alternative, so it falls short of full routing 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?

With no annotations, the description carries the full burden, and it does disclose the returned content (heading tree, per-section word counts, missing standard sections) rather than just restating the name. It says nothing about error behavior, whether the 'name' must match an existing paper, or how word counts are computed.

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 what is returned and followed by the cost rationale. Every clause carries information; nothing is padding.

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

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

For a simple read-only tool with no annotations and no output schema, describing the return shape is the right move and it is done. Gaps remain around the sole parameter's meaning and failure/precondition behavior, which an agent needs 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 coverage is 0% for the single 'name' parameter, and the description never explains what it refers to — a paper name, file, or section identifier. With one undocumented, undescribed parameter, the description should compensate and does not.

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

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

Names a specific resource and its contents: the heading tree with per-section word counts plus missing standard sections. It is a noun phrase rather than a verb, but the returned artifact is unambiguous and implicitly contrasted with reading the paper. It only partially distinguishes itself from siblings like paper_read_section or paper_lint.

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 phrase 'Cheaper than reading the paper' implies a cost-based heuristic for choosing this over full reads, which is genuine usage guidance. However, no sibling tool is named and there are no explicit when/when-not conditions or prerequisites (e.g. whether the paper must exist).

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 one meaningful behavior: output is truncated to `max_tokens` (default 1200). However it is silent on what happens if `heading` doesn't match an existing section, whether matching is exact or fuzzy, and whether `name`/`level` scope the lookup.

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 core action and followed by the disambiguation. No filler, though the extreme brevity leaves no room for the parameter clarifications the schema needs.

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 4-parameter tool with zero schema descriptions, no annotations and no output schema, the description is too thin: it leaves half the parameters undefined and gives no indication of return shape or failure behavior when a heading is not found.

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% with 4 parameters, and the description only illuminates `heading` and `max_tokens`. The `name` and `level` parameters are completely undocumented — an agent cannot tell whether `name` is a file path, corpus entry, or paper title, or what `level` means for heading selection.

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 — 'Read exactly one section (heading plus body)' — plus the truncation limit, which is more precise than the tool name alone. It implicitly distinguishes itself from whole-file reads, though it doesn't name a specific sibling (e.g. paper_context or paper_outline) that an agent might confuse it with.

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 instead of reading the whole file' gives a directional preference, but there is no named alternative tool and no statement of when this tool is inappropriate (e.g. when the section is unknown or when a full outline is needed). Usage is implied rather than fully specified.

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 burden. It usefully discloses the return payload (output path, size) and that failure surfaces only a short stderr tail rather than the full Quarto log — a genuinely useful expectation-setting detail. However, it never states that this is a write operation, whether existing PDFs are overwritten, or what permissions/environment it requires.

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 is rendered and how to widen scope, followed by the return-value caveat. Nothing is padded or redundant.

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 compensates for the absent output schema by describing return values, and clarifies the all/name scope. But with no annotations and 0% parameter coverage, the engine selection and keep_going semantics — which materially affect behavior — remain undocumented, leaving the definition incomplete for a 4-parameter tool.

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

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

Schema description coverage is 0%, so the description must document the four parameters, but it only explains 'all' (and implicitly 'name'). The 'engine' enum (typst/latex/both) and 'keep_going' are left entirely unexplained in both schema and description.

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

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

The description names a specific verb ('Render') and resource ('one paper / the whole corpus') with a concrete output format (PDF), so an agent immediately knows what the tool produces. The single-paper vs. corpus distinction is explicit, though there is no sibling render tool to differentiate against.

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 the two modes ('one paper' vs. 'whole corpus with all=true'), which implies usage, but gives no when-not guidance, no prerequisites (e.g., Quarto must be installed), and no guidance on choosing an engine or when to use keep_going.

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 exist, so the description carries the full burden. It does disclose two real behavioral traits: output is size-bounded by `budget`, and the full bundle is deliberately never returned. It says nothing about prerequisites (must the paper be imported first?), failure modes, or what 'screening' counts represent, which leaves significant gaps for a tool with zero annotation coverage.

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 payload contents and followed by the bounding constraint. Slightly redundant wording ('Compact' + 'brief') but no filler sentences.

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

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

With four undocumented parameters, no annotations, and no output schema, the description must do more. It never defines what the brief looks like (structure of counts/screening), what citation keys are keyed to, or how the tool fails on an un-imported paper – all essential for correct 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 0% – all four parameters appear with types and defaults only. The description explains `budget` as the size bound and loosely maps 'top core papers' and 'citation keys' to max_papers/max_keys, but `name` is entirely unexplained and the interaction between budget and the two caps is not described.

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 names the resource (an evidence brief for an imported paper) and enumerates its contents: counts, screening, top core papers, citation keys. It is clearly distinct from write/import siblings, but the near-identically named sibling paper_context is never addressed, so an agent cannot tell the two apart from the text alone.

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 statement of when to call this versus paper_context, paper_meta_get, or paper_research_prisma. The only implicit routing cue is 'never returns the bundle', which hints at a summary-vs-full-bundle distinction but never names the alternative tool or the precondition (e.g., that research must already be imported).

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. It does add one genuinely useful safety fact — 'The manual references.bib is never overwritten' — which tells the agent the manual bibliography is preserved. But it omits what happens when the target paper already exists, what force actually does, whether other files can be clobbered, and what the tool returns, which are material gaps for a scaffolding/write operation.

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 action, and the safety constraint is placed immediately after. Every sentence earns its place with no boilerplate.

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 six-parameter, non-annotated, no-output-schema tool that scaffolds a project and mutates bibliographies needs more than two sentences. Missing is any account of the force/overwrite semantics, engine/template behavior, what the handoff bundle contains, what files are created, and how it relates to paper_new or paper_bib_init. The one safety note is not enough to make the definition callable with confidence.

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 33%: name and handoff have brief descriptions, while force, title, engine, and template are undocumented in both schema and description. The description adds no parameter meaning at all — it never explains that engine selects typst/latex/both, that template defaults to research-article, or that force controls overwriting. With low coverage the description needed to compensate and does not.

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

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

The description states a specific verb and resource: 'Scaffold a paper from a researcher-python handoff bundle and wire its bibliographies.' This is clearly distinct from generic creation siblings like paper_new or paper_init because it names an input artifact (handoff bundle) and a secondary effect (bibliography wiring). It stops short of 5 because 'researcher-python handoff bundle' is unexplained jargon and it never explicitly contrasts itself with paper_new/paper_init/paper_research_sync.

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 rather than stated: the agent can infer this tool is for the case where a handoff bundle exists. There is no explicit when-to-use vs. paper_new, paper_init, or paper_research_sync, and no when-not guidance (e.g., what to do if the paper name already exists).

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 burden, but it does disclose two meaningful traits: the operation is idempotent ('insert or replace') and it targets a named artifact (research/prisma.md). It does not say whether an existing appendix's content is destroyed, whether the source PRISMA file must already be generated, or what the response 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?

One sentence, front-loaded with the verb and the key qualifier, with zero filler. It is efficient but so terse that it leaves little room for the usage context that is missing elsewhere.

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 four-parameter write tool with no annotations and no output schema, the description should cover prerequisites, the effect on existing content, and what the optional parameters mean. It covers only the high-level outcome, so an agent would have to guess at everything else.

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% — only 'after' is documented — and the description does not mention name, level, or heading at all. Given that low coverage, the description is expected to compensate, and it does not; the agent learns nothing about how heading/level govern the appendix structure.

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 concrete verb pair ('insert or replace') and a concrete resource ('Quarto appendix' containing the PRISMA screening flow from research/prisma.md'), so the agent knows exactly what artifact is produced. It does not differentiate itself from near-neighbours like paper_write_section or paper_render, which is the only thing keeping it below 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?

There is no guidance on when this should be called versus paper_write_section, paper_render, or paper_research_sync, and no prerequisites are stated. The only hint is implicit in 'insert or replace', which suggests re-running is safe, but nothing tells the agent when the PRISMA block is expected to exist.

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 disclosure burden and does add real value by scoping what is untouched (manuscript text and manual references.bib). It does not say whether existing generated research/ files are overwritten or deleted, whether the paper must already exist, or what happens if the supplied bundle is older rather than newer.

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 the action and followed by the explicit non-impact statement; no filler. It is arguably too terse given the operational ambiguity, but nothing present is wasted.

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-style refresh with no annotations, no output schema, and an undocumented `name` parameter, the description leaves out overwrite semantics, prerequisites, and the resulting file set. The safety-adjacent claim about untouched files is helpful but does not cover what an agent needs to invoke this correctly alongside paper_research_import.

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 50%: `handoff` is documented in the schema itself, and the description only adds the 'newer' qualifier. The `name` parameter is undocumented in both the schema and the description, so the agent must guess whether it identifies the paper and whether it is optional or derived from context.

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

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

Names a specific verb and resource ('Refresh a paper's generated research/ files') plus the source ('newer handoff bundle'), which is more precise than the title. It doesn't distinguish itself from the closely-named sibling paper_research_import, so an agent can't fully tell the two apart from the description alone.

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 phrase 'from a newer handoff bundle' implies the trigger condition (a newer bundle exists for the paper), which is useful implicit guidance. However, it never states when NOT to use it, or how it differs from paper_research_import or paper_research_context, leaving the agent to infer the 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?

With no annotations, the description carries the full burden of behavioral disclosure. It implies read-only behavior through 'List' and discloses that templates come from built-in and corpus-local sources, but does not address permissions, ordering, return structure, or other operational traits.

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

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

The description is a single front-loaded sentence with no wasted words. It states the action and scope immediately.

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-parameter list tool without an output schema, the description covers the essential purpose and source distinction. It could do slightly more to clarify expected output or template meaning, but it is largely complete for this complexity level.

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 has zero parameters, so parameter semantics are not applicable and the baseline score is 4. The description does not need to explain any input 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 uses a specific verb ('List') and two clearly scoped resources ('built-in and corpus-local paper templates'). It is clear what the tool does, though it does not explicitly differentiate itself from any sibling tool.

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

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

The description provides no guidance on when to use this tool versus alternatives, nor any prerequisites or exclusions. Usage is only weakly implied by the verb 'List' and the mention of template 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?

No annotations are provided, so the description carries the full burden. It usefully discloses that the abstract is stored outside section flow and that the result includes word count and diagnostics, but it does not state whether an existing abstract is overwritten, what permissions are needed, or other mutation side effects.

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

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

The description is front-loaded with the action and resource, followed by useful placement and return-value context. Every clause contributes information 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?

For a simple two-parameter mutation tool with no annotations or output schema, the description covers purpose, placement, and a return hint. It remains incomplete on parameter semantics and mutation behavior such as overwriting an existing abstract.

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 description does not explain the parameters. It implies that the abstract content is passed as text, but the optional 'name' parameter is entirely undocumented in both schema and description.

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

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

States a specific verb and resource: 'Set the front-matter abstract.' It also distinguishes this from section writing by saying the abstract stays out of the section flow, which helps separate it from sibling tools like paper_write_section.

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 implied usage context by saying this is for front-matter abstracts rather than section flow. However, it does not explicitly say when to choose this over paper_write_section, nor does it mention prerequisites or exclusions.

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

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

With no annotations, the description carries the full burden, and it usefully discloses the return shape (small receipt plus updated outline, not the whole document). However, it omits failure behavior when a heading is absent and create=false, and says nothing about permissions or reversibility of the replace operation.

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 no waste, front-loading the core action and the output expectation. Slightly under-elaborated, but nothing redundant.

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?

Return behavior is covered despite no output schema, which is valuable. But for a tool with 8 parameters, no annotations, and half the params undocumented, the description leaves too much (name, level, insert anchoring, create fallback) 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 50%, so the description must compensate; it clarifies content (markdown body, no heading line) and names the three modes. It leaves the undocumented 'name' parameter, 'level', and the after/before interplay for insert entirely unexplained.

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 specific verbs (replace, append, insert) and the resource (a section), plus a scoping detail that content is markdown without the heading. It does not explicitly differentiate from paper_write_abstract or paper_read_section, so an agent must infer that this is the generic section writer.

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 three modes are listed, implying when one might be used, but there is no explicit guidance on choosing replace vs append vs insert, no prerequisites (e.g., create=true needed for new headings), and no mention of the paper_write_abstract alternative.

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