Read accounts, staff, shifts, worklogs and absence dates in Smartplan.
Scored across 14 tools
Each tool clearly targets a distinct resource (absence, account, jobtype, location, member, shift, worklog) with a get-one versus list-page distinction. The only slight overlap is between smartplan_get_account and smartplan_list_accounts, but the descriptions distinguish account settings from the authenticated account list.
All tools follow a consistent smartplan_verb_noun pattern using snake_case. The get/list split is predictable across every resource, making the naming highly uniform.
Fourteen tools are reasonable for a read-only API covering seven resource types with both get and list operations. The count is slightly repetitive because every resource has both a single-item and page-listing tool, but it remains well-scoped.
The read-only surface covers get/list for the main entities, but there are notable exclusions such as absence types, reasons, notes, member contact details, and custom data. There is also no explicit operation for retrieving separate absence metadata or switching accounts beyond the selected one.
One absence by ID in the selected account. Excludes absence types, reasons and notes. Read-only Smartplan Pro API.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered; the description adds real value by disclosing that absence types, reasons and notes are omitted from the response. It does not cover not-found behavior or auth/permission requirements. 'Read-only Smartplan Pro API' largely restates 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, front-loaded clauses; the key scope statement comes first and the field-exclusion caveat follows. The final 'Read-only Smartplan Pro API' sentence is largely redundant with annotations.
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 what comes back; it says what is excluded but not what fields are included, and does not address error behavior. Adequate to call correctly, but thin for an agent that must reason about the returned payload.
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?
Only one parameter (id) and the schema carries 0% description coverage, so the description is the only source of meaning — it says only 'by ID', leaving the format, allowed characters and the 80-character limit unexplained (the schema has the pattern but no prose). This is the minimum viable level.
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 a single absence by ID, scoped to the selected account. The singular framing distinguishes it from smartplan_list_absences, though the sibling is never named 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 — an agent can infer this is for single-record lookups, but there is no explicit 'use when you have an ID / do not use for browsing' guidance and no mention of the list alternative. The 'excludes absence types, reasons and notes' note hints that other tools may be needed for related data, but it is not framed as routing advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Account settings and timezone for this connection's selected account. Read-only Smartplan Pro API.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the description's 'Read-only Smartplan Pro API' mostly restates structured data. It does add one piece of useful context, telling the agent which content comes back (settings and timezone), which the annotations don't convey.
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, front-loaded sentences with no filler. The second sentence is largely redundant with the readOnlyHint annotation but is harmless and reorients the agent to the API context.
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 is the only source for return values, and 'account settings and timezone' only sketches the payload rather than enumerating fields. For a zero-parameter read this is adequate to invoke correctly, but not complete for interpreting the response.
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?
Tool takes zero parameters, so the schema baseline of 4 applies. Nothing about argument semantics needs explanation, and the description correctly avoids inventing inputs.
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 and scope: account settings and timezone for the connection's selected account. It's clearly a single-object read and implicitly distinct from smartplan_list_accounts, but the sibling differentiation is left to inference 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?
No guidance on when to use this versus smartplan_list_accounts, which is the obvious alternative in the sibling set. The phrase 'this connection's selected account' hints at scope but never tells the agent how to choose between the two account tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One jobtype by ID in the selected account. Read-only Smartplan Pro API.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, and the description's 'Read-only' merely restates that. The one potentially novel claim, 'in the selected account', is unexplained — how the account is selected and whether it affects lookup is never stated.
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 the resource and mode front-loaded; nothing is padded. It is terse to the point of being skeletal, but no sentence 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?
For a single-parameter read tool with full safety annotations and no output schema, the description is minimally adequate. It still leaves open what a 'jobtype' represents and what the account scoping means, which an agent calling this cold would have to infer.
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 0%, so the description carries the burden, yet it only says 'by ID', which essentially repeats the parameter name. The schema's pattern constraint is undocumented in prose, and there is no hint about where a valid jobtype ID comes from (e.g. output of list_jobtypes).
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 phrase 'One jobtype by ID' identifies both the resource (jobtype) and the retrieval mode (single record by identifier), which is enough to distinguish it from bulk operations. However, it never names smartplan_list_jobtypes as the alternative, so the differentiation from its closest sibling is left implicit.
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 statement of when to use this versus smartplan_list_jobtypes, nor any prerequisite or error condition (e.g. what happens with an unknown ID). The only guidance is the implied 'use when you have an ID'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One location by ID in the selected account. Read-only Smartplan Pro API.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so "Read-only" largely repeats structured data. The one piece of added context is "in the selected account" (account scoping), but nothing is said about not-found behavior or error responses.
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, with no filler. The second sentence is partially redundant with annotations but cheap enough to justify itself.
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 single-parameter read tool with rich annotations and no output schema, this is minimally sufficient. Gaps remain around account selection semantics and what happens when the ID is invalid or absent.
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 0%, so the description must carry the parameter burden. "by ID" only confirms that the lone parameter is an identifier; the '^[A-Za-z0-9][A-Za-z0-9_-]{0,79}$' pattern constraint and the format of valid IDs go entirely unaddressed.
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?
"One location by ID" states the resource (location), the retrieval key (id), and implicitly the singular-fetch behavior, which distinguishes it from the sibling smartplan_list_locations. It is clear but lacks an explicit verb and does not name the list sibling.
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: fetching a single location when an ID is known, versus listing. There is no explicit when-to-use/when-not statement and no alternative tool is named, even though smartplan_list_locations is an obvious fork point.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One member by ID in the selected account. Excludes contact details, photos and custom data. Read-only Smartplan Pro API.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing that contact details, photos and custom data are excluded from the response, which shapes how the agent should interpret the result. Missing only error/not-found 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?
Three short sentences, front-loaded with the retrieval action and scoped by account. Little waste, though the trailing 'Read-only Smartplan Pro API' mostly repeats the readOnlyHint annotation.
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, so the description bears the burden of describing return values; it only says what is excluded, never what fields are included. Adequate for selection, but incomplete for an agent that needs to know the response shape.
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 0% for the single `id` parameter, so the description is the only explanation: 'One member by ID in the selected account' conveys that the id identifies a member within the current account. That is minimal but sufficient for an obvious identifier; no format guidance beyond the schema pattern.
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 scope: 'One member by ID in the selected account.' The singular 'one ... by ID' implicitly distinguishes it from smartplan_list_members, though the sibling is never named.
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 'by ID' — an agent can infer this is the single-record retrieval path versus list_members, but there is no explicit when-to-use, no prerequisite, and no named alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One shift by ID in the selected account. Date filters use the displayed start date, including shifts crossing midnight. Shift IDs change on archive/bulk edit; worklogs are historical records. Read-only Smartplan Pro API.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered; the description still adds genuinely new behavioral context by warning that shift IDs change on archive/bulk edit and that worklogs are historical records. That ID-instability warning is the key operational caveat an agent needs and is not derivable from 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?
The purpose is correctly front-loaded, but two of the four sentences are tangential to a get-by-ID call: date-filter behavior is irrelevant since this tool accepts no date parameters, and the worklog remark reads as family-wide boilerplate. Those sentences do not earn their place here.
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-only lookup with full annotation coverage and no output schema, the description supplies the essential risk information (unstable IDs) and account scoping. The only real omission is a pointer to smartplan_list_shifts for discovery when the ID is not known.
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 0% for the single `id` parameter, so the description must compensate, and it does add real meaning: IDs are opaque strings that mutate on archive or bulk edit. It does not restate the pattern constraint, but the schema already enforces that.
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?
"One shift by ID in the selected account" states a specific verb (retrieve), resource (shift), and cardinality (single), which implicitly contrasts with smartplan_list_shifts. It stops short of naming the list sibling explicitly, so an agent must infer the pairing.
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 "One shift by ID" implies the single-record use case and "selected account" scopes the context, but there is no explicit statement of when to prefer smartplan_list_shifts or what happens when the ID is unknown. 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.
One worklog by ID in the selected account. Date filters use the displayed start date, including shifts crossing midnight. Shift IDs change on archive/bulk edit; worklogs are historical records. Read-only Smartplan Pro API.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description provides crucial behavioral context far beyond the read-only hint. It details data mutation behavior (Shift IDs change on archive/bulk edit), data persistence (worklogs are historical records), and specific operational logic (date filters include shifts crossing midnight).
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 description is highly condensed. While four separate points are crammed into the text, every phrase—from scope to data lifecycle—is necessary, making it efficient despite its density.
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-record historical API, this description is comprehensive. It covers the safety profile (read-only), data integrity risks (ID changes), and functional constraints (date filtering/midnight handling), leaving no critical piece of context 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?
With 0% schema coverage, the description is essential. However, since there is only one parameter (id), the description does not add meaningful semantic depth beyond the schema's definition of the ID itself. The baseline score of 3 is appropriate 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?
The description explicitly states the tool retrieves a 'One worklog by ID', which is highly specific. It clearly distinguishes this function from list operations by naming the resource (worklog) and the method (by ID).
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 implies usage—you use this tool when you possess a specific worklog ID—but offers no explicit guidance on when to use it versus the sibling list functions. The usage is self-evident from the ID requirement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One page of absence dates for the selected account; continue with next_offset. Excludes absence types, reasons and notes. Read-only Smartplan Pro API.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No | ||
| status | No | ||
| absentee | No | ||
| end_date | Yes | ||
| start_date | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, open-world, and non-destructive behavior. The description adds useful context beyond annotations: results are paginated one page at a time, continuation uses next_offset, and absence types/reasons/notes are excluded from the response.
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 description is compact and front-loads the core purpose and pagination behavior. The final 'Read-only Smartplan Pro API' phrase repeats annotation information and is slightly redundant, but overall there is little waste.
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 six parameters, 0% schema description coverage, and no output schema, the description is too thin. It covers pagination and excluded fields, but an agent still lacks enough information to interpret the date parameters, status values, absentee filter, and expected page 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 0%, so the description must carry parameter meaning, but it only explains pagination continuation via next_offset. It leaves start_date/end_date formats, the status enum values (W, A, D, C, DEL, A-AUTO), the absentee filter, and limit/offset semantics undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: listing one page of absence dates for the selected account. It clarifies scope by excluding absence types, reasons, and notes, which helps distinguish it from a detail tool like smartplan_get_absence, though it does not name that 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?
It implies usage through pagination guidance ('continue with next_offset') and exclusion of detail fields, suggesting this is for lightweight absence-date listing rather than full absence retrieval. However, it does not explicitly say when to use this versus smartplan_get_absence or how the required start_date/end_date should be chosen.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Shows only the account selected during login, from the authenticated account list. Read-only Smartplan Pro API.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered. The description adds one genuinely useful behavioral trait: it returns at most the single login-selected account rather than a full list. "Read-only Smartplan Pro API" merely restates the annotations, and nothing is said about auth mechanics or what happens for a multi-account login beyond the stated filter.
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 result-shape constraint before the API-level note. Nothing is padded, though the trailing "Read-only Smartplan Pro API" sentence duplicates annotation content and is the weakest sentence present.
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, read-only tool with a fully covered schema and no output schema, the description conveys the essential fact an agent needs: the call yields only the login-selected account. Return type (single object vs one-element array) is not pinned down, which is the only notable omission.
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 no parameter meaning to convey, and the schema is empty. Baseline 4 applies; no parameter-related disclosure is needed or missing.
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 and resource ("Shows ... the account") and adds an important scope qualifier: only the account selected during login, not every account. That resolves the ambiguity created by the "list" prefix. It does not name or distinguish itself from the very similar sibling smartplan_get_account, which is the main remaining gap.
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: the description tells the agent this returns the login-selected account, which implicitly frames when to reach for it. There is no explicit when-to-use/when-not-to-use guidance and no mention of the alternative smartplan_get_account, leaving the agent to infer the split between the two.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One page of job roles for the selected account; continue with next_offset. Read-only Smartplan Pro API.
| Name | Required | Description | Default |
|---|---|---|---|
| alive | No | ||
| limit | No | ||
| offset | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so 'Read-only' adds nothing new. The one genuinely additive fact is that results are paged one page at a time, but there is no detail on ordering, page size defaults, or filtering semantics.
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 compact sentence with the resource and the continuation instruction front-loaded. 'Read-only Smartplan Pro API' is redundant given the annotations, so it is not perfectly waste-free.
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 three-parameter list tool with no output schema, the description leaves the only non-obvious filter ('alive') undefined and points to a parameter name that does not exist. An agent can call it, but cannot call it with confidence about filtering or paging semantics.
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 0% for three parameters, so the description must compensate and it largely does not. The 'alive' boolean is never explained, and the cursor is called 'next_offset' while the actual parameter is 'offset', which risks a wrong invocation.
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 ('One page of job roles') and scopes it to the selected account, which separates it from smartplan_list_accounts and other list siblings. It does not explicitly contrast with smartplan_get_jobtype, though 'one page' implies the paged-list 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?
Gives a pagination hint ('continue with next_offset'), which tells the agent how to iterate, but says nothing about when to prefer this over smartplan_get_jobtype or how the 'alive' filter changes results. Usage is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One page of locations for the selected account; continue with next_offset. Read-only Smartplan Pro API.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No | ||
| is_hidden | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so 'Read-only Smartplan Pro API' adds nothing. What does earn credit is the pagination contract — one page at a time, continue with next_offset — a behavioral trait found nowhere in the annotations or schema that directly shapes the calling loop.
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 statement, front-loaded with the resource and the continuation instruction. Nearly zero waste; the redundant 'Read-only Smartplan Pro API' clause is the only 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?
It is a trivial read-only list tool with no output schema, so the return-shape burden is low, but the description never explains is_hidden, never resolves the next_offset/offset naming mismatch, and leaves the 'selected account' context unexplained — enough gaps to keep it at minimum viable.
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 0%, so the description must carry parameter meaning and doesn't. It references 'next_offset', a name that does not exist in the schema (the field is 'offset'), and says nothing about limit's 1-50 cap or what is_hidden filters — both of which are unintuitive and undocumented.
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 ('One page of locations') and scopes it to 'the selected account', which separates it from the singular smartplan_get_location. The only gap is that 'selected account' refers to an ambient context never exposed as a parameter, so the scope is slightly hand-wavy.
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?
'continue with next_offset' implies the pagination loop, which is real usage guidance. However, it never says when to prefer this over smartplan_get_location for a known location, nor how to obtain the account context, so the guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One page of members for the selected account; continue with next_offset. Excludes contact details, photos and custom data. Read-only Smartplan Pro API.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No | ||
| is_admin | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the bar is lower. The description still adds real value by disclosing the pagination continuation token and, importantly, that contact details, photos and custom data are excluded from results — telling an agent this tool cannot supply emails or profile images.
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, front-loaded sentences: what you get, how to continue, what is excluded. No filler, and the most actionable detail (pagination) appears before the caveats.
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, and the description partially compensates by describing excluded fields, so an agent knows roughly what a member record contains. It remains incomplete on the is_admin filter and on what 'the selected account' means operationally given siblings like smartplan_list_accounts and smartplan_get_account.
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 0% across three parameters. The description implies a page-size/offset model via 'one page' and 'next_offset', but it never explains the limit maximum of 50 or the offset parameter by name. The is_admin filter — a meaningful selection control — is not mentioned at all, leaving a third of the inputs undocumented in both schema and description.
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 members) plus scope ('one page ... for the selected account'), which clearly separates it from the singular smartplan_get_member sibling. It stops short of naming that sibling or saying what makes a member match, but the list-vs-get distinction is 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?
Pagination usage is explicit ('continue with next_offset'), which tells the agent how to iterate. However there is no guidance on when to use this versus smartplan_get_member for a single record, and no mention of how the is_admin filter affects which members come back.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One page of upcoming shifts for the selected account; continue with next_offset. Date filters use the displayed start date, including shifts crossing midnight. Shift IDs change on archive/bulk edit; worklogs are historical records. Read-only Smartplan Pro API.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| owner | No | ||
| offset | No | ||
| end_date | Yes | ||
| jobtypes | No | ||
| location | No | ||
| start_date | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered; the description adds genuine extra context: date filters key off the displayed start date (including overnight shifts), and shift IDs are unstable after archive/bulk edit, which is a real gotcha. Minor inconsistency: it says "next_offset" while the schema parameter is "offset", which could confuse pagination.
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 short sentences, front-loaded with the core purpose and pagination, then the two non-obvious caveats. Dense and waste-free, though the mixing of pagination, date semantics, and ID instability in one block reads as a list of caveats rather than a structured flow.
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 and 0% schema coverage across 7 params, the description covers the trickiest parts (date filtering, pagination, ID instability, historical worklogs) but leaves filter parameters unexplained — an agent cannot tell whether owner/jobtypes/location expect IDs or names. Adequate but with clear gaps for a filter-heavy 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 coverage is 0%, so the description must carry the burden, and it explains the date filter semantics (start_date/end_date apply to displayed start date) and pagination via offset/next_offset. It says nothing about owner, jobtypes, location, or limit (max 50), leaving four of seven parameters with no semantic guidance.
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?
"One page of upcoming shifts for the selected account" states a clear verb (list) and resource (shifts) with page scope, which implicitly separates it from smartplan_get_shift (single shift) and the list_* siblings. It never names a sibling explicitly, so the differentiation is inferred 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?
"continue with next_offset" gives concrete pagination guidance, which is real usage direction. However there is no explicit when-to-use/when-not-to-use guidance versus smartplan_get_shift or the other list_* tools; the mention that "worklogs are historical records" only hints at an alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One page of recorded worklogs for the selected account; continue with next_offset. Date filters use the displayed start date, including shifts crossing midnight. Shift IDs change on archive/bulk edit; worklogs are historical records. Read-only Smartplan Pro API.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| owner | No | ||
| offset | No | ||
| end_date | Yes | ||
| jobtypes | No | ||
| location | No | ||
| start_date | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description earns credit for the extra semantics: date filters use the displayed start date even for shifts crossing midnight, and shift IDs change on archive/bulk edit so worklog references may be stale. That stale-ID warning is behavior an agent could not get from the schema and would otherwise get wrong.
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 short clauses, each delivering distinct information, with the scope statement front-loaded. Slightly compressed to the point of ambiguity around 'next_offset' rather than being verbose.
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 and zero parameter documentation, the description should say more about what a page contains and what the filters (owner, jobtypes, location) select. The date and stale-ID notes are valuable, but half the callable surface remains unexplained.
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 0% across 7 parameters, so the description carries the full burden. It clarifies the semantics of start_date/end_date (displayed start date, midnight-crossing shifts) and pagination, but says nothing about owner, jobtypes, location, or the limit cap of 50, and the 'next_offset' naming does not match any declared parameter.
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 recorded worklogs') plus explicit scope ('one page ... for the selected account'), which separates it from the singular smartplan_get_worklog. It stops short of naming sibling tools or explicitly excluding filtered variants.
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?
'continue with next_offset' gives pagination guidance, which is genuine usage direction, but the schema exposes an 'offset' parameter and no 'next_offset', leaving the agent to infer the mapping. There is no guidance on when to use this versus smartplan_get_worklog or the shift-listing tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
smartplan_get_absencesmartplan_get_accountsmartplan_get_jobtypesmartplan_get_locationsmartplan_get_membersmartplan_get_shiftsmartplan_get_worklogsmartplan_list_absencessmartplan_list_accountssmartplan_list_jobtypessmartplan_list_locationssmartplan_list_memberssmartplan_list_shiftssmartplan_list_worklogsRead groups, roles, employees, agreement metadata, role assignments and planned shifts.
Read Tamigo departments, employees, shifts, absences and opening hours; register attendance.
Read SmartAccounts clients, vendors, invoices, payments, ledger, accounts; create and book records.
Read RotaCloud shifts, attendance, leave, availability and payroll; create shifts and handle leave.
Add one secure layer between your agents and this server.