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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with 'Read-only; returns no credentials.' It further discloses key behavioral nuances: a pass proves file integrity but not that anything is measured yet, the endpoint used, the exact output (missing/modified/unexpected paths), and the optional repair_steps behavior. This goes beyond the annotations by explaining what the verdict does and does not guarantee.

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 somewhat long, but every clause earns its place: it front-loads the core check, contrasts with the HTTPS endpoint, lists runtimes and file format, explains optional parameters, and states return values and read-only nature. It could be tightened, but the density of useful information is high and the most critical usage guidance comes first.

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 verification tool with read-only annotations and no output schema, the description covers the return shape (pass/fail plus missing/modified/unexpected paths) and the repair_steps behavior. It lacks explicit notes on error cases (e.g., invalid sha256 format, unknown runtime) and the openWorldHint=false nuance, but it is otherwise complete for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds useful context: it clarifies that each file result already includes its expected sha256, and that repair_steps returns text on mismatch. However, it does not add much beyond the schema for runtime or installed_version. The 3 baseline is appropriate because the schema already documents all parameters.

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

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

The description states a specific verb ('Check'), resource ('a Boosthis kit's FILES ON DISK'), and scope ('byte-perfect'), and distinguishes itself from the plain HTTPS verify endpoint and from sibling boosthis_verify_kit by focusing on files already written on disk. The distinction is explicit enough for an agent to know this is the disk-verification tool, not the generic verify 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 explicitly says when to use this: after writing kit files, send each file's sha256, and it contrasts with the plain HTTPS endpoint ('same check over plain HTTPS...'). It also names the condition that triggers repair_steps. This gives the agent clear context for invoking it as a post-install verification step, though it doesn't enumerate when to prefer siblings like boosthis_verify_kit or boosthis_get_integration_kit; the disk-specific scope is sufficient differentiation.

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