Connecteam MCP by usefulapi

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

Annotations only declare the generic profile (readOnly=false, destructive=true, idempotent=false, openWorld=true). The description adds the operationally important side effects: the default is an unpublished draft employees cannot see, publishing triggers user notifications unless notify_users=false, and the 'title or job_id' server-side requirement. This is context the agent cannot derive from annotations or 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?

Front-loads the WRITE marker and single-shift scope, then layers defaults, required-field rule, and open-shift recipe in tight sentences. Every sentence carries a distinct constraint; the trailing endpoint reference is the only near-redundant element.

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 14-parameter mutation tool with no output schema, this covers defaults, publication behavior, notification behavior, and the assignee/open-shift fork adequately. It does not indicate what the call returns (e.g. the new shift id) or how to retrieve it afterward, which is a minor gap for a create operation.

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 3 is the floor, but the description adds cross-parameter constraints the schema states only in scattered property notes: the title/job_id either-or requirement and the coupled is_open_shift + empty assigned_user_ids rule. Useful consolidation, though largely duplicative of existing field descriptions.

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 ('WRITE: create ONE shift in a scheduler') and immediately bounds the scope by stating the V1 endpoint cannot create group or multi-spot shifts. An agent can distinguish this from connecteam_list_shifts and connecteam_get_shift without opening any 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?

Gives explicit conditional guidance: set is_published=true to publish, leave assigned_user_ids empty plus is_open_shift=true for an open shift, and supply either a title or job_id. It stops short of naming an alternative tool for the unsupported group/multi-spot case, so the routing guidance is strong but not complete.

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 safety profile (destructiveHint=true, openWorldHint=true, idempotentHint=false). The description adds valuable context: 'draft keeps it hidden; published sends it to assignees'apps' and 'several user ids make one group task' - behavior not captured in annotations. Minor gap: doesn't mention the destructive implications noted in annotations.

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 with WRITE prefix and action, then key behavioral notes, then API path. Efficient and well-organized, though the API path is somewhat redundant for an agent.

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?

Complete for a creation tool with full schema coverage and annotations. The status behavior and group-task semantics are the critical non-obvious details, and they're covered.

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 the schema fully documents all 9 parameters. The description reinforces the status enum semantics and group-task behavior for user_ids, adding some value, but baseline 3 is appropriate given the schema does the heavy lifting.

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 ('create one quick task on a task board') and scopes it. Clearly distinguishable from connecteam_list_task_boards, connecteam_list_tasks, and connecteam_list_task_labels 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?

Explains the draft/published status behavior which implies when to use each, but no explicit when-to-use-this-vs-alternatives guidance. No exclusions or prerequisites 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?

readOnlyHint=true already covers the safety profile, so the description only needs to add context. It does: the result is scoped to the credential itself ('this API key belongs to'), which tells the agent there is no way to target another account and that the call is a self-identity lookup.

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 plus the endpoint, with the returned payload front-loaded. Nothing is redundant or padded.

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, no output schema, and read-only annotations, the description carries the right load by stating exactly which fields come back. It stops short of noting failure behavior for an invalid/expired key, which would have made it fully self-contained.

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 the baseline is 4 and there is nothing for the description to clarify. The absence of parameters is consistent with the stated key-scoped behavior.

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 resource (the Connecteam company/account tied to the API key) and enumerates the returned fields (company name, company id), so an agent can distinguish it from the surrounding list_*/create_* siblings at a glance. It is clear but relies on the implicit verb 'get' and the endpoint rather than stating an action outright.

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?

There is no guidance on when to call this versus alternatives, nor any prerequisite or exclusion. The 'GET /me' reference implies it is the identity/whoami lookup, but that must be inferred rather than read.

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?

readOnlyHint=true already establishes the safe read profile, so the bar is lower. The description adds useful context by disclosing the returned sub-structures (sub-jobs, assignments, location) and the backing endpoint, but says nothing about auth needs, errors, or missing-id 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 short sentences, front-loaded with the core purpose and followed by the return contents. The endpoint string is marginally useful provenance rather than filler, so the text earns its place.

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 annotations covering safety and no output schema, the description supplies the key missing piece: what the response contains. Only edge-case behavior (nonexistent id, permissions) is omitted.

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 job_id parameter is fully documented in the schema, including its source (connecteam_list_jobs). The description reinforces 'by id' but adds no format or syntax beyond the schema, 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 (get) and resource (one job by id), and enumerates what the result contains: sub-jobs, assignments and location. It distinguishes a single-record fetch from a listing, though it does not name connecteam_list_jobs 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?

'One job by id' implies the single-record counterpart to connecteam_list_jobs, so usage is inferable, but there is no explicit guidance on when to prefer this over the list tool or any stated 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=true, so the safety profile is covered; the description adds real value by enumerating the returned content (assignments, statuses, breaks, notes, tasks) and the endpoint path. It stops short of noting auth scope or rate limits.

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 tightly packed sentences with no filler; the key retrieval scope and returned fields are front-loaded before the endpoint reference.

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 correctly carries the burden of describing return content, which it does at a summary level. It is nearly complete for a get-by-id tool, missing only explicit sibling routing and auth/limit context.

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% for both required parameters (shift_id with its source, scheduler_id), so the schema already documents them fully. The description adds no syntax or format detail beyond that, making the baseline 3 appropriate.

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 (get) and resource (shift) with clear scope: a single shift 'by its id' plus the fields it carries (assignments, statuses, breaks, notes, tasks) and the underlying endpoint. It implicitly distinguishes itself from connecteam_list_shifts, but never names the 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?

Usage is only implied: 'by its id' signals a single-resource lookup, and the schema notes the id comes from connecteam_list_shifts. There is no explicit statement of when to use this versus list_shifts or create_shift, and no prerequisites or 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?

With only readOnlyHint available, the description adds real behavioral context: the hard 45-day range cap, the REST endpoint, decimal hour units, and that pay rates appear only when defined. It does not discuss pagination, empty-range handling, or permission requirements.

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 dense sentences, front-loaded with the return content before filters and the endpoint. Every clause carries information, though the trailing endpoint reference is marginally redundant for an agent.

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 the burden of describing return values, and it does so thoroughly (per-user/day totals, break breakdowns, approval/submit/lock flags, pay items with rates). Combined with the stated range limit and filters, an agent has everything needed to call it correctly.

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 parameters are already fully documented in the schema. The description echoes the date-range limit and filter dimensions but adds no syntax or value semantics beyond what the schema provides; a 3 baseline is appropriate.

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 (get) and resource (timesheet totals of a time clock) with scope and content: per-user/per-day hours, flags and pay items. It is clearly distinguishable from siblings like connecteam_list_time_activities or connecteam_list_time_clocks, which are named/implied elsewhere.

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?

Conveys when the tool applies (payroll-ready totals for a time clock over a date range) and what can be filtered (users, groups, jobs, approval state). It does not explicitly name an alternative tool or state when not to use it, 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?

readOnlyHint=true already tells the agent this is a safe read. The description adds that questions are returned alongside forms and gives the underlying endpoint, which is mild extra context. It says nothing about pagination behavior or result size, so it does not go far beyond the annotations.

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 with the core purpose front-loaded and no filler. The trailing raw endpoint path (GET /forms/v1/forms) is the least valuable element but costs little.

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, zero-required-parameter list tool with full schema coverage and readOnly annotations, the description covers purpose, content of the response (forms with questions) and filterability. With no output schema, a brief note on return shape beyond "with their questions" and pagination would round it out, but nothing critical 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?

Schema description coverage is 100%, so all five parameters are already documented in the schema with formats, defaults and bounds. The description only restates that name and creation-date filtering exist, adding no syntax or semantics beyond the schema; 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 and resource (list forms) and clarifies the domain with examples — checklists, inspections, reports — plus the notable fact that questions are included. It does not explicitly distinguish itself from the closest sibling, connecteam_list_form_submissions, though the noun difference makes the split inferable.

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?

"Filter by name or creation date" implies how to narrow results, but there is no statement of when to reach for this tool versus connecteam_list_form_submissions or when not to use it. Usage is inferable from the name rather than given.

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?

readOnlyHint=true already establishes the safe-read profile, so the bar is lower; the description still adds value by disclosing the scope (one form at a time), the fields returned, and the filterable dimensions. It stops short of describing pagination behavior for the paged result set, which is a minor gap.

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 tight fragments: what is returned, how it can be filtered, and the endpoint. Content is front-loaded and no sentence is redundant.

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 sketches the response shape (submitter, timestamp, answers, status/owner/notes) and the filtering surface for a 6-parameter tool. It is slightly thin on how the return payload is structured and on pagination semantics, but the schema covers those inputs.

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 (limit, offset, form_id, user_ids, submitted_to/from) is already documented in the schema. The description's "filter by submitting users and time window" only restates two of those filters without adding format or boundary semantics, 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 gives a specific verb (list) and a precisely scoped resource (submissions of one form), and even enumerates what each submission contains (submitter, timestamp, answers, manager fields). This clearly separates it from siblings like connecteam_list_forms and connecteam_list_tasks.

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 states the available narrowing criteria (submitting users, time window), which implies how to use it, but never says when to choose this over a sibling or what prerequisites exist (e.g., that a form_id comes from connecteam_list_forms). Usage 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 declare readOnlyHint=true, so the safety profile is covered. The description adds genuine context beyond that: the domain model of jobs as the anchor for shifts/time, the relational scope (parent job and sub-jobs, schedulers/time clocks they belong to), and the presence of GPS/geofence data in results. It omits anything about the connecteam-specific include_deleted default, but the schema covers that.

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, front-loaded sentence that leads with the verb and the definition, then the returned fields, then the endpoint. It is dense but every clause carries information; the long comma-separated field list makes it slightly run-on.

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 enumerates what a returned job contains, which is the main gap a caller would otherwise face. Pagination and filtering semantics live in the schema. Nothing critical is missing, though a note on the deleted-jobs default behavior would round it out.

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 all nine parameters are documented in the schema itself (including the parent-id-returns-sub-jobs nuance and pagination via next_offset). The description adds no syntax or semantic detail about the parameters, 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?

Specific verb (List) plus resource (jobs), and it goes further by defining what a job is in domain terms ('the work items shifts and time are tracked against'). It enumerates the returned fields and names the endpoint, making it easy to distinguish from the sibling connecteam_get_job.

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 rather than stated: the filter parameters (job_ids, job_codes, job_names, instance_ids) signal this is a bulk/collection retrieval, but the description never says when to use it instead of connecteam_get_job for a single job, nor when to reach for connecteam_list_shifts. No exclusions or prerequisites are given.

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?

readOnlyHint=true already covers safety, and the description adds a GET endpoint and return-field list. It doesn't disclose pagination, auth, or rate-limit behavior, so with annotations carrying the safety profile, this is adequate but not rich.

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, front-loaded with purpose and returned fields. The API path is marginal but the description remains tight and non-redundant.

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 list tool, the description supplies the key return fields and the downstream dependency. That is enough for correct selection and 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?

The tool has zero parameters, so the baseline is 4. The description correctly adds no parameter detail because there is none to add.

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 uses a specific verb ('List') and resource ('job schedulers (schedules)'), names the returned fields, and connects the scheduler id to shift operations, which distinguishes it from sibling shift tools. An agent can identify it as the entry point for scheduler IDs 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?

It states the operational dependency: the scheduler id is needed to list or create shifts, which tells the agent when to call this tool. It stops short of naming an explicit alternative or exclusions, so it's clear but not exhaustive.

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?

With readOnlyHint=true already covering the safety profile, the description still adds real behavioral context: it discloses the V1 endpoint returning one row per assigned user (an important shape quirk given no output schema), names the upstream route, and enumerates the returned fields. Pagination semantics live in the schema rather than here, which keeps 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?

Front-loads purpose and scope, then the returned-field inventory, then filtering, then the endpoint. Dense but nearly every clause carries information; the long field enumeration is justified by the absence of an output schema.

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 13-parameter read tool with full schema coverage and no output schema, the description supplies the missing pieces: scope, row granularity, returned fields, and filter dimensions. Only pagination behavior and any rate/failure notes are left implicit.

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 one of the 13 parameters is already documented, including formats, bounds, and defaults. The description restates four filter categories (assigned users, job, open, published) without adding syntax, constraints, or interaction rules beyond the schema. 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 and resource with explicit scope: 'List shifts of one scheduler in a time window'. The parenthetical 'one row per assigned user' pins down the granularity, which is what separates this from connecteam_get_shift, and the enumerated returned fields make the tool's output identity unmistakable.

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 filters sentence ('Filter by assigned users, job, open or published') implies when the tool is useful for narrowing a range, but there is no explicit when-to-use vs connecteam_get_shift and no stated conditions or exclusions. Usage is inferable from context but never spelled out.

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 readOnlyHint annotation already declares this is a safe read. The description adds the endpoint path (GET /tasks/v1/taskboards) and the returned field set, but says nothing about pagination, auth scope, or result limits, so it adds only modest context beyond the annotation.

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 with the purpose and the key returned fields front-loaded. The trailing raw endpoint string is marginally useful and the only element that does not directly aid tool selection.

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 must convey return values, and it does so at a summary level (id, name, archived). For a parameterless list tool with a readOnly annotation, this is nearly complete; pagination behavior is the main unaddressed detail.

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 the baseline is 4. The listed fields (id, name, archived) describe the response, not inputs, so there is no parameter ambiguity to resolve.

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 the quick-task boards') and even enumerates the returned fields (id, name, archived). The note that the board id feeds task listing/creation implicitly separates it from connecteam_list_tasks, though it never names the sibling directly.

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 sentence 'The board id is needed to list or create tasks' gives clear prerequisite context: call this first when you need a board id. There are no explicit exclusions or named alternatives, so it stops 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 the description adds the HTTP method (GET) and return fields, which reinforces the read-only nature. It does not disclose pagination behavior, rate limits, or error handling beyond what the schema already covers.

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 plus a short endpoint reference, front-loaded with the purpose and return fields. Every part earns its place with no redundancy.

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?

No output schema exists, but the description lists the returned fields (id, name, color), and the schema fully documents parameters. Annotations cover the read-only safety profile. Pagination behavior is not described, though the schema supplies limit and offset details.

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 the schema fully documents all four parameters with defaults and constraints. The description adds no parameter-level information beyond what the schema provides, 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 and resource ('List the labels of a task board'), names the returned fields (id, name, color), and implicitly distinguishes itself from siblings like list_task_boards and list_tasks by scoping to labels.

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?

Provides clear usage context ('for filtering tasks or labelling a new one') but does not explicitly state when not to use it or name alternative tools. No exclusions or prerequisites are given.

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, so safety is covered; the description adds real value by disclosing the shape of what comes back (field list, status vocabulary draft/published/completed, Unix-seconds timestamps). Pagination semantics live in the schema rather than the description, so it stops 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?

Two sentences, front-loaded with the action and resource, followed by returned fields, then filters and the endpoint. The field enumeration is dense but earns its place since there is no output schema; nothing is redundant.

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, describing the returned fields is genuinely necessary and done well, and all 7 parameters are covered by the schema. Missing are guidance on pagination behavior in the description text and any cross-reference to how task_board_id is obtained.

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 bounds, defaults and enum values. The description restates the filter axes but adds no syntax or format detail beyond the schema, which is the baseline-3 case.

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 ('List tasks on a task board'), then enumerates the returned fields (title, assignee ids, status, times, labels, sub-tasks) and the supported filters. This clearly separates it from siblings like connecteam_list_task_boards and connecteam_list_task_labels.

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 filter dimensions (status, users, labels, task ids) and gives the underlying endpoint, which implies retrieval usage, but it never states when to reach for this tool versus e.g. connecteam_list_task_labels or a single-task lookup. No prerequisites or exclusions are given.

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 readOnlyHint=true, so the safety profile is set. The description adds real behavioral context beyond annotations: the 31-day cap per call, grouping by user, the specific fields emitted (start/end, job, sub-job, notes, auto clock-out), and the underlying REST route. It doesn't discuss pagination or whether users removed from a clock appear, but the 31-day rule is a meaningful operational disclosure.

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 dense, front-loaded sentences that pack the noun phrase (what it returns), the cardinality constraint, grouping semantics, and the route. Slightly overloaded with parenthetical field lists, but every clause carries 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 read-only list tool with a fully documented schema and no output schema, the description supplies the one thing the schema cannot: the 31-day cap and grouped-by-user shape. Return-value detail is absent but acceptable for a listing endpoint; pagination behavior would have pushed it to 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%, so the schema documents all six parameters including the date pattern and filter semantics. The description restates filters ('by users, jobs or activity type') and the date-range constraint without adding format or edge-case detail beyond the schema, making the baseline 3 appropriate.

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 (clock-in/clock-out records of a time clock) with a precise scope (date range, grouped by user) and enumerates the record types returned. Clearly distinguishable from siblings like connecteam_list_shifts and connecteam_get_timesheet_totals by naming the time-clock activity domain directly.

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 31-day-per-call limit is stated, which is a usage constraint, and the description notes filtering options. However, it never says when to choose this tool over alternatives such as connecteam_list_shifts (a very close sibling) or connecteam_get_timesheet_totals, so the agent must infer the boundary between aggregate totals and raw activity records.

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?

readOnlyHint=true already declares the safe read profile. The description adds the returned field set and the endpoint path, which is useful, but says nothing about pagination, ordering, or whether archived clocks are included or filtered.

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 plus the endpoint path; the key information (what it lists, the fields, why the id matters) is front-loaded. The raw GET path is slightly redundant but not disruptive.

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-only list with no output schema, disclosing the returned fields and the downstream use of the id is nearly complete. The only gap is return volume/pagination behavior, which is minor here.

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 and the schema is empty, so there is nothing to document; baseline 4 applies. The description correctly implies no filtering inputs are required.

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 the time clocks in the account') and enumerates the returned fields (id, name, archived). It is clearly distinguishable from the many list_* siblings, though it does not explicitly name which sibling to use instead.

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 provides usage context by noting the time clock id is needed for time activities and timesheets, implying when to call it. However, there is no explicit when-not guidance or named alternative among siblings.

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 readOnlyHint annotation already establishes this is a safe read. Beyond that, the description adds the HR & Skills hub dependency and, importantly, sketches the payload shape (policies with unit and accrual type) even though no output schema exists. It still doesn't cover pagination or result size, but the added 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?

Two tight sentences with zero filler: purpose plus examples first, prerequisite second. The endpoint path is appended compactly rather than padding the 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 present, the description usefully names what comes back (policy types and their policies with unit and accrual type) and flags the required hub. Only pagination and any filtering/ordering behavior remain unstated, which is a minor gap for a parameterless 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. No parameter-level detail is needed or expected here.

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 (List) and resource (time-off policy types), with concrete examples (Vacation, Sick) and a note on the returned fields (unit, accrual type). It distinguishes itself from connecteam_list_time_off_requests by targeting policy definitions rather than requests, though it never names that 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 description gives a prerequisite ('Needs the HR & Skills hub') which is genuinely useful gating information, but offers no guidance on when to choose this over the nearby list_time_off_requests tool. Usage is implied by the resource name 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?

Beyond readOnlyHint=true, the description discloses the implicit status filter default, the 365-day range cap, the hub entitlement requirement, and the underlying endpoint. That is real behavioral context an agent needs to avoid silently missing pending/denied requests, though pagination and rate behavior are left to the 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?

Three sentences, front-loaded with purpose and range constraint, then the default-filter caveat, then the access requirement. The long field enumeration is slightly run-on but serves as a return-value substitute given no output schema.

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 returned fields and clarifying the approved-only default; it also states the hub prerequisite and date-range limit. Nothing an agent needs to invoke this correctly 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?

Schema description coverage is 100%, so the schema already documents limit, offset, dates, statuses, and user_ids. The description restates the status default and the 365-day bound but adds no syntax or format detail beyond the schema, which is the expected baseline when structured fields carry the load.

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 time-off requests') plus the scoping semantics ('overlapping a date range'), and enumerates the returned fields, so it is clearly distinguishable from siblings like connecteam_list_time_off_policy_types. An agent knows exactly what this yields 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?

Gives a concrete prerequisite ('Needs the HR & Skills hub') and a critical calling caveat ('returns only approved requests unless statuses is given'), which tells the agent when the default output is incomplete. It stops short of naming alternative tools or explicit when-not-to-use conditions.

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?

readOnlyHint=true already establishes the safety profile, and the description adds real value on top: the fields returned, plus the disclosure that kiosk codes and device ids are never exposed. It stops short of describing paging behavior or result limits, which the agent must infer from the 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?

Three tight sentences: what is returned, why you would call it, and one important exclusion. The return fields are front-loaded and nothing is wasted.

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 correctly carries the burden by enumerating the returned fields, and the schema handles pagination via next_offset. Slightly incomplete in that it does not describe response shape or how paging interacts with large result sets.

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 all ten parameters are already documented with formats, ranges and defaults. The description only implicitly relates the returned fields (email, phone, status) to the filter parameters and adds no new semantics for sort, order, limit, offset or modified_since.

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 employees (users)') and enumerates the returned fields, so the agent knows exactly what this returns. It is clearly distinguishable from every sibling, none of which list users.

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 use case: mapping user ids appearing in shifts, time activities, timesheets, time off and tasks back to names. There is no competing sibling to exclude, but it never states a when-not-to-use condition (e.g. single-user lookup) or the paging requirement for large accounts.

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