get_job_logs

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It goes beyond a basic statement by explaining pagination, log level precedence ('Ignored if log_levels is provided', 'Takes priority over min_level'), and the order of log levels. However, it does not mention edge-case behaviors such as error handling, timezone assumptions for timestamps, or log ordering, so it is not fully exhaustive.

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 well-structured: a one-sentence purpose, two sentences for tool selection, a brief note on log level ordering, and a clean Args list. No sentence is redundant; the structure makes scanning easy.

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 an 8-parameter tool with no annotations and zero schema coverage, the description covers all parameters, usage guidance, and behavioral nuances. The presence of an output schema means return values need not be explained. Minor gaps include no mention of timestamp timezone handling, log ordering, or behavior when the job is not found, keeping it from being fully complete.

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, and it does so thoroughly. Every parameter gets a plain-language explanation: job_id, folder_name, batch_size, skip, min_level, log_levels, start_time, and end_time. It even clarifies the relationship between min_level and log_levels, which is not evident from the schema alone.

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 opens with a clear and specific verb-resource pairing: 'Retrieve paginated robot execution logs for a specific job.' It also explicitly distinguishes itself from the sibling tool diagnose_job by contrasting use cases, making it unmistakably distinct.

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 explicit when-to-use guidance: 'Use diagnose_job instead when the goal is to understand a failure' and 'Use get_job_logs when you need full log pagination, specific time ranges, or log levels that diagnose_job doesn't surface.' This directly names an alternative and gives clear usage boundaries.

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