Summarise visibility for a period

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

Annotations indicate readOnlyHint=true and openWorldHint=true, so the description doesn't need to state that it's a read operation. The description adds context about the comparison with the previous period, which is useful behavioral information. However, it doesn't clarify that the period must be within 366 days (though the schema describes that for endDate), or mention any other restrictions such as the need for an active project. Since the annotations carry the safety profile, the description adds moderate value without contradicting, 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 concise, with two focused sentences. The purpose is front-loaded at the start, and the guidance for when to use alternatives and how to use the 'by' parameter is efficiently packed. No fluff is present; every phrase adds value.

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?

Given the tool's complexity (6 params, all optional, with enums) and the fact that there is no output schema, the description is complete enough for an agent to know when and how to call it. It covers the main use case ('how visible are we'), the alternative route, and the key parameter behavior. It doesn't explicitly mention the comparison with the previous period in the parameter section, but it is mentioned in the description. It might benefit from noting that 'limit' is ignored without 'by', but the schema already says that, so the description doesn't need to repeat it. Overall, it's well-rounded for the purpose.

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?

The schema description coverage is 100%, meaning the schema already documents all parameter semantics. The description, however, adds explanatory value for the 'by' parameter (e.g., 'day for a trend line, model to compare assistants, prompt to rank the prompts') that goes beyond the schema's brief description. It doesn't add much for other parameters, as the schema covers them well. With high schema coverage, a baseline of 3 is correct, but the description earns its place by illustrating parameter usage.

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 specifies the verb ('Summarise'), the resource ('visibility for a period'), and the key behavior ('headline visibility figures' and 'how they moved against the period before it'). It also distinguishes itself from the sibling tool get_visibility_timeseries, explicitly stating which to call for what. This is a clear, specific definition that sets it apart.

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: 'This is the tool to call for "how visible are we"' and tells when to use the alternative: 'use get_visibility_timeseries only when the individual measurements behind the number are needed.' It also explains how to use the 'by' parameter for different analysis scenarios. This is explicit and actionable guidance.

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