read_local_artifact

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

Annotations already cover the read-only, non-destructive, closed-world profile, but the description adds real behavior beyond them: output is bounded extracted text with original path and source fingerprint, pagination applies, and four distinct error states must be handled. Missing detail on what 'fresh' means operationally (cache bypass? snapshot semantics).

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 tight sentences, front-loaded with the identity/precondition and ending with the scope exclusion. Dense but every sentence carries information; style is telegraphic rather than wasteful.

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 so return values needn't be spelled out, yet the description still flags path and fingerprint payload. Error handling and pagination are covered. The gap is pagination semantics and the meaning of 'fresh', which an agent invoking with limit/offset would want.

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% and none of the three params (limit, offset, artifact_id) carry descriptions. The description does clarify artifact_id's provenance and implies pagination via limit/offset, which compensates partially, but the pagination mechanics and defaults remain 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?

Names a specific verb (fresh read) and resource (artifact id), and explicitly distinguishes itself from the alternative path-based access: 'an id returned by search_local, never an arbitrary path.' An agent can route between this and search_local without opening either 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?

States the precondition that the id must come from search_local and enumerates the error conditions to respect (missing/disconnected/stale/blocked). Also says PDF rendering/download is out of scope, which is a useful exclusion. It stops short of naming a sibling alternative for the PDF case, so not a full 5.

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