ris_get

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

With no annotations provided, the description carries the full disclosure burden. It successfully discloses that section retrieval is token-preserving, save_path writes to disk, and save_path returns metadata only instead of content. It does not address authentication, errors, or rate limits, but the main behavioral side effects of the tool are surfaced.

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 two sentences with no filler. The core retrieval purpose is front-loaded, and the remaining content packs parameter routing, mode behavior, and output implications into a tight, scannable structure.

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 no output schema and no annotations, yet the description covers the main invocation modes, output format, and side effects, so an agent can reasonably select and call it. Some gaps remain around error conditions and output details when no save_path is given, but they are not severe enough to make the definition inadequate.

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 meaningful semantic relationships: content_url is preferred over id, applikation is conditionally required with id, section is token-preserving, and save_path changes the return behavior. This goes beyond what the property descriptions alone provide.

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 and resource: 'Retrieve a RIS document as Markdown.' It is clearly scoped to full documents and partial sections, and it contrasts with the broader sibling set by focusing on RIS document retrieval. It does not explicitly name or differentiate sibling tools like ris_get_norm or ris_toc, so it misses the top score.

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 strong internal guidance: prefer content_url from ris_search, use id only with applikation, use section for partial retrieval, and use save_path to write to disk while returning metadata only. It clearly explains when to use each parameter mode, but it does not state when to prefer this tool over sibling alternatives such as ris_get_norm.

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