beel_get_customer

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well covered. The description adds the endpoint, which is technical but not behavioral, and mentions 'complete details' about output, not behavior. It does not disclose error cases like 404 on missing customer, which would be useful but not critical given the read-only nature. Annotations carry most of the burden, and the description adds minimal value beyond that, so a 3 is appropriate.

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 that states the purpose, followed by the endpoint. It is concise, front-loaded, and contains no filler. Every word earns its place, and the endpoint provides a useful technical reference without bloat.

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 read operation with annotations covering safety and schema covering parameters, the description is largely complete. It tells the agent what the tool does and the context (per-company). The only gap is the lack of output structure, but since there is no output schema, the description could have mentioned that it returns the full customer object. However, for a get operation, the agent can reasonably infer the return shape from the resource. Overall, the information is sufficient 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 100%, with both company_id and customer_id having detailed descriptions in the schema. The description itself adds no parameter-specific meaning beyond the endpoint path, which is redundant. Since the schema already documents the parameters thoroughly, the description does not need to compensate, and the baseline score of 3 stands.

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 verb 'Retrieves' and the resource 'complete details of a customer', which is specific and unambiguous. It includes the exact endpoint, distinguishing it from list operations like beel_list_customers. The sibling differentiation is implicit via the endpoint path and the singular resource, making the purpose immediately 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 provides no guidance on when to use this tool versus alternatives. It does not mention that this is for fetching a single customer by ID, nor does it suggest using beel_list_customers for listing. The agent must infer usage from the name and parameter structure, which is not explicit. No exclusions or conditions are given.

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