get_r_company_get_uninstall_secret

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

No annotations are provided, so the description must convey behavioral traits. It only states the HTTP method and parameter locations, but doesn't disclose authentication requirements, sensitivity of the returned secret, or any side effects (though GET implies read-only). The description lacks detail on what the return value contains (e.g., token string) and any rate limits or error conditions, leaving significant behavioral gaps.

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 a single sentence, which is concise, but it is not well-structured for clarity. It starts with the purpose, then adds a somewhat technical instruction about the HTTP call. It's not overly verbose, but the information is minimal and could be better organized to front-load the key purpose and usage.

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?

Despite having an output schema, the description lacks essential context for a tool that returns a sensitive secret. It doesn't explain the purpose of the uninstall secret, what the response format is (though the output schema exists), or any prerequisites like company ID in path_params. Given the complexity of routing and the sensitivity, more detail is needed for correct invocation.

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 parameters are generic (body, query, headers, path_params) with no documentation. The description merely says to provide route IDs in path_params and filters in query, but doesn't specify what route IDs are needed or what filters are valid. This does not compensate for the lack of schema guidance, leaving the agent guessing about parameter values.

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 it retrieves an uninstall secret token via a specific endpoint, which is clear about the resource. However, it doesn't differentiate from many sibling tools that also start with 'get_r_company_' and could be confused, such as get_r_company_credentials or get_r_company_patch_settings. The verb 'Get' and resource 'uninstall secret' are specific enough for a basic understanding.

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 provides no guidance on when to use this tool versus alternatives. It doesn't mention that this is for company-level uninstall secrets, nor does it contrast with other get_r_company_* tools. The agent is left to infer from the name and endpoint, which is insufficient given the large sibling set.

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