create_location

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

The annotations declare destructiveHint: true, which implies the operation may destroy data. However, the description states 'Create a new business location,' which is inherently an additive operation. This is a direct contradiction. The description also provides no additional behavioral context (e.g., side effects, permissions, reversibility) beyond what annotations already give. This contradiction makes the description misleading for an agent.

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 sentences, with the core purpose stated upfront. It is concise and contains no redundant information. The structure is logical: statement of purpose, usage context, and a note about associations. It earns a 4 rather than a 5 because the final sentence adds only minor context and could be more directly relevant to the create action.

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 covers the purpose and when to use it, but does not mention return values (no output schema exists) or any operational constraints such as required permissions, duplicate handling, or location uniqueness rules. The annotation contradiction (destructiveHint vs. create) also leaves the safety profile unclear. For a moderately complex create tool with 5 parameters, this is inadequate but not severely incomplete, hence a 3.

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 all five parameters have descriptions in the schema itself. The description does not add any parameter-specific meaning beyond what the schema already provides (e.g., it does not clarify coordinate format or labeling conventions). According to the rubric, with high schema coverage the baseline is 3, and the description adds no extra value here.

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 ('Create') and resource ('a new business location') and provides context about its use for reader deployment and pass management. It is distinct from sibling tools like list_locations, update_location, and delete_location, so an agent can easily distinguish it.

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 explicitly says 'Use this when setting up a new store, venue, or checkpoint,' which gives clear guidance on when the tool should be invoked. It also mentions that locations can be associated with passes and readers, adding contextual usage info. It does not explicitly list alternatives for updating or deleting locations, but the context strongly implies that this is the creation path.

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