bugcap

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

Goes well beyond the annotations by disclosing that files are copied into a local store, URLs are downloaded, existing media is preserved, and nothing is uploaded to GitHub — important context given openWorldHint=true. It also documents partial-failure semantics ('one bad source does not stop the others'), which annotations never convey.

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

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

Front-loads purpose and the sibling exclusion, then layers behavior. Dense but nearly every clause earns its place; the return-shape sentence partially duplicates the output schema, a minor redundancy.

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

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

With an output schema present and annotations covering safety profile, the description supplies the remaining essentials: storage behavior, GitHub exclusion, and partial-success handling. An agent has everything needed 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 100%, so the baseline is 3, but the description adds meaning beyond the schema by explaining that labels let notes refer to items as @label and that failures are reported per source. It doesn't restate the 1-to-20 source limit or glob syntax, which the schema already covers.

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 ('Add files ... to a bug report as supporting evidence') and enumerates the file types accepted. It explicitly distinguishes itself from the sibling attach_image and its output target (get_report).

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?

Gives an explicit routing rule: use attach_image for pictures so they are returned as images by get_report, implying this tool for everything else. The @d<n>/@label referencing note also tells the agent how attachments are consumed downstream.

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 cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), and the description adds real behavior beyond them: images are copied into a local store, URLs are downloaded, existing media is preserved, and partial failure is tolerated. It also discloses the reference convention (@i<n> or @label) that the agent needs for later note updates.

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?

Front-loaded with purpose and alternatives, then behavior — good ordering with no filler sentences. Slightly over-packed because it spells out the full return JSON shape, which the output schema already provides.

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 annotations covering safety, full schema coverage, and an output schema present, the description supplies everything else an agent needs: accepted formats, source kinds, mutation semantics, partial-failure behavior, and the labeling convention. Nothing required for correct invocation is missing.

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

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

Schema coverage is 100%, so the schema already documents id, labels and sources. The description still adds value by explaining how labels are consumed downstream (notes referring to @label) and that source failures are per-item rather than all-or-nothing, though it does not restate the 1-20 item or glob limits.

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

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

States a specific verb (add/attach) and resource (existing images) with the accepted formats and scope (into a bug report). It explicitly distinguishes itself from attach_file and request_screenshot, so an agent can pick correctly among siblings without opening schemas.

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?

Names both alternatives and the exact condition that selects each: attach_file for logs/videos/non-image files, request_screenshot when the user must take the picture. No exclusions 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?

The description adds substantial behavioral detail beyond the readOnlyHint/openWorldHint annotations: screenshots are returned as image content, notes use @i1/@d1/@label references, resolved_references maps those tokens, and an {"error": ...} object is returned when the id is missing. It also states the tool is 'Read-only and local,' confirming the annotations rather than contradicting them.

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?

It is front-loaded with the core action and return contents, followed by the workflow hint and the token-mapping detail. Every sentence contributes useful information, and there is no redundant restatement of the title or schema.

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

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

Although there is no output schema, the description explains the returned report fields, embedded image behavior, token-to-media mapping, and the error shape for a missing id. For a one-parameter read tool with readOnlyHint and openWorldHint=false annotations, this is complete enough to call 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?

The schema has 100% description coverage for the single id parameter, including its numeric type and example. The description adds only the missing-id error behavior, not additional syntax or format detail beyond the schema. Baseline 3 is appropriate when the schema already documents the parameter fully.

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 and resource: 'Read one bug report in full,' then enumerates exactly what is returned, including title, body, notes, status, tags, linked GitHub issue, attached media, and embedded screenshots. It also distinguishes the tool's role from list_reports by positioning this as the follow-up read after listing.

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 guidance: 'Use this after list_reports to understand a bug before fixing it.' This establishes the intended workflow and timing. It does not explicitly name when not to use it or mention alternative sibling tools such as request_screenshot, so it falls short of full when/when-not guidance.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=false, and the description largely restates that ('read-only and local: no network access') rather than adding new safety facts. It does add genuinely new behavior, though: it enumerates the exact summary fields returned, warns that notes and images are omitted, and states that an empty JSON array is returned when nothing matches.

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

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

Four short sentences, front-loaded with the purpose, then the return shape, the alternative, and the safety note. Nothing is buried and no sentence is filler, aside from a mild restatement of read-only.

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?

An output schema exists, yet the description still summarizes the returned summary fields and the empty-result case, and it points to get_report for full detail. Combined with full parameter coverage in the schema, an agent has everything needed 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%, so all three parameters (all, limit, status) are already fully documented in the schema. The description only echoes the ordering implied by 'limit' ('newest first') and says nothing about the repo-scope flag 'all' or status filtering, so it adds little beyond the schema.

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

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

States a specific verb and resource ('List bug reports stored by bugcap') plus ordering ('newest first'). It also carves out exactly what the sibling get_report does instead, so the agent can distinguish the two without inspecting schemas.

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

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

Explicitly says the intended use is 'to find a report id' and names the alternative ('call get_report for the full report') with the condition that selects it (need notes/images). This is a clear when-to-use plus when-to-use-something-else routing statement.

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?

Goes well beyond the annotations: it discloses the auth dependency (GitHub API via the user's `gh` login), the precise idempotency semantics (existing imports refresh only title and body, never notes/tags/status), and the return/error shape including the no-repo and not-signed-in failure modes. The idempotentHint is confirmed and fleshed out rather than repeated.

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?

Front-loads the action and scope in the first clause, then layers the when-to-use, auth mechanism, idempotency guarantee, and return shape in a tight sequence with 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?

Covers purpose, prerequisites (gh auth, repo config), repeat-safety, and error conditions; an output schema exists but the description still summarizes the count/error shape, which is sufficient 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 100%, so repo fallback to .bugcap.toml, the limit default, and label AND-filtering are already documented in the schema. The description adds only the repo-default behavior, which is duplicative; limit and labels go unmentioned. 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 and resource ("Import open GitHub issues into bugcap as reports") and immediately clarifies the resulting object type is readable via get_report, distinguishing it from the read-only siblings like list_reports and get_report.

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?

Gives an explicit selection condition: "Use this when the bug you need lives in GitHub rather than in bugcap yet," plus the follow-on path (read imported issues with get_report, attach screenshots to them). That routes the agent between this importer and the report-reading siblings without 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 only declare safe non-destructive mutation; the description adds substantial behavior: it opens the user's capture tool, blocks until completion/cancel/timeout, may create a report for an issue, and lists exact return statuses including 'non_interactive' for SSH/container environments. That goes well beyond 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?

Front-loaded with the core action, then usage, blocking behavior, side effects, and return values. Each sentence contributes distinct information and there is no repetition.

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

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

Covers all the hard parts: blocking semantics, side effects, alternative tool, environmental failure mode, and return shape. With no output schema, the description fully explains outcomes.

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 parameters are already documented in detail. The description adds only high-level references to timeout and report creation, which the schema already states; 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 and resource ('ask the human... to take a screenshot') and explicitly distinguishes it from the sibling attach_image. Examples of when the resource is useful reinforce the purpose without ambiguity.

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

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

Explicitly says when to use it ('when you need visual evidence you cannot produce yourself') and names the alternative ('to attach an image file that already exists, use attach_image'). No inference required.

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

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

Annotations declare destructiveHint/readOnlyHint/openWorldHint, but the description still adds materially non-obvious behavior: replace-not-append semantics, atomic rejection on unknown @ references versus tolerant handling of unknown #report links, where warnings appear, and the 'Local only' constraint. It does not contradict any annotation — 'Local only' is consistent with openWorldHint=false.

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?

Dense and front-loaded: the destructive semantics come first, followed by reference rules, then constraints. The only wasted sentence is the explicit return-shape listing, which duplicates the existing output schema and could be dropped.

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

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

Covers what an agent needs before a destructive overwrite: read first, what counts as a valid reference, atomicity on failure, and local-only scope. With an output schema present, the return-value recap is redundant but not misleading, and no call-critical gap remains.

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

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

Schema coverage is 100%, and the schema already documents id and notes including @i1/@d1/@label syntax, so the baseline is 3. The description adds real meaning beyond that: the @ must match media attached to the report, `#12` links another report, and invalid link handling is explained — but it never clarifies `label` resolution or whether `id` accepts anything other than the list_reports form.

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?

Opens with a specific verb+resource+scope: "Overwrite a bug report's notes with new text", then distinguishes the operation from its sibling by naming get_report for reading. The example use cases (diagnosis, repro steps, fix changes) pin down intent without ambiguity.

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

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

Explicitly routes the agent to get_report before calling and explains why (previous notes are replaced, not appended). It also states the consequence of a bad @ reference (rejected, nothing saved) versus a bad #report link (kept, surfaced in warnings), which is prescriptive guidance rather than bare description.

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