sbis_write_raw

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

Given annotations already declare readOnlyHint=false and openWorldHint=true, the description adds meaningful behavior: method restrictions, confirm_write guard, host default behavior, and the success/error envelope. It stops short of detailing overwrite consequences, idempotency, or authentication prerequisites, but it substantially expands on the annotations.

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 purpose is front-loaded and the text is tight, but there is minor redundancy: 'POST, PUT and PATCH only' is restated in the Args line, and confirm_write is stated twice ('requires confirm_write=true' and 'confirm_write: must be true'). Still, the structure makes all required parameters easy to scan.

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 six-parameter raw write tool with no schema descriptions, the description covers every parameter, the invocation constraints, the target API documentation, and the response envelope. An agent has enough information to select and call the tool correctly.

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%, and the description compensates thoroughly by explaining each parameter: method allowed values, path format (leading '/'), host override/default, query-string parameters, JSON body, and the mandatory confirm_write=true.

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 opens with 'Create or update data at ANY path, including paths not in the catalog,' which gives a specific verb, resource, and scope. This directly differentiates the raw tool from catalog-scoped siblings like sbis_write_method and sbis_call_method.

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?

It clearly states the supported methods and the confirm_write requirement, and the 'ANY path, including paths not in the catalog' phrase gives the selection context for raw writes. However, it does not explicitly name an alternative or say 'use sbis_write_method for catalog paths,' so the guidance is strong but not fully explicit.

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