tokportal_add_edit_slots

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

Annotations only mark the tool as not read-only and not idempotent, which implies a state-changing operation. The description confirms this by saying 'Add edit slots', which indicates mutation. However, the description does not explain what 'edit slots' do conceptually, whether adding them modifies existing bundle properties, or if there are side effects on bundle state or pricing. The idempotency key parameter hints at retries, but the description lacks explicit behavioral details like 'this modifies the bundle's edit slot count' or 'would cause an error if the bundle is published'. Given the annotations carry some transparency, but leave gaps, a score of 3 is appropriate.

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 short and functional, but somewhat terse. In the context of many sibling tools with similar names, a bit more detail (e.g., 'increases the number of editable slots in a bundle identified by id') would improve understanding without being verbose. It earns its place but could be slightly more descriptive to match the complexity of the domain.

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 there is no output schema, the description does not explain what the tool returns (e.g., the updated bundle object, a success message, or nothing). With a complex nested input object and 28 sibling tools, the description is too minimal to fully contextualize how this slot addition affects the bundle lifecycle. However, the schema covers parameters well, so gaps are partially mitigated. A score of 3 is fair for this minimal but not incomplete coverage.

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 input schema has 100% description coverage, so each parameter already has a basic description explaining its purpose (Bundle ID, JSON request body, optional idempotency key). The description adds no extra meaning beyond what the schema provides. For example, it doesn't clarify that 'quantity' must be between 1 and 500 (already in schema), or what a valid 'id' looks like. Since schema coverage is high, baseline is 3, and the description does not elevate further.

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 verb ('Add edit slots') and the resource ('a bundle'), making the tool's primary purpose immediately clear. However, it lacks differentiation from sibling tools like 'tokportal_add_video_slots' and 'tokportal_update_bundle', which could also add or modify aspects of a bundle. The title repeats but doesn't add new context.

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 provides no guidance on when to use this tool versus alternatives. Among the many sibling tools, 'tokportal_add_video_slots' and 'tokportal_update_bundle' are obviously related, but no conditions for choosing this one are given. There is no mention of prerequisites, required state of the bundle, or scenarios where this tool is inappropriate.

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