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

Beyond the readOnly/idempotent annotations, the description discloses the most important behavioral fact: the tool 'opens nothing by itself' and instead returns procedural content (screens, buttons, fields). It also explains the follow-up tool family required to act and why the vendor API route is unavailable on lower plans, which is context an agent cannot get from annotations or an empty schema.

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?

Purpose and the 'opens nothing by itself' caveat are front-loaded in the first two sentences, which is the right order. The third sentence about the official API and MCP server is longer than needed for the decision at hand, though it does justify why this tool exists.

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 no parameters and no output schema, the description covers what is returned, what is not performed, and which tools carry out the action, which is enough to invoke it correctly. Minor gaps remain: it does not say whether the Cloud Browser session must already be authenticated, nor how to narrow the listing given that no filter parameters exist.

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 there is nothing for the description to disambiguate; baseline is 4. It could have noted that no date range or employee filter is accepted, which would preempt an agent trying to scope the listing, but the empty schema already makes that clear.

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 the resource (timesheets) and, crucially, clarifies that the tool does not fetch data itself but returns step-by-step instructions for performing the listing in Connecteam's UI. That resolves the ambiguity in the name 'list_timesheets', which would otherwise imply a data read. It stops short of naming sibling actions (e.g., approve_timesheet) it should not be confused with, so it is clear but not fully differentiated.

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 an explicit workflow: call this tool to get the procedure, then execute it with the cotlet_browser_* tools in the Connecteam Cloud Browser. It also rules out the official API/MCP server as a path for non-Expert plans. It does not state when this tool should be skipped or which sibling to prefer for related tasks like approvals, so it is clear context without exclusions.

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