workspace_read

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

Since no annotations are provided, the description carries the full burden of behavioral disclosure. The description only says 'Read contents', which implies a safe, non-destructive operation, but it does not disclose what happens if the file does not exist (error?), whether it follows symlinks, or if there is a size limit. The lack of annotations amplifies the need for more detail here.

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 a single short sentence that is easy to parse and front-loaded with the key verb. It is concise but arguably too brief given the lack of annotations. It earns a 4 because it is efficient, though it could include a bit more context without becoming verbose.

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?

Given the tool's simplicity (single parameter, no output schema, no nested objects), the description is nearly complete for basic usage. However, it lacks information about file types supported, error cases, or behavioral details that would be needed for robust agent decision-making. A 3 reflects that it is adequate for a simple tool but missing important context.

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 input schema has 100% coverage with a single required 'path' parameter, and its description ('File path relative to workspace root') is already clear. The tool description adds no new semantic information beyond what the schema provides. However, with only one parameter and high schema coverage, the description's minimal addition is acceptable, earning a 4 as per the scoring rule (baseline 3, with high coverage and single param, slight bonus for clarity).

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 uses the verb 'Read' with the resource 'contents of a file in the workspace', which is specific and distinguishable from sibling tools like workspace_list, workspace_tree, workspace_write, and workspace_search. It lacks explicit mention of the path parameter's role, but the verb+resource pairing is strong.

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?

There is no guidance on when to use this tool vs alternatives. For example, it does not clarify whether this tool is for textual files only, or if it works on binary files. No exclusions or when-not-to-use conditions are provided, leaving the agent to infer usage from context signals alone.

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