read_resource

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

With no annotations, the description carries the burden of behavioral disclosure. It does add valuable information: safe line pagination and rejection of binary resources. However, it omits other behavioral details like whether the operation is read-only, potential error cases, or any 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?

A single sentence that front-loads the core purpose and includes two key constraints. No wasted words; highly efficient.

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 tool has 9 parameters including multiple JAR selector options, but the description gives no context on how these selectors interact or when to use each. It does not explain the relationship between resourcePath and the JAR selection parameters, nor does it mention the output structure. An agent would be under-informed 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?

The schema provides descriptions for most parameters (8 out of 9), so baseline is 3. The tool description itself adds no extra parameter meaning beyond the concept of 'exact resource' and pagination, which are already partially implied by 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 clearly states the action ('Read'), the resource type ('exact text resource'), and a key behavioral constraint ('safe line pagination'). It is specific enough to distinguish from search-oriented siblings like search_resources, though it does not explicitly compare with them.

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 guidance is given on when to use this tool versus alternatives such as search_resources or inspect_jar. The context of when to use the various JAR selector parameters is not addressed, leaving the agent without clear decision criteria.

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