Workyard MCP by usefulapi

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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false; the description reinforces this with 'adds a new note on every call' and 'does not edit or delete existing notes'. That said, it adds little beyond restating the non-idempotent and non-destructive profile, and says nothing about permissions or failure behavior.

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?

Two compact sentences with the operation type front-loaded and the append-only semantics immediately after. No filler.

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?

Covers operation, target scope and mutation semantics for a simple two-param write tool with no output schema. Minor gap: no mention of auth or rate limits for a write endpoint.

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%, so both parameters (description note text, time_card_id) are already documented. The description only implies the note text and target card, adding no syntax or format detail beyond the schema, so baseline 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?

States a specific verb (add), resource (text note) and scope (one time card), and pins it to an endpoint shape. It also distinguishes append-notes behavior from editing records, so an agent can tell it apart from the GET/list siblings.

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 'WRITE:' prefix and 'one time card' scope clearly signal when this tool applies versus the read-only list/get siblings. It does not name an explicit alternative or state exclusions, so it falls short of a 5.

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

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

Beyond the annotations (destructiveHint=true, idempotentHint=true, openWorldHint=true), it discloses the downstream consequence that approval feeds payroll and may not be undoable via the API. That is exactly the kind of context annotations cannot convey. It is consistent with destructiveHint=true rather than contradicting it.

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?

Two sentences, front-loaded with the WRITE marker and the verb, zero filler. The irreversibility warning is placed before the guardrail clause, so the highest-risk information lands first.

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 destructive one-parameter mutation with no output schema, the description covers the essential risk profile and the exact-call guardrail. The notable gap is preconditions: it never says whether the time card must be in a pending/unapproved state, which matters for an agent choosing when to call.

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?

With one parameter at 100% schema coverage, the schema already documents time_card_id fully, and the description only reinforces that a single specific card is targeted. No additional semantics (valid ranges, statuses, how to obtain the id) are added, so the baseline 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?

States a specific verb (approve), a single resource (ONE time card), and even the underlying endpoint (PATCH .../time_cards/{id}/approve). The emphasis on ONE cleanly separates it from the list/get siblings, which read time cards rather than mutate them.

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 an explicit gating condition: only call it when the user asked to approve this exact time card, which rules out speculative or batch usage. It does not name an alternative path (e.g., use workyard_get_time_card first to confirm status), so it falls short of full when/when-not/alternatives guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the source endpoint (GET /orgs/{org_id}) and a sketch of the returned payload, but nothing about error behavior if the connection lacks an org, or how settings are shaped.

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?

A single sentence with the resource front-loaded and the payload details trailing in a parenthetical. The endpoint reference is arguably redundant but short enough not to hurt scannability.

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 has to convey the return shape, and it does so at a high level (id, name, settings such as timezone). For a trivial zero-arg read this is close to sufficient, missing only edge-case behavior.

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, which is the baseline-4 case; there is nothing for the description to disambiguate. The one useful addition is clarifying that org_id is derived from the connection rather than supplied by the caller.

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?

States a specific verb+resource: retrieves the organization bound to this connection, and enumerates the fields returned (id, name, settings such as timezone). This clearly distinguishes it from the project/employee/time-card listing siblings, though it never names a sibling explicitly.

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 phrase 'this connection uses' implies a current-context lookup rather than a search, which is implicit guidance. There is no explicit statement of when to call it versus alternatives, nor any prerequisite or follow-up guidance.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds nothing further, such as behavior when the id does not exist. With annotations carrying the load, a 3 is the right minimum-viable score.

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?

One short sentence with the key fact and the sibling pointer front-loaded, and no filler. It is efficient, though the telegraphic phrasing reads more like a note than a specification.

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 single-parameter getter with full schema coverage and a readOnly annotation, the description covers what the agent needs in order to call it correctly. The main remaining gap is what happens on a missing id, which pushes it just below a 5.

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% and the single project_id parameter is fully documented there, including the org_project_id note. The description only restates 'by id', adding no format or validation detail beyond the 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?

States a specific verb and resource: retrieve a single project by id. It implicitly contrasts with the sibling list tool by saying 'One project', so an agent can distinguish it from workyard_list_projects without reading the schema.

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?

Names workyard_list_projects as the way to obtain ids, which routes the agent to the correct sibling when it lacks a project_id. It gives no explicit exclusion or prerequisite beyond that, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds only 'with its details' — it does not say what details are included or how a missing/invalid id behaves, so added context beyond annotations is thin.

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?

One sentence with zero waste, and the resource plus the id source are front-loaded. The telegraphic style ('One time card by id') is slightly clipped but not ambiguous.

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 one-parameter read tool with no output schema, this covers what it returns ('its details') and how to get the id. The only gap is not enumerating what those details contain, which is minor given the tool's simplicity and the absence of an output schema.

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% and the single parameter is documented in-schema as 'The time card id.' with a positive integer constraint. The description's 'by id' merely restates this, so the baseline 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?

States a specific resource (a single time card) fetched by id, and the parenthetical names the sibling that produces ids, which separates it from workyard_list_time_cards. It never says 'get'/'fetch' explicitly, but 'One time card by id' is unambiguous.

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 parenthetical 'workyard_list_time_cards gives the ids' tells the agent exactly where to obtain the required input, which is the key routing decision for this tool. It does not state what to do if the id is unknown or invalid, so it stops short of explicit exclusions.

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

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

Annotations already declare readOnlyHint and openWorldHint, so safety is covered. The description adds that results are 'active' only and carry 'limited data', but never says which fields are omitted or how active is determined, which matters since there is no output 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?

Two short sentences, front-loaded with what is returned and followed by the routing note. The phrase 'limited data' is efficient but vague enough to leave a question open.

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-param read tool with no output schema, the description should convey the shape of the returned geofences; 'limited data' gestures at this without specifying fields. The routing guidance is complete, but the return-value picture is not.

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 no parameters, so there is nothing to disambiguate and the baseline of 4 applies. The description correctly does not waste space on parameters.

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?

States a specific verb and resource ('All active geofences') plus the underlying API call, and flags the 'limited data' scope. It doesn't explicitly contrast with the sibling workyard_list_geofences, so an agent must infer the difference between 'active' and the full list.

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 an explicit exclusion ('does not say who is clocked in') and names the alternative tool with the parameter needed (workyard_list_time_cards with status working). It stops short of saying when to pick this over workyard_list_geofences or workyard_list_geofence_projects.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds behavior beyond that: pagination via next_page, and the fact that the four status values define the full status space. It doesn't mention rate limits, default page size in prose, or authorization/scope requirements, keeping it short of a 5.

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?

Three compact sentences, front-loaded with the core purpose and return shape, then filters, then paging. The dense parenthetical field list is efficient rather than verbose. Slight density cost from cramming enumerations into parentheses instead of prose.

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 listing the returned fields, which is the key gap it needed to close. For a 7-parameter, all-optional filter tool with full schema coverage, an agent has enough to call it correctly. Only missing pieces are default limit and empty-result behavior.

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%, so every parameter is already documented with format, bounds and comma-list semantics. The description restates status, email, role name and search filters almost verbatim from the schema, adding little; the parenthetical field list is return-value information rather than parameter meaning. Baseline 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?

Opens with a specific verb+resource ('List employees of the organization') and enumerates the returned fields (employee_id, profile_id, name, title, role, status, contact data), so an agent knows exactly what it gets back. It never names a sibling to differentiate against, but no sibling tool competes for the same resource (the others cover time cards, projects, geofences).

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?

Usage is implied through the filter enumeration ('Filter by status ... email, role name or free-text search') and a pagination instruction ('Paged: use next_page'), which tells the agent how to iterate. There is no explicit statement of when this tool is preferred over another or any exclusions/prerequisites, so it stops at implied guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety profile needs no restating. The description adds the paged nature of the response and the next_page continuation mechanism, which is genuinely useful behavioral context, but says nothing about result shape, default limit behavior, or empty results.

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?

Two short fragments with no waste, and the scoped subject is front-loaded ahead of the pagination note. Slightly telegraphic phrasing ('Paged: use next_page') costs it the top mark.

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 simple read-only list tool with full schema coverage, one required id, and annotations covering the safety profile, the description supplies what an agent needs to call it and page through results. The lack of any indication of what a returned project contains is a minor gap since no output schema exists.

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 every parameter (page, limit, geofence_id, is_archived) is documented inline, so the baseline of 3 applies. The description's only added semantics is the paging hint, which the schema already covers.

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?

States the specific resource (projects) and the exact scope (attached to one geofence/work site), so an agent can distinguish it from workyard_list_projects and workyard_list_geofences. It falls short of 5 only because it doesn't explicitly name the alternative tools it is not.

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 phrase 'Paged: use next_page' gives concrete pagination guidance, and the required geofence_id implies usage after workyard_list_geofences. However, there is no explicit when-to-use/when-not statement or named alternative, so the guidance is implied rather than stated.

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

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

Annotations already establish read-only and open-world behavior, and the description adds two things annotations cannot: the shape of returned records and the pagination contract ('Paged: use next_page'). It stops short of stating effective default page size at runtime or any rate limits, but the added context is meaningful.

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?

Three short sentences, zero filler: what it lists and the fields, what can be filtered, how paging works. The most decision-relevant information leads.

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 read-only list endpoint with fully documented parameters and no output schema, the description covers purpose, filters, returned fields and pagination. The only remaining gap is disambiguation from the active-geofences sibling, which matters for correct tool selection.

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%, including the eq:/like: name semantics and next_page guidance, so the schema carries the parameter burden. The description only restates the filterable fields at a high level, adding nothing the schema does not already say.

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?

States a specific verb and resource ('List geofences / work sites') and enumerates the returned fields (id, name, place, enabled, radius), so the agent knows exactly what comes back. It does not distinguish itself from the sibling workyard_list_active_geofences, leaving the reader to infer that this is the unfiltered/all-states variant.

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 names the available filters (name, enabled state, project), which implies when each is useful, but it never states when to prefer this over workyard_list_active_geofences or how to chain it with workyard_list_geofence_projects. Usage is inferable rather than guided.

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

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

Annotations already declare readOnlyHint and openWorldHint, so safety is covered; the description adds the pagination contract ('Paged: use next_page') and the shape of each returned record. It stops short of noting rate limits, auth requirements, or Workyard default page size behavior, but that is a modest gap given annotation coverage.

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?

Two short sentences with zero filler; the returned fields and the filter capability are front-loaded, and the paging hint is placed last where it belongs.

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 usefully lists the fields each project record contains and explains the paging continuation, which is enough to call the tool correctly. It omits any mention of include_computed_totals' effect on payload size, a minor completeness gap for a 5-parameter list tool.

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 itself documents the prefix/eq:/like: name matching, page/limit bounds, and the is_archived semantics. The description only restates the name and archived filters without adding syntax or edge-case meaning, so it sits at the baseline for full schema coverage.

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?

States a specific verb and resource (list projects) and enumerates the returned fields (id, name, identifier, customer, locations), which clearly separates it from workyard_get_project. An agent can identify the tool's job without opening the schema.

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?

Mentions optional filtering by name or archived state and points to next_page for paging, which is useful context. But it never states when to prefer this over workyard_get_project or workyard_list_geofence_projects, nor any exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint and openWorldHint, but the description contributes a genuinely behavioral fact not present in structured data: "Not paged." That tells the agent it receives the full segment set in one response and need not loop on cursors — exactly the kind of context the annotations don't cover.

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?

A single compact sentence with the resource and payload scope front-loaded, followed by the non-paging caveat. Nothing is padded, though the phrasing "The activity segments of one time card" drops the verb, making it slightly less immediately actionable than it could be.

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 carries some burden for return shape; it gestures at segment contents (location and project) but says nothing about other likely fields, ordering, or whether segments are chronological. Adequate to call correctly, incomplete for interpreting the result.

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%, with both time_card_id and include_archived_projects documented inline, so the baseline is 3. The description reinforces the singular time-card scoping but adds no format, ordering, or filtering meaning beyond the schema, and never mentions the archived-projects toggle.

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 names the concrete resource (activity segments of a single time card) and adds parenthetical content scoping — where and on which project the employee worked — which makes the payload concrete. It is distinguishable from siblings like workyard_get_time_card or workyard_list_time_cards, though the action verb itself is only carried in the title, not the description body.

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?

"of one time card" implies the tool is used once you have a time_card_id, and the required parameter confirms that context. There is no explicit when-to-use guidance relative to workyard_get_time_card or workyard_list_time_cards, and no stated exclusions or prerequisites.

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

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.