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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world behavior. The description adds useful behavioral detail beyond annotations: the output is a project-by-day grid with totals and includes weekdays with nothing logged, and non-billable days still count. It does not describe pagination or auth, but the added shape context is substantive.

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 front-loaded with the return shape and then gives usage context. Every sentence carries useful information, and the dense enumeration of grid contents is appropriate for a tool whose value depends on knowing what the grid includes.

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?

With annotations covering safety traits and an output schema present, the description does not need to explain return values in full. It covers date-range scope, optional client/project filtering, grid contents, and inclusion of non-billable days. Minor omissions such as timezone or maximum range handling keep it from being fully complete, but it is sufficient for correct invocation.

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%, and the schema already explains from/to as inclusive YYYY-MM-DD and client/project as id or name. The description confirms that client and project are optional filters for one client or one project, but adds little syntax or constraint detail beyond the schema, so the baseline of 3 applies.

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 states a specific verb and resource — retrieving a timesheet for a date range — and details the returned shape: one row per project, hours per day, totals, and empty weekdays. This distinguishes it from generic entry listing or project-total tools by emphasizing a grid timesheet view.

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?

It gives clear usage context: "Use this to 'show me my timesheet for last week' or to check a sheet before sharing it," which connects naturally to share_timesheet. It does not explicitly exclude alternatives like list_entries or project_totals, so it stops short of a full when/when-not routing rule.

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