Create an additional API key for this account. Requires an existing API key. Unverified accounts may have only one key; verified accounts may have three. Usage is counted per account, not per key.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | optional kind: user or agent, default agent | |
| name | No | optional key name |
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | ||
| name | Yes | ||
| key_id | Yes | ||
| limits | Yes | ||
| api_key | Yes | ||
| message | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a mutating, non-idempotent operation, and the description adds meaningful behavioral context beyond that. It discloses the prerequisite of an existing API key, account verification limits, and that usage is aggregated per account rather than per key. This gives the agent useful expectations about constraints and side effects.
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 three short sentences with no filler. The primary action is front-loaded, followed by necessary prerequisites and account constraints. Every sentence earns its place by communicating a distinct fact that affects whether and how the tool should be called.
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 tool with two optional parameters and an output schema, the description covers the essential context: prerequisites, account-level limits, and counting behavior. It does not explain the user/agent kind distinction or expected output, but the schema and output schema already provide that information. The description is complete enough for reliable selection and invocation.
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 already documents both parameters fully, including the enum values for kind and the optional nature of name, so schema coverage is 100%. The description does not add additional parameter-level meaning beyond what the schema provides. A baseline score of 3 is appropriate because the schema carries the parameter documentation burden.
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 a specific verb and resource: 'Create an additional API key for this account.' It clearly distinguishes this from sibling tools like create or revoke by emphasizing 'additional,' while the prerequisite makes it distinct from signup. This leaves no ambiguity about what the tool accomplishes.
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 clear context for when this tool is appropriate: it requires an existing API key and is for creating additional keys rather than initial account creation. It also conveys important account-level constraints, such as unverified accounts being limited to one key and verified accounts to three. However, it does not explicitly name alternative tools like list_api_keys or revoke_api_key, so the guidance is clear but not fully explicit about exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
Most tools have clearly distinct roles, and the descriptions explicitly separate product lookup from recall search. However, the multiple recall search entry points (by query, UPC, image, and identifier) overlap enough that an agent could pick the wrong one without carefully reading the details.
Tool names consistently follow a snake_case verb_noun pattern such as add_, list_, remove_, search_, get_, create_, revoke_, and mark_. The single-word signup is the only minor deviation, but it does not undermine the overall naming system.
At 19 tools, the set is in the borderline-heavy range. The count is justified by the multiple subdomains like API key management, inventory, watch patterns, notifications, and recall searching, but it still feels slightly above the ideal well-scoped tool surface.
Core recall search, product lookup, inventory tracking, watch pattern management, notifications, and API key lifecycle are all covered well. Minor gaps exist such as no way to update a watch pattern or view account usage limits, but agents can generally work around them.