Get Response Sample

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

No annotations are provided, so the description carries the burden. It discloses that the tool returns an example JSON response, which is a read-only behavior. However, it doesn't mention whether the response is static/sample data or a live call, nor any error behavior (e.g., unknown slug). The description is accurate but minimal.

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?

One sentence, front-loaded with the core action and object. No wasted words. The example in the schema helps clarify the parameter format.

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 tool is simple (1 param, output schema present), so the description is mostly sufficient. However, with no annotations and no mention of how to discover valid slugs (e.g., via list_endpoints), an agent might not know where to get the slug value. The output schema exists, so return format is covered, but the input source is not.

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%: the 'slug' parameter is described as 'Endpoint identifier (e.g. 'listnetworks')'. The description adds the context that the slug identifies a specific endpoint, but doesn't add much beyond the schema. Baseline 3 is appropriate.

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's purpose: retrieving an example JSON response for a specific UniFi API endpoint. It uses a specific verb ('Get') and resource ('example JSON response'), and the mention of 'specific UniFi API endpoint' distinguishes it from generic listing/searching tools. However, it doesn't explicitly differentiate from the sibling 'get_example', which may be a close alternative.

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 implies usage: call this when you need an example response for a known endpoint identifier. It doesn't explicitly state when not to use it or name alternatives like 'get_example' or 'get_endpoint'. The context is clear enough for a simple tool, but lacks explicit routing guidance.

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