Diagnose service

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

The description adds behavioral context beyond the readOnlyHint annotation by stating that the tool collects 'recent' log evidence (implying a recency limit) and that it does not attempt root-cause analysis. This gives the agent important expectations about the tool's output depth. However, it leaves out details about approval_token, debug_session_id, or how the tool interacts with debug sessions, which might affect behavior.

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, focused sentence that conveys the action, scope, and a key limitation. Every word adds value, and there is no redundant information or filler.

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 tool with 9 parameters and no output schema, the description is notably sparse. It lacks details about return values, how to select the specific deployment, and how this tool relates to the many diagnostic siblings. The absence of output schema means the description should at least hint at what the collected evidence looks like, which it does not.

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?

With 0% schema description coverage, the description must compensate, but it does not mention or explain any of the 9 parameters. It says 'for one deployment' but never maps that to deployment_id or clarifies the roles of env_name, project_id, service_id, etc. The agent has little guidance on how to construct a valid invocation or how parameters relate to the intended operation.

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 tool's function: to collect runtime status and recent log evidence for one deployment. It also explicitly distinguishes itself from other diagnostic tools by adding 'without claiming root cause', which differentiates it from analysis-oriented siblings like analyze_trace_logs.

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 clear context for when to use the tool: when you need raw evidence (runtime status and logs) without aiming for a root-cause conclusion. The phrase 'without claiming root cause' serves as a built-in exclusion, implying alternatives like analyze_trace_logs would be used when root-cause analysis is desired. However, it does not explicitly name any alternative tools or provide a full when-to-use/when-not-to-use matrix.

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