Tamigo MCP by usefulapi

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds that results include both normal and special hours grouped per department, but says nothing about how pagination behaves or what the response structure looks like.

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 returned content front-loaded and the scoping constraint immediately after. The raw endpoint path adds limited value for an agent but is short and harmless.

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?

There is no output schema, so the description carries some burden for explaining return values; naming 'normal and special opening hours per department' covers the content dimension. It does not describe how normal vs. special entries are distinguished in the payload, which is the main remaining gap for a lookup 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%, so start_date, end_date, limit and offset are fully documented in the schema itself. The description only echoes the date-range concept and introduces 'per department', which is not an input parameter and could momentarily confuse an agent looking for a department filter. 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 (opening hours) with scope modifiers (normal and special, per department, for a date range), so an agent knows exactly what it returns. No sibling is named as an alternative, but the sibling set (absences, shifts, employees, revenue) has no overlap, so differentiation is implicit rather than stated.

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 the 'date range' scoping and the GET path; there is no explicit when-to-use, when-not-to-use, or alternative named. For a read-only listing tool with no competing sibling this is adequate but thin.

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, openWorldHint and destructiveHint=false, so safety is covered. The description adds some real value by disclosing the projected fields (employee, department, type, dates, approval status) and the overlap semantics, plus the GET endpoint. It stops short of stating the default page size or that results span all employees.

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 lists the scope, the semantics and the returned fields, followed by the endpoint. Nothing is padding.

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 compensates by enumerating return fields and the overlap rule. It leaves minor gaps an agent might want: whether cancelled/pending requests are included, and whether the result is scoped to all employees or only the caller's team.

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 adds a genuine semantic: start_date/end_date act as an overlap filter rather than a containment filter, which the schema's 'First day / Last day' wording does not convey. The limit/offset pagination is left entirely to the schema, which already documents it fully.

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 a specific verb and resource ('All absences ... holiday, sickness, leave'), scopes it to an overlapping date range, and enumerates the fields returned. That is enough for an agent to distinguish it from siblings like tamigo_list_shifts without consulting 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?

'That overlap a date range' implies the reporting context, but the description never states when to prefer this over tamigo_list_shifts or tamigo_list_employee_details, nor any exclusions or prerequisites. Usage is inferable and nothing more.

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 carry readOnlyHint=true, openWorldHint=true and destructiveHint=false, so safety is covered. The description adds value annotations cannot: the concrete returned field set (DepartmentId, DepartmentKey, Name, IsDefault, ParentDepartmentId) and the underlying endpoint. It does not mention pagination behavior or result size, but that lives in 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?

A single dense sentence, front-loaded with the verb and resource and followed by the returned fields. The trailing 'GET /departments/application/' is endpoint trivia that adds little for an agent, a minor waste in an otherwise efficient definition.

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 compensates by listing the returned fields and their meanings (GUID vs POS key), which is exactly the missing structured information. Pagination is handled by the schema, so the remaining gaps are small — mainly no guidance on how the result feeds into other tools.

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 limit, offset and include_parents each fully documented including ranges and defaults, so the baseline is 3. The description adds nothing about parameters — notably it never mentions include_parents, even though the returned 'ParentDepartmentId' field relates directly to it.

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 all departments') and immediately disambiguates the term with synonyms ('shops, restaurants, units'), which matters given the sibling tools cover employees, shifts and absences. It also enumerates the key returned fields so an agent knows what an entry looks like before calling.

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 note that DepartmentId is 'used by other tools' hints this is a prerequisite lookup for department-scoped calls, but the description never says when to choose this tool over a sibling or what to do next. No exclusions or alternatives 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?

Beyond the readOnly/openWorld/non-destructive annotations, it discloses meaningful behavior: 500 records maximum per page, alphabetical ordering, slice-based continuation, and an explicit privacy boundary that bank details and ID numbers are never returned. It does not address rate limits or whether deleted employees affect ordering, but the added context is substantial.

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?

The content inventory is front-loaded and each sentence carries information: contents, exclusions, paging mechanics, endpoint. The closing 'GET /employees/getemployeedetails/.' is of marginal value to an agent but harmless and short.

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 shape, and it does so well by enumerating the record's fields plus the privacy exclusions and page ordering. Only the interaction between alphabetical ordering and pagination (records shifting between pages) and the include_deleted flag remain unaddressed.

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 already documents page, limit, offset and include_deleted thoroughly. The description reinforces the page-size ceiling and the next_page/next_offset continuation pattern, but adds no semantics the schema lacks, and never mentions include_deleted. 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?

It names the resource precisely (detailed employee records) and enumerates the returned content areas (contact data, roles per department, contract hours, wage history, absence balances, competencies, notes, availability). The adjective 'detailed' implicitly separates it from the sibling tamigo_list_employees, but it never names that sibling, so the differentiation depends on inference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear operational guidance for continuation ('pass the reply's next_page and next_offset to continue') but no guidance on when to choose this over tamigo_list_employees or tamigo_list_absences. The usage context is implied by 'detailed' 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, openWorldHint=true, and destructiveHint=false, so the description only needs to add context—and it does: it lists the exact fields returned, including PosKey's cross-reference to the attendance tool, which is real behavioral information. It does not address pagination behavior or result volume, though 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?

Two sentences, zero waste, with the returned-field inventory front-loaded and the sibling redirect trailing it. Every clause 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?

With no output schema, the description compensates well by enumerating returned fields and clarifying the meaning of PosKey. Combined with annotations covering the safety profile and a fully documented schema, 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 description coverage is 100%: both limit and offset are fully documented in the schema, including the next_offset continuation pattern, so the description does not need to repeat them. The description adds no parameter semantics of its own—baseline 3 applies when 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 and resource (list employees of the company) and specifies the scope of the basic data set it returns. It also clearly distinguishes itself from tamigo_list_employee_details, so an agent can separate the two without opening either 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?

The sentence 'For contract, wage and absence-balance details use tamigo_list_employee_details' explicitly names the alternative and the condition that selects it. It covers the main routing decision but gives no guidance on when this basic list is preferable for bulk or narrow use cases beyond 'basic'.

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, non-destructive, open-world behaviour, and the description adds beyond that: the three shift measures (original/planned/worked), the unit (hours), the associated metadata fields and the endpoint shape. Pagination and response envelope details are left to the schema rather than restated, which is appropriate.

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 plus the endpoint line, with the payload description front-loaded and the use cases immediately after. The trailing GET path is mildly redundant but the whole text earns its space.

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 return shape and does so by naming the three shift measures and the accompanying employee/department attributes. Pagination and limits are handled in the input schema, so the remaining gap is only in fine-grained field structure.

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 two date parameters, limit/offset and department_id are already fully documented. The description only implies the date-range and department dimensions, adding no format or filtering nuance 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 and resource: returns original, planned and worked shift hours per employee and day for a date range, plus the key fields returned. The scope is clear enough for an agent to identify it without the sibling context, though it does not explicitly contrast itself with adjacent tools like tamigo_list_absences or tamigo_list_employee_details.

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?

"Use it for payroll checks, hours worked vs planned and who worked when" gives concrete usage contexts that map to real intent. It stops short of naming when NOT to use it or pointing at an alternative, so it 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 already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is carried by structured data. The description still adds real value by disclosing company rounding rules and that the reply echoes the times actually registered, but it could say more about what happens to conflicting or duplicate entries beyond "not undone by repeating 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?

The verb and write nature are front-loaded, and almost every clause carries information an agent needs. It is a single dense paragraph though, and the key-sourcing plus break-pairing rules would scan faster as separate sentences or bullets.

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, non-idempotent mutation with no output schema, the definition covers prerequisites, ordering, break pairing, rounding behavior, the shape of the reply, and the wage impact plus a confirm-first warning. 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 the baseline is 3, and the description goes beyond it: it explains that department_key/employee_key are POS keys with a specific configuration origin, that each entry needs EITHER check_in_time OR check_out_time, and that a shared activity_name on a pair brackets a break. That is genuine semantics the schema does not express.

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 an explicit "WRITE:" marker and states the precise resource (check-in/check-out times in the Tamigo timesheet) and scope (one or many employees). It also notes it is the same call a POS system makes, which immediately separates it from every read-only sibling such as tamigo_list_shifts or tamigo_list_absences.

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 concrete preconditions (POS keys configured under Configuration -> Departments / POS Keys) and names the two sibling tools that supply those keys, tamigo_list_departments and tamigo_list_employees. It also states ordering requirements, how to register a break, and advises confirming entries first.

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 flag destructive=true, idempotent=false, openWorld=true; the description adds real value beyond that by disclosing that a date already carrying revenue for a department may be overwritten, and by naming the underlying endpoint POST /Revenues/. It stops short of describing partial-failure/batch atomicity or the response, so not 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?

Four sentences, front-loaded with the WRITE verb and resource, then the row shape, then the risk caveat, then the endpoint. No filler and nothing repeated from the schema verbatim.

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?

A single-parameter tool with full schema coverage and no output schema needs little more than this; the description covers write semantics, the overwrite hazard, and formatting. It leaves open what happens with a 200-row batch if one row is rejected, which is the one gap an agent might care about.

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 adds semantics the schema can't express: the composite identity of (department_key, date) that drives overwrite behavior, and that department_key is the POS key configured in Tamigo. The decimal-separator remark is mildly redundant with type=number.

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 an explicit WRITE marker, names the resource (daily revenue per department), and grounds it with a concrete analogue ('the same call a cash-register system makes') plus the downstream purpose (revenue-based planning and KPIs). This clearly separates it from the sibling read tools (list_*, get_*).

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 clear operating context (register-system import, planning/KPI use) and an explicit caution to 'confirm the rows first' before uploading. It does not name a sibling alternative or state when a different tool would be preferred, keeping it 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.