Famly MCP by usefulapi

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 adds a genuine caveat that results depend on token permissions, but says nothing about behavior for unknown/unauthorized IDs, the 100-ID batch cap, or error handling.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with what is returned and then the constraint. The clause 'Uses the Famly Public API' is mild boilerplate that adds little for an agent already in this server's toolset.

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 the returned fields, and it flags the permission dependency. For a single-parameter read-only lookup this is close to complete; only edge-case behavior (unknown IDs, batching) 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 0%, so the description must carry the parameter semantics; it only conveys that the input is known invoice IDs. The UUID pattern and maxItems=100 live in the schema, but nothing in the description explains batching, ordering, or partial-result behavior for mixed valid/invalid IDs.

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 (invoices) and scope (lookup by known invoice IDs) plus the fields returned (numbers, totals, dates, bill payer IDs). The phrase 'known invoice IDs' implicitly distinguishes it from famly_list_invoices, but 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?

'For known invoice IDs' implies you must already have IDs in hand, which hints that discovery belongs to famly_list_invoices, but the alternative is never named and there is no statement about what to do when IDs are unknown or invalid.

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 readOnly/idempotent/non-destructive, and the description adds genuinely new behavioral facts: the 365-day window cap, single-page-per-call pagination, and that visibility varies with token permissions. It also scopes out leave categories, health information and notes. Return format itself is not described, but the safety profile is already covered by 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?

Four dense, front-loaded sentences with no filler; the returned metrics come first and constraints after. The opening is a noun fragment with no verb, which costs a little clarity but not length.

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 six parameters at low coverage, the description does well on scope, exclusions and date limits, but leaves the employee/group filters and pageSize unexplained and never clarifies what the 'differences' figure means. Adequate but with real gaps for a nested-object, cursor-paginated 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 only 17%, so the description carries most of the burden. It only annotates dateRange (365-day cap) and hints at pagination via 'one page per call'; the groupIds, employeeIds, pageSize and next parameters get no semantic explanation at all, so the filter parameters remain opaque.

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?

Names the specific resource and enumerates the exact metrics returned (contracted, attended, scheduled, break minutes plus differences), which distinguishes it from every sibling list_* tool. The verb is only implied by the name rather than stated in the description, keeping it short of a 5.

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 real operating constraints (365-day max range, one page per call, token-permission dependence) but never says when to choose this tool over the sibling tools or what it is not for. Usage is implied by the resource description rather than routed explicitly.

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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds one genuine behavioral fact the annotations do not: results are permission-gated by the token, which tells the agent to expect partial or empty results rather than an error. It does not disclose what includeDeleted does or how permission failures manifest.

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 returned resource and followed by the API/permission caveat. No filler, though the second sentence is slightly boilerplate.

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 two-parameter read tool with no output schema, the description usefully enumerates the returned fields (IDs, titles, references) and the API source. However, it omits the includeDeleted flag and any pagination or result-size behavior, leaving the agent without the full picture for 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?

Schema description coverage is 0%, so the description must carry parameter meaning, and it largely does not. 'For the requested sites' loosely hints at siteIds, but nothing explains that it is a UUID array capped at 100 items, and includeDeleted is never mentioned at all.

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?

Names the resource (account codes) and the fields returned (IDs, titles, references) plus the scoping to requested sites, so the agent knows exactly what entity this retrieves. It lacks a verb and any explicit differentiation from siblings like famly_list_sites or famly_get_invoices, but the resource is unambiguous.

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

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

There is no statement of when to use this tool versus the sibling list/get tools, no prerequisites, and no exclusions. The only contextual sentence is a caveat about token permissions, which is not usage guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered; the description earns credit for adding context annotations cannot express: field-level exclusions (bank accounts, SSNs, contact details), one-page-per-call pagination, and permission-dependent results. A minor gap is that it does not say what happens when nextToken is exhausted.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three compact fragments with zero waste, and the most decision-relevant information (what is returned, what is excluded) is front-loaded. The sentence-fragment style is terse but readable.

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 covers the shape of returned data and the exclusion list, which is the right emphasis. However, for a three-parameter tool it omits any parameter semantics and any usage guidance, leaving real gaps an agent must resolve by inspection.

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 only 33% – nextToken is documented in the schema, but siteIds (required, 1-100 UUIDs) and includeDeleted have no description anywhere. The description mentions no parameters at all, so it does not compensate for the coverage gap; notably, an agent would not learn from this text that deleted payers can be included.

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 enumerates the returned data (billing identities, names, balances, billing references) which effectively identifies the resource, but it never states a verb such as 'lists bill payers' – the agent must infer the action from the name. It is distinguishable from siblings like famly_list_payments and famly_list_invoices only by implication from the field list.

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

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

There is no when-to-use guidance, no statement of when to prefer famly_list_payments or famly_get_invoices instead, and no prerequisites beyond a passing mention that results depend on token permissions. The agent is left to infer all routing decisions.

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 read-only/idempotent/open-world safety, and the description adds real behavioral context beyond them: the default behavior of returning the full date range when nextToken is omitted, the need to pass the returned cursor, exclusion of manager notes and child check-ins, and token-permission dependence. That is substantive disclosure the annotations do not provide.

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 compact sentences, front-loaded with what is returned, then exclusions, then the pagination caveat, then permissions. Every sentence carries distinct content with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema, but the description sketches return content (timestamps, work-tag IDs) and handles pagination and scope well. The remaining gap is that the required SiteSetId and the range from/to format are unexplained, which an agent would need to form correct calls.

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 only 33% (only nextToken is documented), so the description should compensate. It adds meaning to range (narrow it) and nextToken (passthrough), but SiteSetId is never explained and the range from/to format is left implicit. Partial compensation justifies a 3 rather than higher.

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 (employee check-ins), specifies the returned fields (check-in/out timestamps, work-tag IDs), and explicitly excludes manager notes and child check-ins. This scope plus the exclusions make it clearly distinguishable from famly_list_employees and famly_get_staff_hours_totals.

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 context: what is excluded, a pagination warning (narrow the range; pass returned nextToken), and permission dependence. It does not explicitly route to an alternative sibling or state when-not to use it, so it falls short of full when/alternative guidance.

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

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

Annotations already cover safety (readOnlyHint, idempotentHint, destructiveHint=false), yet the description still adds real value: it discloses that results are permission-scoped by the Famly Public API token, that certain personal fields are withheld, and the non-obvious rule that pagination must continue past an empty page. The main omission is record cardinality/ordering behavior, which keeps it from 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 short sentences, front-loaded with what the tool returns, followed by exclusions, the pagination rule, and the auth caveat. No filler or repetition; every sentence carries distinct 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?

With six parameters, 17% schema coverage, and no output schema, the description covers scope and pagination adequately but leaves half the parameters opaque and says nothing about return shape or page-size limits. It is a viable minimum, not a complete briefing for an agent building a filtered staff query.

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 only 17% — just `next` is documented in the schema — so the description must compensate, and it largely does not. includePast, includeFuture, pageSize, employeeIds and siteIds are never explained; a reader cannot tell whether includePast means former staff or historical date ranges. Only pagination via `next` is reinforced.

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 the resource and its scope: a staff directory with employment dates, plus an explicit field-level exclusion list (no home address, birth date, gender, telephone, photographs). That exclusion list usefully separates this from a full employee-profile fetch and from famly_list_employee_checkins. It never uses a verb ('list') and relies on the tool name for the action, which is the only reason it isn't a 5.

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 only actionable guidance is pagination: 'Continue using next, including after an empty page.' Nothing says when to choose this over famly_list_employee_checkins or famly_get_staff_hours_totals, and the semantics of includePast/includeFuture — the key selection decision here — go unmentioned. Sibling routing is left to inference from names alone.

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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered. The description adds one genuinely useful behavioral note — results are permission-dependent on the token — but says nothing about pagination, result size, or ordering for a list operation.

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 no filler, and the returned-field summary is front-loaded. The tradeoff is that the brevity comes from under-specification rather than disciplined editing, and the leading sentence lacks a verb.

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 one parameter, no output schema and full annotation coverage, the bar is modest, and the description does state the returned fields and the permission caveat. It nevertheless leaves the agent without the source of siteSetIds and without any note on result volume, which are the main remaining gaps.

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 required parameter siteSetIds, so the description carries the full burden. 'For the requested site sets' only echoes the parameter name; it does not explain what a site set is, how to obtain the IDs (likely via famly_list_sites), or the practical impact of the 1-100 item limit.

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 opens with a noun phrase listing returned fields ('Room/group IDs, titles, institution IDs and staffing ratios') rather than a verb+resource statement; only the title 'List groups' supplies the action. The resource (rooms/groups) and scope (site sets) are identifiable, and it is distinguishable from siblings like famly_list_sites or famly_list_employees, but the agent must infer the operation from the title.

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 when-to-use guidance and no comparison against sibling tools such as famly_list_sites (which presumably yields the site set IDs this tool consumes). The only contextual note is a caveat about token permissions, which is behavioral rather than a usage rule.

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 readOnly, idempotent, non-destructive and open-world, so the description's job is to add context — and it does: it discloses the field projection limits, that results are paged one page per call, and that output is scoped by token permissions. It stops short of stating page size, rate limits, or ordering, which would complete the picture.

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 zero filler, and the return-field inventory is front-loaded. The lead is a noun phrase of returned fields rather than a verb+resource statement, which is slightly less scannable than it could be, but 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 usefully documents the returned shape and exclusions, and it covers the paging and permission caveats. However, for a 4-parameter filtered list tool it says nothing about the date-range and site filters, and it omits the list-vs-get distinction against famly_get_invoices, leaving real gaps.

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 only 25% — only nextToken is documented, while siteIds and the two date-range objects (createdDateRange, invoiceDateRange with nested from/to) carry no format or semantics in either schema or description. The description never mentions filtering by site or date range, so it fails to compensate for the coverage gap on 3 of 4 parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description enumerates exactly what the call returns (invoice IDs, numbers, totals, dates) and what is excluded (line descriptions, child records, PDF links), which makes the resource and projection unambiguous. It does not differentiate itself from the sibling famly_get_invoices, so the agent cannot tell from the description alone which of the two to pick.

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 page per call' implies a pagination loop and 'results depend on token permissions' flags an auth caveat, but there is no explicit when-to-use guidance and no statement of when to prefer famly_get_invoices over this list tool. The agent is left to infer selection and pagination behavior.

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 readOnly, idempotent, openWorld and non-destructive, so the safety bar is low. The description earnestly adds beyond that: the returned/omitted field set, one-page-per-call pagination, and that results are gated by token permissions. It omits ordering behavior and what happens when siteIds spans many sites.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three compact sentences with no filler, and the field-scope statement leads. Field enumeration is slightly listy but each clause carries information the schema does not.

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 6 parameters, nested date-range objects, no output schema and near-zero schema coverage, the description leaves key decisions unexplained: the required siteIds semantics, includeDeleted's effect on results, and how the two date ranges differ. It adequately covers return shape but not invocation for a fairly complex signature.

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 only 17% and the description does not compensate: siteIds (the sole required param), pageSize, includeDeleted, createdDateRange and paymentDateRange are all undocumented in prose. 'Payment amounts, dates' and 'one page per call' only loosely gesture at the date-range and paging params.

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 enumerates the resource's fields (amounts, dates, method, currency, status) and explicitly scopes out notes, bank details, child records and metadata, so an agent can tell it targets payment records rather than invoices or purchases. It never states the action (list/retrieve) explicitly, relying on the title, but the field-level scope makes it distinguishable from 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?

No indication of when to choose this over famly_list_invoices, famly_list_purchases or the other list tools. 'One page per call' hints that callers must page, and the token-permission caveat sets expectations, but neither is a usage decision rule.

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 readOnly/idempotent/non-destructive, and the description goes beyond them usefully: pagination semantics ('One page per call'), a per-site constraint when a date range is supplied, and that results are permission-dependent ('results depend on token permissions'). It still omits what happens with multiple site IDs absent a date range and any rate-limit 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?

Four short sentences with no filler, and return fields plus the site constraint are front-loaded. The lead sentence is a bare noun list missing a verb, which makes it slightly telegraphic rather than crisp.

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 4-parameter list tool with no output schema, the description helpfully enumerates the returned fields, covers pagination, and flags permission dependence. Remaining gaps (no filtering-by-status mention, no date-range format, no sibling differentiation) are modest rather than disqualifying.

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 only 25% (nextToken only), so the description partially compensates: it implies the date range interacts with siteIds such that a range must target one site at a time, and that results are paged. It says nothing about pageSize bounds, the from/to format for purchaseDateRange, or the difference between passing one vs many site IDs.

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 reads as a return-payload summary ('purchase IDs, status, totals and invoice IDs') rather than a verb+resource statement of what the tool does; the action must be inferred from the name. It does scope the content ('excluding child records and booking details'), but never states how this differs from adjacent siblings such as famly_list_invoices or famly_list_payments.

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?

'With a date range request one site at a time' is the only conditional guidance, and 'One page per call' implies iteration. There is no explicit when-to-use, no mention of when to prefer famly_list_invoices or famly_list_payments instead, and no stated preconditions beyond a token.

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 cover read-only, idempotency and open-world access, so the description's marginal value is the two facts it adds: results are permission-scoped to the token and the endpoint is not paginated. Those are genuinely useful, but nothing is said about ordering, the shape of each returned item, or what an empty result means.

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 what is returned, followed by the pagination and permission caveats. Nothing is padded, though the sentences are terse enough that the missing parameter semantics feel like omission rather than brevity.

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 tool with two undocumented parameters and no output schema, the description should explain filtering semantics and the returned fields. It handles the permission scoping and pagination caveats but leaves the entire input contract 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 description coverage is 0%, so the description carries the full burden for siteIds and organizationId, yet it names neither and explains no filtering behavior. An agent cannot tell whether siteIds narrows the result set, returns only those sites regardless of permission, or errors on an inaccessible ID.

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?

"Site IDs and titles accessible to this API token" states a specific resource and return shape, and the resource name (sites) cleanly separates it from siblings like famly_list_groups or famly_list_employees. It stops short of saying whether it is a full enumeration or a filtered lookup, which the presence of filters makes ambiguous.

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 statement of when to use this tool, when not to, or how it relates to any alternative. With two optional filter parameters, an agent gets no guidance on whether to call it bare, with siteIds, or with organizationId.

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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered structurally. The description adds one piece of real behavioral context – results vary with token permissions – which is useful but undetailed (no indication of what happens when permissions are insufficient, e.g. empty list vs error).

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-data summary front-loaded and the API/permission caveat trailing. No filler, though the first fragment is not a grammatical sentence and could carry the verb more explicitly.

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 one-parameter read tool with no output schema, enumerating returned fields is a helpful substitute. However, the description leaves the sole parameter's meaning underspecified and gives no sense of result shape (list size, ordering, pagination), which matters since no output schema exists.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With a single parameter and 0% schema description coverage, the schema supplies only a UUID pattern with no semantics. The description ties the call to a 'site set', giving minimal meaning to siteSetId, but never explains what a site set is or where the agent obtains such an ID.

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 specific resource (staff work tags) and enumerates the returned fields (IDs, names, colour, payroll codes), which clearly separates it from siblings like famly_list_account_codes or famly_list_employees. The verb is only implied by the title 'List work tags'; the description itself is a noun phrase rather than an explicit verb+resource statement.

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 use this tool versus alternatives, nor any prerequisite or exclusion. The note that results depend on token permissions is a caveat about outcomes, not about when to select this tool.

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