get_connected_site

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

Annotations already indicate readOnlyHint=true, so the tool is known to be safe. The description adds that it returns the full record with tracking script, but does not exceed the annotation's safety profile significantly. It provides context about the return fields but not additional behavioral traits.

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 concise and well-structured, starting with a one-sentence summary, followed by usage guidelines, parameter details, and return format. Every sentence serves a purpose without redundancy.

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 the input schema has two parameters (one required) and an output schema exists, the description sufficiently explains the required parameter and the expected return structure (JSON with specific fields). It is complete for a read tool with good annotations.

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 0%, so the description must compensate. It describes the required connected_site_id parameter well, including how to obtain it from list_connected_sites. However, it ignores the optional account parameter, leaving its purpose unclear. This partial coverage adds some value but is not fully complete.

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 tool retrieves a full record for a single connected site, including its tracking script. It distinguishes from sibling tools like list_connected_sites and explicitly mentions usage when a connected site ID is known.

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 tells when to use this tool: when you have a connected site ID and need its script snippet or installation status. It also provides clear guidance to use list_connected_sites for browsing instead, offering an alternative.

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