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

Annotations already declare readOnlyHint/idempotentHint/non-destructive, and the description adds real context beyond that: it returns instructions rather than performing work, it opens nothing, and it notes ClockShark has no public developer API (with a checked date). The main undisclosed behavior is how a parameterless call can target a specific timesheet — the guide is evidently generic, but that is never said.

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?

Front-loaded and efficient: the scope, the return content, the do-not-act warning, and the follow-up tool family all appear in two sentences. Minor filler exists in 'from ChatGPT, Claude or any AI agent,' which adds no decision-relevant information.

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 zero-parameter, no-output-schema helper, the definition covers what it returns and what to do next, which is the core need. It omits prerequisites an agent might care about — whether the user needs manager/admin rights to approve timesheets in ClockShark — but nothing essential to invoking it is missing.

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 tool takes zero parameters, so per the baseline this scores 4. The description adds nothing about parameters because there are none, and it correctly communicates that the returned guidance is the payload rather than a targeted action.

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?

Names a specific verb+resource (approve timesheet) in the user's ClockShark account, then corrects the likely misreading by stating it only returns a step-by-step how-to and performs no action itself. The tension between the name and the actual guide-generation behavior is resolved, but only after a first sentence that could be read as 'this tool approves the timesheet,' so it falls short of a clean 5.

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?

Explicitly states the two-step usage pattern: call this first to get screens/buttons/fields, then execute via the cotlet_browser_* tools in the ClockShark Cloud Browser. It does not explain when not to use it (e.g., if the user only wants the call guide, or which specific browser tools follow), and gives no guidance relative to siblings like clockshark_list_time_entries or cotlet_app_guide.

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