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

Annotations cover the safety profile (readOnlyHint=true, openWorldHint=true), and the description adds real operational context: the silent default status filter, unix-seconds timestamps interpreted in the organization timezone, and the presence of time_summary in the reply. It doesn't state rate limits or result-size ceilings beyond the limit parameter's own bound.

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?

Four sentences, no filler, front-loaded with the resource and returned fields before the two behavioral gotchas (default status, paging). Every clause carries information an agent needs.

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 output schema, the description compensates by naming the returned fields and time_summary. All 9 parameters are non-required and fully documented in the schema, and the one dangerous default (status=working) is called out explicitly.

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 coverage is 100%, so the baseline is 3, but the description still adds meaning the schema lacks: status values framed as the working-vs-finished distinction, start-time filtering interpreted in the organization timezone, and next_page as the pagination cursor. This is genuine semantic value on top of an already well-documented schema.

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?

Opens with a specific verb+resource ('List time cards') and enumerates the returned fields (id, employee_id, start_dt_unix, end_dt_unix, status, approver, totals), so the agent knows exactly what comes back. It does not explicitly distinguish itself from workyard_get_time_card (single record) or workyard_list_time_card_activity_segments, though the scope is clear enough to infer.

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?

Gives a concrete, high-value usage rule: default returns only status=working, so pass status (e.g. submitted,approved) to get finished work. That is exactly the kind of condition an agent would otherwise get wrong. It stops short of naming sibling alternatives such as get_time_card for a single record.

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