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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, and openWorldHint=true, so safety is covered. The description adds genuinely new lifecycle context — 'The store starts pending; the activation check makes it live' — plus enforcement constraints (hours must fall inside 10:00–22:00, radius capped at 5, default 2). It stops short of stating permission/auth requirements or the failure mode on a rejected activation check.

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?

Front-loaded with purpose, then a dense but orderly enumeration of payload fields and constraints. It is a single long sentence, but the parallel structure keeps it scannable and every clause carries a constraint or field; nothing is padding.

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 an 11-parameter creation tool with nested objects and no output schema, the description covers the required fields, the optional payload, key defaults, and the pending→live state transition. The gaps are the two undocumented enum params and any indication of what the call returns (store id, status), which matters for a non-idempotent create.

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 0%, so the description carries the full burden, and it does most of the work: it enumerates name, address, alert_channels kinds (relay/webhook/sms/voice), robot_spot, hours window, radius default and max, visibility, loading_notes, and external_ref. It omits robomart_version and perishables_after_hours, two enum params that remain undocumented anywhere, and it adds meaning (the 2-mile default, the 5-mile cap, the 10:00–22:00 hours band) not present in the schema.

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?

States a specific verb and resource ('Register a store') and immediately anchors it in the domain ('a real place whose owner promises to load the robot'), which separates it from read/list siblings like find_stores and list_stores without needing their schemas. An agent can tell this is the creation path vs. update_store.

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 lays out exactly what to send (required fields plus optional payload pieces), which implies the creation context, but it never states when to use this over update_store or what precondition (e.g., the store not already existing) selects it. Usage is inferred rather than spelled out; no alternatives or exclusions are named.

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