beel_get_request_log

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so safety is known. The description adds valuable behavioral detail: it explains the scope is per-person, not per-credential, describes 404 conditions (including 'another user of this same account'), and highlights security implications ('reads the traffic of your privileged keys too'). It also clarifies the effect of the timestamp parameter on the search window. These insights go well beyond the annotations and are crucial for correct and safe usage.

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 compact and front-loaded: the first sentence states the core purpose, followed by a clear 404 note, a security caveat, and the endpoint. Each sentence earns its place, and the bolded emphasis highlights the key scoping rule. There is no fluff, and the structure guides the reader from purpose to caveats to endpoint efficiently.

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 has 3 parameters, a rich set of annotations, and no output schema, so the description must carry the return-value information. It does so by stating 'Returns the full detail (bodies and headers)'. It also covers error semantics (404), the security scope, and the optional timestamp behavior. Everything an agent needs to call this tool correctly and interpret its result is present. The description is fully adequate for the tool's complexity.

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 coverage is 100%, so each parameter already has a description. The description adds extra meaning: it explains that account_id 'authorizes the call; it does not widen what you can see', and that timestamp 'narrows the search window around that instant so the detail also works for logs older than the default window'. These are non-obvious behaviors that the schema does not convey. The request_id is simply called a correlation identifier, which the schema already states. This adds value beyond the raw schema, earning a 4.

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 what the tool does: 'Returns the full detail (bodies and headers) of a request made by you, with any of your API keys in this environment'. It specifies the resource (a request log entry) and the exact scope (traffic from the caller's own keys). It also contrasts with the sibling list tool implicitly by calling itself 'the widest read the logs:read scope opens', distinguishing it from a simple list operation. It is unambiguous and specific.

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 context on when to use this tool: it is the detail view for request logs, and it emphasizes that the account_id 'authorizes the call; it does not widen what you can see', guiding the agent on its limitations. It also notes that 'a key holding only logs:read reads the traffic of your privileged keys too', which is a caution about security implications. However, it does not explicitly name the sibling tool (beel_list_request_logs) or state 'use this instead of the list tool when you need full bodies/headers', so the contrast is implied rather than direct. Still, it gives clear situational context.

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