Homebase MCP by usefulapi

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so safety is covered. The description adds useful context that the result is scoped to the calling API key (no identifier needed), but omits error/rate-limit behavior. With annotations carrying the safety profile, a 3 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?

A single front-loaded sentence that names the resource and its fields, with no waste. The trailing 'GET /company.' is mildly redundant protocol detail but does not detract from the structure.

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

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

With no output schema, the description compensates by enumerating the returned fields (name, owner id/name/email/phone, timestamps). For a zero-param read tool this is close to complete; only error behavior is left unspecified.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly conveys that no identifier is supplied and the company is derived from the API key, which is the only parameter-adjacent semantics that matter here.

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

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

States a specific verb-implied resource ('the Homebase company this API key belongs to') and enumerates the returned fields (name, owner details, created/updated times). This clearly distinguishes it from the employee, location, shift, and timecard 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?

Usage is implied by the 'this API key belongs to' scoping, which signals a single company-fetch context, but there is no explicit when-to-use, no when-not, and no mention of any alternative sibling.

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, destructiveHint=false and openWorldHint=true, so safety and network scope are covered. The description adds the exact REST path and confirms the shape of what comes back, but says nothing about behavior for a missing/archived employee or error conditions.

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

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

Two tight sentences: the payload description leads and the REST endpoint trails as supplementary context. No filler, though the parenthetical field list is dense.

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

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

With no output schema, the description compensates by naming the returned fields, and all three parameters are documented in-schema. For a simple single-resource read this is close to sufficient; only error/not-found behavior is 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 100%, including the archived-toggle semantics for with_archived and the id provenance, so the baseline is 3. The description restates that employee_id is the user id from the list tool but adds no format or constraint detail beyond the schema.

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

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

States a specific verb+resource ('One employee of a location by user id') and enumerates the returned payload (contact details, role, wage type/rate, payroll id), which cleanly separates it from homebase_list_employees and the other get_* 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?

It tells the agent where the required inputs originate ('the id is the job's user id from homebase_list_employees') and the schema points to homebase_list_locations for the uuid, so the lookup workflow is implied. It stops short of an explicit 'use this instead of X when...' exclusion statement.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds value by enumerating the returned metric categories (regular/overtime/paid hours, labor cost, tips, breaks, time off), but discloses nothing about auth requirements, rate limits or 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?

It is a single sentence with the primary action and grouping options front-loaded, followed by the metric list and endpoint path. Slightly dense with the enumerated fields, but no wasted 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?

For a read-only reporting tool with full schema coverage and annotations carrying the safety profile, the description covers action, scope and output fields. Without an output schema the metric list helpfully previews results, though pagination/limits remain undisclosed.

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

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

Schema description coverage is 100%, so the schema already documents location_uuid, start_date, end_date and the group_by enum. The description only echoes the date-range and day/hour grouping, adding no format or constraint detail beyond the schema. Baseline 3 applies.

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

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

The description uses a specific verb ("Aggregate") and resource ("labor") and defines scope (location, date range, day/hour grouping) plus the returned metrics. It does not explicitly name the closely related siblings homebase_get_labor_by_employee or homebase_get_labor_by_role, so differentiation is only 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?

It states the aggregation context but gives no explicit when-to-use or when-not-to-use guidance. Given siblings like homebase_get_labor_by_employee and homebase_get_labor_by_role exist, an agent gets no signal about which labor tool to pick.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered without description support. The description adds the aggregated field list but says nothing about pagination, result size limits, or auth/scoping requirements for an open-world report endpoint.

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

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

Two tightly written sentences, with the aggregation scope and grouping front-loaded before the use case. The trailing REST path is somewhat redundant given the tool name and the location_uuid parameter, but it is short and not harmful.

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 reasonably by naming the returned aggregates (hours, cost, wage rate, tips, overtime, time off). For a date-range report it does not mention pagination or result caps, which is the main remaining gap.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters with ISO 8601 formats and the location_uuid source. The description confirms the date-range/location framing but adds no syntax or constraint detail beyond the schema, making the baseline 3 correct.

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 ('Aggregate labor... grouped by employee') and enumerates the aggregated metrics (hours, cost, wage rate, tips, overtime, time off). The 'grouped by employee' phrase implicitly distinguishes it from homebase_get_labor and homebase_get_labor_by_role, but neither sibling is named, so the differentiation must be inferred.

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 totals' gives one concrete scenario, which is helpful context for choosing this over other labor tools. However, there is no guidance on when NOT to use it or on routing to homebase_get_labor / homebase_get_labor_by_role, which are the obvious alternatives.

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, destructiveHint=false, and openWorldHint=true, so safety is covered. The description adds that the report aggregates a specific metric set (hours, cost, tips, overtime) grouped by role, which is useful context, but says nothing about auth, pagination, or aggregation edge cases.

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

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

Two tight sentences with the metrics and grouping front-loaded ahead of the endpoint reference. The 'for a location in a date range' clause mildly restates required params but costs little.

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

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

No output schema exists, and the description compensates reasonably by enumerating the aggregated metrics and the grouping key. It is complete enough for a read-only aggregate report, with only return-format/pagination details 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 coverage is 100% and all three required parameters are fully documented in-schema (including ISO 8601 date formats and the location_uuid source). The description only restates 'location' and 'date range', adding no format or syntax detail beyond the schema.

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

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

States a specific verb (aggregate), resource (labor), and distinguishing grouping dimension ('by role'), plus the exact endpoint. An agent can tell it apart from homebase_get_labor and homebase_get_labor_by_employee by the grouping, though it never names those siblings 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 implied by 'grouped by role' but there is no explicit when-to-use/when-not guidance or named alternative, so the agent must infer that this is the role-bucketed variant of the labor report.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds value beyond them by disclosing the returned field set (name, address, phone, website, time zone, POS merchant id) and the underlying endpoint GET /locations/{location_uuid}, which is useful given there is no output schema.

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

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

Two telegraphic clauses with no filler: the resource and return fields come first, the endpoint mapping second. Every fragment carries information an agent can use.

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 no output schema, the description compensates by listing the returned fields and citing the endpoint, and annotations cover the safety profile. It is nearly complete, though a note on what happens for an unknown uuid (error vs empty) is 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?

There is only one parameter with 100% schema description coverage, including the pattern and a pointer to homebase_list_locations as the source. The description's 'by uuid' adds no semantics beyond what the schema already states, so the baseline of 3 applies.

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

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

States a specific verb ('Get') and resource ('one location by uuid') and enumerates the returned fields, which cleanly separates it from the plural homebase_list_locations. It does not explicitly name siblings like homebase_get_location_plan, so differentiation relies on inference from the singular 'one location'.

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 'by uuid' implies the prerequisite of already having a location uuid, which the schema confirms comes from homebase_list_locations. However, there is no explicit when-to-use guidance or any statement about when to prefer this over homebase_list_locations or homebase_get_location_plan.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description goes beyond that by disclosing the fields the response will carry, which matters here because there is no output schema. It does not mention auth needs, rate limits or error behavior, so it falls short of a 5.

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

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

Two short sentences, front-loaded with the resource and its returned fields. The trailing 'GET /locations/{location_uuid}/plan' is mildly redundant with the tool name and schema path, but the text is otherwise free of 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?

For a single-parameter read with annotations covering safety and no output schema, the definition is nearly sufficient — the response contents are spelled out in the description. It lacks only guidance on when this call is warranted versus other location lookups.

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?

There is one parameter and schema coverage is 100%; the schema description already explains it is a Homebase location uuid sourced from homebase_list_locations. The description adds nothing about the parameter beyond repeating the path variable, 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?

Names a specific verb and resource ('The Homebase subscription plan of a location') and enumerates exactly what the plan object contains: plan number, price, last update and trial state. No sibling tool retrieves a plan, so it is unambiguously distinguishable from the other homebase_get_* tools.

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 by the resource name — call it to read a location's plan — but there is no explicit when/when-not statement or named alternative. The only routing hint ('from homebase_list_locations') lives in the schema, not the description.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered structurally. The description adds only that the response carries labor data and an optional note; it says nothing about permissions, scoping, or the note's behavior when with_note is false.

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

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

Two tight sentences with zero filler, leading with the resource and following with the endpoint. Every clause (resource, payload, note, route) carries information.

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

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

For a small read-only getter with no output schema, the description plus the 100%-covered schema give an agent enough to invoke it correctly. It could say more about what 'labor data' contains, but that is a minor gap given the tool's simplicity.

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 both required params and with_note are already documented in the schema. The description's phrase 'optional note' loosely mirrors with_note but adds no format, default, or constraint detail 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+resource ('One shift of a location by id') and names the extra payload ('labor data and optional note'), which clearly separates it from the list_shifts sibling. It stops short of explicitly contrasting with homebase_list_shifts, so it is clear but not maximally differentiating.

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?

'By id' implies this is the single-record lookup as opposed to the listing tools, and the mention of labor data hints at when it is useful. However, there is no explicit when-to-use/when-not-to-use guidance or named alternative, so 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.

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

Annotations already cover readOnlyHint=true, destructiveHint=false, openWorldHint=true, so the safety profile is known. The description adds useful payload context (clock in/out, breaks, labor hours and cost, tips, approval state) beyond annotations, but does not mention the GET path being idempotent simply because it repeats the URL.

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 clauses: what the tool returns and the endpoint path. Front-loaded with the resource and its contents, no filler. Could be slightly tighter by dropping the path which duplicates the schema.

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

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

For a simple 2-param read with no output schema, the description covers the returned fields adequately and annotations cover safety. However, it omits pagination/error semantics and does not identify sibling alternatives, leaving minor gaps for an agent choosing between timecard 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 coverage is 100% and both parameters are documented with descriptions (timecard_id, location_uuid with source hint). The description adds little beyond the schema; the 'by id' phrasing only weakly maps to the timecard_id 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+resource: one timecard of a location by id, and lists the returned fields. It distinguishes itself implicitly from list_timecards and list_deleted_timecards by 'one ... by id', though it doesn't explicitly name those siblings.

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

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

The 'get one by id' framing implies when to use it over list_timecards, but no explicit when-to-use or when-not-to-use is stated. No prerequisites or exclusions are given.

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful context about what is returned: current state, current shift, clockable shifts, and startable breaks, plus the underlying GET endpoint. It does not discuss auth or rate limits, but it goes beyond structured annotations for a read-only status call.

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 no filler. The core state information is front-loaded, followed by the prerequisite for the required parameter and the endpoint. Every sentence contributes useful content.

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 no output schema, the description adequately explains the return content (current state, current shift, available clock-ins and breaks), the required job id and where to get it, and the endpoint. Annotations cover the safety semantics, so little is missing for correct 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 coverage is 100% and the job_id parameter is fully documented in the schema. The description adds meaning by specifying that the job id is the `job.id` of an employee obtainable from homebase_list_employees, giving an agent a clear source for the required value.

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+resource: retrieves the current time-clock state of one job, and enumerates the state values (clocked_in, on_break, clocked_out). It also distinguishes the job concept by pointing to homebase_list_employees for obtaining the job id, helping separate it from sibling employee and shift tools.

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 by the stated purpose, and the description gives a prerequisite: the job id comes from homebase_list_employees. However, it does not explicitly say when to use this tool versus alternatives such as homebase_get_timecard, homebase_get_shift, or list tools, nor does it provide when-not guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. Beyond that the description discloses the payload shape (ids with start, end, and deletion time) and the underlying endpoint, which is genuinely additive given there is no output schema.

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

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

Two sentences, front-loaded with the result payload and the sync use case, with the REST path trailing harmlessly. Efficient and well ordered, with no filler, though the endpoint string is marginal 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 no output schema, the description usefully enumerates the returned fields, and pagination semantics live in the schema. What remains thin is the deletion/timezone nuance of deletion time and any guidance on large ranges, but nothing essential for a correct call is missing.

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

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

Schema description coverage is 100%: the schema already documents ISO 8601 formats for start_date/end_date, pagination via page/per_page and next_page, and the location_uuid source. The description only restates "date range at a location" and adds no format or constraint detail, so baseline 3 applies.

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

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

The description states a specific verb+resource with precise scope: shift ids deleted within a date range at a given location, plus the fields returned. It is clearly separable from homebase_list_shifts (live shifts) and homebase_list_deleted_timecards (different resource), though it never names a sibling explicitly.

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

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

"Use it to keep a copy of the schedule in sync" gives one concrete scenario (reconciliation/sync), which implies when to reach for it. However it offers no when-not guidance and does not contrast with homebase_list_deleted_timecards or homebase_list_shifts, leaving the routing decision partly to inference.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the return fields (ids, clock in, clock out, deletion time) and the underlying GET endpoint, but discloses nothing further about auth, rate limits, or pagination behavior.

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

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

Two compact sentences that lead with what is returned and follow with the sync use case. No wasted words, though it is slightly terse for the amount of behavioral context it could carry.

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

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

With no output schema, the description correctly carries the return-value burden by naming the fields returned. Combined with the annotations covering safety and the schema covering params, an agent has what it needs to call it correctly; only edge-case behavior (large ranges, empty results) is 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 100%, so all five parameters are fully documented in the schema, including ISO 8601 formats, pagination defaults and the next_page chaining hint. The description adds no parameter detail beyond that, 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: listing timecard ids deleted within a date range at a location, including clock in/out and deletion time. The word 'deleted' distinguishes it from the sibling homebase_list_timecards, but no sibling is 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?

Gives a clear use case ('keep a copy of the timecards in sync'), which tells the agent when this tool is appropriate. It stops short of naming alternatives or stating when not to use it.

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 the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the bar is lower. The description still adds real value by disclosing that the time-clock PIN is never returned, a data-exposure constraint not derivable from annotations or schema.

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

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

Two compact sentences plus the endpoint path, front-loaded with the core action and returned fields. Every clause earns its place with no 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 usefully enumerates the returned fields and adds the PIN-exclusion caveat, which is exactly the kind of detail an agent needs. It stops short of noting the default archived behavior or pagination, but those are covered by the schema.

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

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

Schema description coverage is 100%, so all four parameters (page, per_page, location_uuid, with_archived) are already documented in the schema. The description adds nothing about parameter syntax or behavior beyond the location scoping, 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?

The description gives a specific verb (list) and resource (employees of a location) and enumerates the returned data (contact details, job level, roles, wage type/rate, payroll id, archive date), which clearly separates it from the singular homebase_get_employee and from homebase_list_locations. It does not explicitly name the sibling it is not, so it falls just 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?

Usage is only implied by the location scoping ("employees of a location"); there is no explicit when-to-use statement, no exclusion telling the agent to use homebase_get_employee for a single person, and no prerequisite beyond the location uuid that the schema already documents. Adequate but with clear gaps.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the endpoint (GET /locations) and the field set, but says nothing about pagination, result caps, or empty-account behavior. Reasonable but not rich beyond the annotations.

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

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

Two short sentences, front-loaded with purpose and then the key operational note about uuid, plus a compact endpoint suffix. Every clause earns its place 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?

With no output schema and no parameters, the description carries the burden of describing the response, and it does so by listing uuid, name, address, phone, website and time zone. It stops short of noting pagination or whether the list can be filtered, which leaves a small gap.

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

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

The tool takes zero parameters, so the baseline is 4; there is no parameter semantics to clarify and the description correctly adds none. It neither misleads nor omits anything parameter-related.

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

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

States a specific verb and resource ('List the locations (stores or sites) of the account') and enumerates the returned fields, which is concrete and unambiguous. It clearly contrasts with the singular homebase_get_location sibling by virtue of being a bulk list, but no sibling is named explicitly to force the distinction.

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

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

Provides strong usage context without formal exclusions: 'The uuid is the id every other Homebase tool needs' tells the agent to call this first when it needs a location uuid to feed other Homebase tools. There is no explicit when-not or named alternative, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, so the safety profile is covered. The description adds real value beyond them by inventorying exactly what each shift record contains (wage rate, regular/overtime scheduled hours, published state) and naming the GET endpoint, which matters since there is no output schema.

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

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

A single front-loaded sentence that names the verb and resource first and then the returned fields, with the endpoint appended. Dense but every clause contributes; the colon-delimited field list is slightly run-on.

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

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

With no output schema, the field inventory substitutes well for a return-value contract, and the endpoint plus annotations round out the operational picture. Pagination behavior lives in the schema, so nothing critical is missing, though an explicit note on the deleted-shift sibling would complete it.

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

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

Schema description coverage is 100%, so all eight parameters (including open, date_filter, page, per_page, with_note) are already documented in the schema. The description adds only the 'filter open shifts only' hint, which the schema already states; baseline 3 is correct when the schema carries the parameter burden.

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+resource ('List the scheduled shifts of a location in a date range') and enumerates the returned data (employee, role, department, start/end, published/open state, wage rate, labor hours). It implicitly separates itself from sibling tools like homebase_list_deleted_shifts and homebase_get_shift, but never names an alternative to make the distinction explicit.

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

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

It states the one filtering behavior available ('Filter open shifts only'), which maps to the `open` parameter, but gives no guidance on when to choose this tool over homebase_get_shift (single shift) or homebase_list_deleted_shifts. Usage is implied by the resource scope 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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds genuinely non-obvious behavioral data: that time-off hours are always 0 on timecards, and which fields each record carries. It does not discuss result ordering or pagination semantics, which the schema handles instead.

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

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

Two dense sentences plus the endpoint path, all front-loaded: resource and scope first, then the field inventory, then the time-off caveat and alternative. No filler or repetition.

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 returned fields (employee, role, clock in/out, breaks, hours, labor cost, tips, approval state) and warns about the time-off=0 trap. Pagination is covered by the schema, so the remaining gap is minor (no ordering or volume expectations).

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

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

Schema description coverage is 100%, so every parameter (including the date_filter enum and the page/per_page follow-the-next_page instruction) is already documented in structured data. The description restates the date-range scoping but adds no syntax, defaults, or constraints beyond the schema, so baseline 3 is appropriate.

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

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

States a specific verb (List), resource (timecards), and scope (a location, in a date range), then enumerates what each record contains. It is clearly distinguishable from homebase_get_timecard (single record) and homebase_list_deleted_timecards by its 'worked time' framing and the API path GET /locations/{location_uuid}/timecards.

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?

Explicitly routes one case away from this tool: 'Time-off hours are always 0 on timecards; use homebase_get_labor_by_employee for totals with time off.' That is a real alternative with a stated condition. It stops short of when-not-to-use guidance against other siblings (get_timecard, list_deleted_timecards) and says nothing about pagination as a usage pattern.

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