mavis_read

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

The description discloses important behavioral traits: return types (text vs base64), truncation of large files, and the need for partial reads. However, it references a non-existent 'offset' parameter, which is misleading, and omits other behavioral details like error handling, file size limits, or explicit confirmation that this is a read-only operation (though that is implied by the name).

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 concise and front-loaded with the core action 'Read a file from the workspace.' The second sentence provides useful details about return types and truncation. However, the 'use offset' clause is inaccurate and unnecessary, preventing a perfect score.

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 read tool with no output schema, the description covers return format and truncation behavior, which is good. But the mention of 'offset' without the parameter existing, combined with no explanation of how max_lines relates to partial reads, leaves an ambiguous path for handling large files. Overall, it is adequate but has a clear gap.

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 has 100% parameter description coverage, so the baseline is 3, but the description introduces an 'offset' parameter that is not part of the input schema, potentially confusing the agent. It adds no additional meaning beyond the schema for cwd, path, or max_lines, making the net contribution negative.

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 'Read a file from the workspace' and specifies return types (text or base64), making the tool's purpose unambiguous. However, it does not explicitly differentiate from sibling tools like mavis_search or mavis_write, so it misses the highest tier of clarity.

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 a clear context for reading files and notes truncation for large files, but it does not explicitly state when to use this tool instead of alternatives or when not to use it. The advice to 'use offset for partial reads' is actionable but references a parameter that does not exist in the schema, which undermines the guidance.

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