crpt_write_raw

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

Annotations already flag readOnlyHint=false and openWorldHint=true, but the description adds valuable specifics: method restrictions (POST, PUT, PATCH), the mandatory confirm_write flag, and the JSON return envelope. These details are not in annotations and help the agent understand safety and outcome.

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 well-structured with the core purpose front-loaded, followed by API target, method constraints, an Args list, and return format. Each line serves a clear function; only the Args list makes it a bit longer, but it is necessary given zero schema coverage.

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 write tool with 6 parameters and an output schema, the description covers all parameters, return format, and method restrictions. It omits details on error handling beyond 'error envelope' and does not mention permissions, but those are not critical given the tool's scope and annotations.

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%, yet the description explicitly documents all six parameters with constraints (e.g., 'path: full path beginning with /', 'confirm_write: must be true', 'host: host override'). This fully compensates for the lack of schema descriptions and leaves no ambiguity.

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 states a specific action ('Create or update data') and a clear resource ('at ANY path, including paths not in the catalog'). It distinguishes itself from sibling tools like crpt_write_method or crpt_get_raw by emphasizing arbitrary paths, making the tool's purpose unambiguous.

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 operational constraints (POST/PUT/PATCH only, requires confirm_write=true) but does not explicitly contrast with alternatives. It implies usage for arbitrary paths but never names sibling tools or says 'use X for catalog paths', leaving the agent to infer routing from the tool name.

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