rba_write_file

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

With no annotations, the description must disclose behavioral traits itself. It states 'Create or replace' but omits critical behavior: the 'overwrite' parameter defaults to false, meaning replacement may not occur without explicit opt-in. It also does not mention the default creation of backups (backupExisting=true) or automatic directory creation (createDirectories=true). These behaviors affect the outcome and failure modes, making the description insufficiently transparent.

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 concise sentence: 'Create or replace a file inside the RBA workspace.' It is front-loaded with the primary verb and resource, contains no filler words, and every word adds meaning. This is an example of ideal conciseness.

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 has five parameters, no output schema, and no annotations, the description is too sparse. It explains the basic purpose but provides no information on return behavior, error conditions, prerequisites (e.g., RBA workspace availability), or parameter interactions. The 'replace' behavior is contextually important because overwrite defaults to false. The description is a minimal one-liner that leaves significant gaps for safe and correct use.

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 description does not mention any parameters. Schema coverage is only 20% (one parameter has a description), so the burden falls on the description to clarify parameter usage. The five parameters (path, content, overwrite, backupExisting, createDirectories) have nuanced defaults and effects that are not explained. The agent must rely on parameter names and the sparse schema, which is inadequate for correct invocation.

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 uses a specific verb phrase 'Create or replace a file' and names the target resource as 'a file inside the RBA workspace.' This clearly differentiates it from sibling tools like rba_append_file (add to file), rba_read_file (read), and rba_backup_file (backup). The intent is unambiguous and identifies the unique operation.

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?

No guidance is provided on when to use this tool versus alternatives. For example, it does not mention using rba_append_file for appending content or rba_backup_file for backing up, nor does it explain scenarios where this tool should not be used (e.g., when the file does not exist and overwrite is false). The description is silent on usage context, leaving the agent to infer from the name alone.

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