fs_copy_file

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

No annotations are provided, so the description must carry the burden of behavioral disclosure. It mentions 'overwrite toggle' which hints at overwrite behavior, but does not state whether overwrite defaults to false, what happens if the destination exists, or what 'metadata' specifically includes (e.g., permissions, timestamps). This leaves significant ambiguity about side effects and error conditions.

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 short phrases, front-loaded with the verb 'Copy' and resource 'file'. There is no filler or redundancy. It is appropriately sized for the tool's simplicity, though other dimensions suffer from the brevity.

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?

Despite being a simple copy operation, the description lacks essential context such as the meaning of 'metadata', the exact overwrite behavior, and any prerequisites or caveats. An output schema exists but is not described; with no annotations, the description is incomplete for reliable tool selection and 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?

Schema description coverage is 0%, so the description must compensate. It only references the 'overwrite' parameter via 'overwrite toggle' and provides no additional meaning for source_file_path or dest_file_path beyond their self-explanatory names. The parameter semantics are largely left to the schema's type and requiredness, which is minimal.

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 identifies the operation as copying a file and mentions a distinguishing feature (metadata preservation) and an overwrite toggle. The resource type 'file' differentiates from sibling tools like fs_copy_directory, though 'with metadata' is somewhat vague and could be interpreted as copying metadata properties without specifics.

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 provide any explicit guidance on when to use this tool versus alternatives. It implies usage for file copying, but no exclusions or conditions are stated. The sibling tools include move and delete operations, but the description does not clarify that this is for copying as opposed to moving or linking, leaving the agent to infer from the name.

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