vk_put_user_05b2c0bba8e2

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

With no annotations provided, the description carries the full burden. It discloses a side effect: 'This will also set the user's avatar provider to upload', and states authentication is required. It also explains the multipart form input format and alias conventions. However, it omits response behavior and error cases, which would be helpful but are not strictly required for a raw proxy.

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 information-dense but contains redundancy, repeating 'Upload a user avatar' twice. It also has a run-on sentence with missing punctuation: 'This will also set the user's avatar provider to "upload" Pass multipart form data in the form field.' While not overly long, it could be more concise and better structured.

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?

The tool has one parameter, no output schema, and no annotations. The description thoroughly covers input format, side effects, and authentication, but does not mention the response format or failure behavior. For a raw proxy, 'Raw Vikunja REST proxy' may imply a raw response, but this is not explicit. It is adequate but leaves some gaps.

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 covers 100% of the single parameter 'form' with a detailed description. The tool description adds extra meaning by noting that 'Path and query parameters are top-level fields' and 'Original parameter names also accept camelCase and snake_case aliases', which are not in the schema. This goes beyond the baseline of 3 provided by high schema coverage.

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 'Upload a user avatar' and explicitly identifies the raw REST proxy endpoint 'PUT /user/settings/avatar/upload'. This gives a specific verb and resource, and the mention of the endpoint clearly distinguishes this tool from sibling vk_put_user_* tools that target other endpoints.

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 implies usage by stating the endpoint and purpose, but it does not explicitly mention alternatives or when not to use this tool. For example, it lacks a note like 'Use this instead of updating the avatar URL' or any comparison with sibling user tools. The guidance is implicit rather than explicit.

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