Save Site

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

Annotations already indicate readOnlyHint=false, and the description adds valuable behavioral context: keyless calls return auth_required, passing market triggers a DCPI baseline snapshot, and the tool returns a saved site id. It also notes the persistent shortlist nature. This goes beyond the annotation hints without contradicting them.

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 fairly long but well-structured: it front-loads the critical auth/API-key warning, then explains the core action, parameter hints, return value, optional snapshot behavior, and ends with explicit non-uses. Each sentence adds value, though some cross-tool guidance could be slightly trimmed without loss.

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 10 parameters, an output id, auth prerequisite, and snapshot behavior, the description covers purpose, usage, parameters, return value, and related tools. It does not detail error cases beyond auth_required, but the presence of an output schema and annotations reduces the need for that. Overall, it is contextually rich and sufficient.

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 coverage is 100%, so the baseline is 3. The description adds meaning by highlighting that lat+lon are expected inputs (though schema marks them optional), explaining the special effect of 'market' (snapshots DCPI baseline), and providing a concrete example with parameter values. This enhances the bare schema descriptions.

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 uses a specific verb and resource: 'Save a candidate data-center site to your DC Hub account to track it across sessions.' It clearly distinguishes itself from siblings by stating 'Do NOT use to read back the shortlist (use list_saved_sites), download it (use export_dataset), or score a site (use score_facility).' This makes the tool's purpose unambiguous.

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?

Provides explicit when-to-use guidance, including the prerequisite to call claim_free_key first, and names alternatives for read, download, and scoring operations. It also instructs on chaining to set_site_alert, making the intended workflow clear.

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