diagnose_user_blocks

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond the annotations: it aggregates across seven log types, groups and explains blocks (which layer blocked, why, what to check next), and with reported_url expands scope to related domains. It also implies a timeline construction. This is useful behavioral disclosure that goes beyond the structured fields.

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?

Two sentences, front-loaded with the most important usage signal ('START HERE'), and every clause earns its place. The first sentence covers scope, behavior, and output; the second covers the conditional expansion with reported_url. No filler or repetition of schema details.

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 complex diagnostic tool with 7 optional parameters and no output schema, the description gives a strong high-level picture: what logs are searched, what the output looks like (timeline, grouped/explained), and when to use reported_url. It doesn't detail the output format or edge cases (e.g., what happens with no results), but the description is sufficient for an agent to select and invoke the tool correctly, especially given the 100% schema coverage.

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%, so the schema already documents all 7 parameters. The description adds value by explaining the role of reported_url (flags blocks on OTHER domains) and implicitly the user/src_ip focus, but it doesn't add detail on period vs incident_time tradeoffs or max_groups semantics beyond what the schema provides. Baseline 3 is appropriate when the schema carries the parameter documentation burden.

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 directive ('START HERE for a ticket') and a specific verb ('Builds a timeline') tied to a concrete resource (everything that blocked a user or source IP across multiple log types). It explicitly names the log categories and the grouping/explanation behavior, and it distinguishes itself from sibling diagnostic tools by being the entry point for ticket diagnosis. This is a specific, non-tautological statement that an agent can act on.

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 explicitly says 'START HERE for a ticket', which is a strong when-to-use signal. It also names the alternative behavior with reported_url (flags blocks on OTHER domains at the same time), which tells the agent when to include that parameter. While it doesn't name a specific sibling to avoid, the 'START HERE' framing and the cross-log scope make the usage context clear and distinct from the many get_* and diagnose_* siblings.

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