post_my_collection

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

Annotations already provide readOnlyHint=false, destructiveHint=false, idempotentHint=true. The description adds the key behavioral detail that the tool updates the entry if it already exists, which supplements the idempotency hint. However, it does not disclose permissions or side effects beyond what the annotations imply. With annotations present, the description adds moderate value.

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, short sentence that conveys the core action efficiently. It is front-loaded and contains no extraneous information. While minimal, it earns its place. No verbose or redundant phrases.

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 description adequately covers the main behavior for a tool with 2 parameters (one required, one nested object) and an existing output schema. However, it does not mention the scope ('current user') beyond the name, nor does it address potential error states or race conditions. Given the available annotations and schema, it is minimally complete 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?

Schema description coverage is 100%, so each parameter already has a detailed explanation in the input schema (e.g., type, tags, comment). The description does not add extra meaning beyond the schema's own parameter descriptions. For high coverage, baseline is 3, and no additional value is provided.

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 states the action: 'collect specified item, update if already collected'. It identifies the resource (current user's collection) and verb (create/update). The name 'post_my_collection' aligns with a POST operation for the user's collection, effectively distinguishing from read tools like get_my_collection or delete tools like delete_index_collection.

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 explicit guidance on when to use this tool versus alternatives like patch_my_collection (partial update) or other collection mutation tools. The description does not state any prerequisites, who can use it, or when it should be preferred. The implicit purpose is clear, but the agent has no explicit direction to avoid misuse.

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