get_r_company_agent_discoverysettings_mapping_id

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

With no annotations, the description carries the full behavioral burden. It does disclose that the operation is a read-only GET via both the verb 'Retrieve' and the HTTP method, which rules out side effects. However, it adds no context on auth requirements, error behavior, rate limits, or response envelope, leaving significant behavioral ground uncovered for a zero-annotation tool.

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?

Two sentences with no filler: the first states the operation and endpoint, the second gives the param placement rule. Purpose is front-loaded before usage hints. Minor awkwardness in 'route IDs' (singular `{id}`) does not bloat the text.

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 simple generated pass-through client, the description covers the core invocation contract (endpoint, where each parameter type goes), and an output schema exists so return values need not be explained. Missing pieces are the when-to-use distinction from the collection sibling, example query keys, and whether the body field is ever relevant — gaps that matter more because there are no 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 description coverage is 0% and the schema properties are empty generic objects (`additionalProperties: true`), so the description must compensate. It does meaningfully by assigning roles to each container: path_params holds the route ID, query holds filters/pagination, headers holds request headers. It falls short of enumerating actual filter or pagination key names, but it converts four opaque buckets into usable guidance.

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 states a specific verb (Retrieve), a specific resource (agent discoverysetting mapping), and the exact endpoint `GET /r/company/agent_discoverysettings_mapping/{id}`. The `_id` suffix in the name and the `{id}` path template clearly signal single-item retrieval versus the sibling collection endpoint `get_r_company_agent_discoverysettings_mapping`. It doesn't explicitly name the sibling it differs from, which keeps it just short of a 5.

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 gives concrete placement guidance: route IDs go in path_params, filters and pagination go in query, headers go in headers. However, there is no explicit statement of when to use this tool versus the collection-only sibling or the write variants, and no exclusion criteria; the correct usage context (fetching one mapping by ID) is only implied by the endpoint and name.

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