buddie

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

Beyond the readOnly and non-destructive annotations, it discloses the grant model, that requests cannot grant consent, that approval of this call is not a grant, that denied/unsupported/unavailable results include reasons, and that each observation records its basis. This is unusually rich behavioral context for a read-only diagnostics tool.

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 dense and front-loads usage guidance before a crisp statement of purpose. The grant-threat-model details are relevant, but several sentences repeat or expand on concepts already covered by annotations and schema, making it longer than necessary.

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 important behavioral boundaries: grants, protected policy, denial reasons, basis, and read-only operation. With no output schema, it does not fully specify the return shape beyond basis and unavailable observations, but it gives enough context 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%, and the schema already documents list, path, task, tools, and categories. The description's parameter-related statements mostly restate the schema, such as list: true naming categories and task granting nothing, rather than adding substantial new parameter-level 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 and resource: observe parts of this machine, collecting diagnostics categories only and never files or reports. It is clear about the tool's purpose, but it does not differentiate it from the sibling tools snap, source_text, summary, or verify_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?

It explicitly says to use this before giving system-specific instructions such as install commands, drivers, or setup, and to ask only for the categories the task needs instead of guessing. It does not state when to choose a sibling tool or when not to use this one.

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 readOnly/idempotent/non-destructive, so 'reads the chain, checks nothing, changes nothing' is largely redundant reinforcement. The real value added is the acceptance contract: verified disposition plus byte-for-byte identity, with three named refusal cases (post-edit, refused repair, unverified chain) — context annotations cannot express.

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?

Every clause carries information, but the structure is poor: the opening is a dangling fragment and the primary outcome (accepted boolean plus reason) is buried mid-sentence inside a semicolon chain. Front-loading 'Returns whether a final report is acceptable' would have made it far easier to parse.

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 tool with no output schema, the description covers the decision criteria, the failure reasons, and the side-effect profile, which is nearly everything an agent needs. It leaves 'disposition is verified' undefined, depending on the agent's knowledge of the sibling feedback tools.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning beyond the schema: 'final_text' must be byte-for-byte the chain's last accepted text, which tells the agent not to normalize or edit the string before passing it. The 'chain' parameter's provenance is only restated from the schema.

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

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

The description makes clear this is a validation predicate over a feedback chain's final report, with the accepted/reason outcome implied by the enumerated refusal cases. It is specific about the resource (a chain's final text) but is written as a sentence fragment ('Before accepting...: whether it is...') rather than a verb+resource statement, and it never names the sibling it differs from (e.g. verify_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?

'Before accepting a final report from a feedback chain' establishes the exact moment this check belongs in a workflow, and the refusal cases imply it should be run prior to handing in a report. It does not mention alternatives such as verify_report or feedback_resolve, so the agent must infer the routing itself.

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 that buddie re-runs the chain's own check options, names the judging criteria (scope, no added lines except 'buddie:' disclosures, verified claims kept), states the decision is appended to the chain, and specifies atomicity ('a refused submission changes nothing'). Minor gap: idempotencyHint=false is not explained, and openWorld behavior isn't elaborated.

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, then validation detail, then return/refusal behavior. Dense but each clause carries information; slightly clunky phrasing but 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?

No output schema, but the description explains what is returned (the decision and next feedback) and the refusal case. For a mutation tool with full schema coverage and annotations, this is largely complete; only the shape of the 'decision' and handling of specific refusal codes remain implicit.

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 chain/feedback/submission/original_text/corrected_text are already documented. The description adds a little meaning ('one corrected text' being checked against chain's check options) but does not clarify the submission object fields or how original_text/corrected_text relate to the artifact hashes.

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 ('answer a chain's open feedback with one corrected text') and describes the internal validation and append step. It's clearly distinguishable from siblings like feedback_start/feedback_accept by its resolve-and-append role, though it never names those alternatives.

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: you call this to answer an open feedback-v1 returned by feedback_start. There is no explicit when-to-use statement, no contrast with feedback_accept, and no prerequisites (e.g. that an accepted/started chain must exist) spelled out.

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=false, openWorldHint=true and idempotentHint=false, so the mutation and open-world profile is known. The description adds real value beyond them: it says the chain and its check options are persisted 'in files of its own', that the return is a feedback-v1 with at most one bounded action per finding, and that verifying is only 'advice' relative to state.task. It stops short of saying where those files live or how the chain terminates.

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?

Roughly 70 words with the action front-loaded in the first clause, and every sentence carries information rather than filler. The multipurpose phrasing ('buddie runs the check itself, keeps the chain and its check options in files of its own') is packed tight and takes a second read, which costs some clarity but no length.

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?

This is a complex, high-parameter, stateful workflow tool with no output schema, so the description must carry the return-value burden. It gestures at the feedback-v1 shape ('at most one bounded action per finding') but never explains what a finding or an action looks like, and it leaves the boundary with verify_report unstated. Adequate orientation, insufficient for a 14-parameter chain-starter.

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% across all 14 parameters, including enums and defaults for profile, checks, modules and numbers, so the schema does the heavy lifting and a baseline 3 applies. The description contributes one genuinely extra semantic link, tying the requirements parameter to what counts as a 'finished task' (state.task). The remaining 13 parameters, including fetch, repos, store, access and iteration_limit, get no added meaning in prose.

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 combination: 'Check a report and open a verification feedback chain'. It also pre-names the follow-up sibling (feedback_resolve), so the agent knows this is the entry point of a two-step flow. What it does not clarify is how 'Check a report' differs from the sibling verify_report, which reads as an overlapping purpose.

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 downstream guidance ('correct only what an action names and call feedback_resolve') and a completion caveat ('a verified report is not a finished task unless the requirements you state are met'), but it never states when this tool should be chosen over verify_report or feedback_accept. The usage path is implied rather than spelled out.

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 read-only, open-world, idempotent, and non-destructive behavior. The description adds useful behavioral context by saying snapshots store bytes keyed by sha256 for later checking, though it omits return format, error handling, and authentication/rate-limit 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 with the core action front-loaded, followed by the workflow instruction. There is no filler or redundancy.

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

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

For a simple two-parameter tool with rich annotations and complete schema coverage, the description gives enough context to invoke it correctly in the quoting workflow. Since there is no output schema, it could say more about what a snapshot returns or how to reference it later, so it is not fully complete.

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

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

Schema description coverage is 100%, so both the urls array and store parameter are already documented in the schema. The description reinforces linking the same URL but adds no new meaning for the store parameter or array behavior, 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?

Starts with a specific verb and resource: 'Snapshot URLs', and explains the purpose via 'bytes by sha256' and quote verification. It also distinguishes itself from the source_text sibling by saying to call snap first, then copy words from source_text.

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

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

Explicitly says to call it before quoting a page and then use source_text, giving clear workflow context. It does not state when not to use it or name an alternative snapshot route, 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?

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the bar is lower; the description adds that grep mode truncates output to matches plus context, which materially changes what the agent sees. It omits any mention of output size limits or behavior when the ref matches nothing.

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 what the tool returns, followed by the grep caveat and citation rules; no filler. The citation-formatting sentence is arguably workflow advice rather than tool description, but it is compact and actionable.

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 read-only tool with full schema coverage and no output schema, this covers what is returned, the grep variant, and the quote/citation convention. The main remaining gap is failure/empty-match behavior and any truncation of large snapshots.

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 every parameter is already described in the schema, so the baseline is 3. The description's grep note restates what the schema's grep/context entries already say, adding no syntax or format detail beyond them.

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 the concrete resource and result: the visible text of a snapshot, with the accepted reference forms (URL or sha256 prefix). An agent can distinguish it from summary/verify_report/snap, though the verb is implicit rather than stated ('visible text of a snapshot' rather than 'reads').

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 ('With grep, only the matches with context') and prescribes how to cite results, but never states when to choose this over siblings like summary or verify_report. The selection logic is left to inference from the sibling names.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds real context beyond that: the summary is built from the hook's records and returns both `text` and a ready `card`, and it clarifies that launching auto/ask steps is the agent's downstream action, not a mutation by this tool. It stops short of describing filtering behavior or failure modes.

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

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

The description is a single dense run-on containing parentheticals, Russian text, and an emoji anchor marker. The purpose is buried behind the trigger condition rather than front-loaded, and the instruction payload would be clearer as separate sentences; it is over-packed rather than economical.

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 partially compensates by naming the returned `text` and `card` and their contents (verdicts, lost agents, PRs, CI). But parameters are left entirely to the schema and the behavior of the queue/repos/stale inputs is never tied back to the output, leaving the picture incomplete for a tool whose returns are 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 100% with all four parameters (queue, repos, stale, session) documented in the schema itself. The description adds nothing about those parameters, so baseline 3 applies.

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

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

The description does reveal that the tool produces a summary assembled by code from hook records plus a `card` (AskUserQuestion input), but it opens with a trigger condition ('When no subagent is left') rather than a clean verb+resource statement. It is distinguishable from siblings only indirectly, and the mix of purpose with post-call instructions makes the core function fuzzy.

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 condition 'When no subagent is left' gives an implied trigger for calling the tool, which is useful. However, it never names or contrasts with the sibling tools (source_text, verify_report, snap), and the rest of the sentence is guidance about what to do with the output rather than when to choose this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, and the description adds substantial behavioral detail beyond that: receipt outcomes of FAIL/GAPS/PASS/EMPTY, blocking items, a summary line, and the important caveat that EMPTY means nothing was checkable rather than that the text is correct.

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 purpose and stays dense with useful information, including the example of a valid quotation and anchor. It is somewhat long, but the length is justified by the tool's complexity and the density of checkable formats.

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 13-parameter tool with no output schema, the description is complete enough: it explains what is checked, how quotations and anchors must be written, the possible receipt outcomes, and the meaning of EMPTY. Missing details such as auth or rate limits are less critical here because annotations cover the safety profile and the schema covers parameter 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 100%, so the schema already documents all 13 parameters in detail. The description adds useful checking examples and semantics such as quote/anchor syntax, but it does not add much parameter-specific meaning beyond what the schema provides.

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

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

The description states a specific verb-resource pair: it checks a report, verifying quotes against linked source bytes and anchors against repos, GitHub, or session transcripts. It also explains the receipt outcomes, making the tool's scope immediately clear and distinguishable from unrelated siblings such as snap or summary.

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 a clear usage context: 'Check a report before accepting or passing it on.' It further explains what is checkable and what EMPTY means, but it does not explicitly name alternatives or describe when not to use this tool.

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