get_r_company_credentials

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

No annotations are provided, so the description must disclose behavioral traits. It mentions 'filters and pagination in query' but does not explain that this is a read-only GET operation (though implied by the path), nor does it describe response format, pagination mechanics (e.g., limit/offset), potential errors, or authentication requirements. It fails to state that this typically returns a list of credentials, which is essential behavioral context.

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, concise and to the point. It front-loads the action and HTTP call. However, the grammar is awkward ('Retrieve credentials Calls' without a period) and the phrase 'Provide route IDs in path_params' is potentially misleading for an endpoint with no path parameters. Despite this, it avoids unnecessary verbosity.

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 tool has an output schema, return values need not be explained. But the description is incomplete for effective invocation: it does not clarify that this is the list endpoint versus the ID-specific sibling, does not specify which headers are actually required for this endpoint (just says 'any required'), and does not detail the query parameter structure. An agent would struggle to know what to put in path_params (since none are required) and what specific pagination parameters to use. It lacks practical details to avoid mis-calls.

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%, so the description must compensate. It does map parameters: path_params for 'route IDs', query for 'filters and pagination', headers for 'required request headers'. This adds some meaning beyond the empty schema. However, it is vague: what filters are available? What pagination parameters? What are 'route IDs'? It also ignores the `body` parameter entirely. The mapping is a start but lacks detail.

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 'Retrieve credentials' and names the exact HTTP call `GET /r/company/credentials`. It clearly indicates the resource (credentials) and the action (retrieve). It distinguishes from the sibling `get_r_company_credentials_id` by omission of an '_id' suffix, implying a list operation, but does not explicitly say 'list all'. The combination of the verb, path, and naming makes the purpose clear.

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 mechanical placement instructions (path_params, query, headers) but provides no guidance on when to use this tool versus the sibling `get_r_company_credentials_id`. It does not mention that this is for listing all credentials or that using an ID should route to the other tool. There are no examples, conditions, or exclusions, leaving the agent to infer usage.

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