files_get_content

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

Beyond the readOnlyHint annotation, the description discloses important behavioral traits: it re-hashes bytes and compares against stored sha256, returns integrity_mismatch with both hashes on mismatch, and content_not_found if the blob is missing. It also explains the rationale for refusing to serve mismatched content and mentions permission nuances. This is substantial additional context, though the cryptic 'OR 958f' phrase adds confusion.

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 core action is front-loaded ('Read a stored file back as base64'), but the description becomes verbose with conditional error behaviors and cryptic references. Phrases like 'This is the OR 958f Abs. 3 readability half' and 'Needs the file-content right on top of the master-data read' are unclear and add noise without clear value. The structure could be tightened by focusing on the action, parameters, and expected outputs.

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?

With no output schema, the description should explain what the success response contains beyond base64, but it only mentions error cases. It also fails to describe how workspaceId and fileId are used or validated. The cryptic legal/regulation reference does not aid understanding. For a tool with two parameters and no schema descriptions, this is incomplete.

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 two required string parameters (workspaceId and fileId) with no descriptions (schema coverage 0%). The description does not mention either parameter, leaving the agent without clues about what fileId refers to (e.g., a file identifier) or how workspaceId scopes the operation. This is a critical gap for a tool with no schema documentation.

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 tool reads a stored file and returns it as base64, with a specific verb ('Read') and resource ('stored file'). It also mentions the integrity check and error conditions, making it distinct from sibling file tools like files_upload, files_search, or files_delete, which have different purposes.

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 does not explicitly state when to use this tool versus alternatives. It includes a cryptic reference to 'OR 958f Abs. 3 readability half' and a note about read-only roles, but no clear guidance on when to choose this over other file operations. The agent must infer that this is the primary content-retrieval tool, but the description lacks explicit routing or exclusions.

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