Gingr MCP by usefulapi

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds only the underlying API route (GET /api/v1/get_feeding_info), with no mention of permissions, error behavior, or empty-result handling — minimal value 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 tight sentences, front-loaded with the purpose and the returned field categories. The trailing API-route sentence is mildly superfluous for an agent but is short and non-disruptive.

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

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

For a simple read-only, one-parameter tool this is close to adequate, and the '(food, amounts, schedule)' parenthetical partially compensates for the missing output schema by hinting at return contents. However, the exact response structure, pagination, and null/empty cases 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 coverage is 100% for the single animal_id parameter, so the schema already documents it ('Animal (pet) id.'). The phrase 'of one animal' confirms but adds no new meaning about format or constraints, matching the baseline 3 when the schema does the work.

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 ('Get the feeding information of one animal') and enumerates the content returned (food, amounts, schedule). The resource is distinct enough from sibling lookups like get_animal_immunizations or get_animal_medications that an agent can route correctly without opening the schema, though it never explicitly contrasts them.

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

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

The description gives no when-to-use guidance, no prerequisites, and no mention of alternative tools. The scope ('one animal') implies it is a single-record lookup, but nothing states when an agent should call this versus another animal-info 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 and openWorldHint=true, so the safe-read profile is covered structurally. The description adds genuinely useful context by disclosing that results include expiration dates and cover a single animal, which is meaningful since no output schema exists. It does not cover pagination, empty-result behavior, or auth requirements, so it stays at a baseline-plus level.

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, zero filler, with the resource and scope front-loaded before the API route reference. Nothing needs trimming.

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 whose annotations carry the safety profile, the description is close to sufficient; mentioning expiration dates partially compensates for the absent output schema. It could still say more about what the records contain or how many are returned, keeping it short of a 5.

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

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

Schema description coverage is 100% and the single animal_id parameter is fully documented in the schema. The description's 'of one animal' phrase reinforces the cardinality but adds no syntax or format detail beyond the schema, matching the baseline 3 for schema-driven 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?

States a specific verb and resource ('Get the immunization (vaccination) records of one animal') plus the scope ('one animal, with expiration dates'). It is clearly distinguishable from sibling read tools like gingr_get_animal_medications and gingr_get_animal_feeding without opening any schema.

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

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

There is no statement of when to use this tool versus alternatives, no prerequisites, and no exclusions. Usage is only inferable from the tool name and the 'one animal' scoping phrase.

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 openWorldHint=true, so the safety profile is covered. The description adds useful content context (that doses and a schedule come back) and names the underlying endpoint, but says nothing about permissions, pagination, error cases, or how missing medication data is represented.

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 purpose and followed by the endpoint path. The API path is mildly redundant for an agent but harmless; 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?

For a single-parameter read tool with no output schema, the description covers what is returned (medications, doses, schedule) and the operation's safety is carried by annotations. It is adequate, with only secondary gaps around empty results and access requirements.

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 a single parameter with 100% schema description coverage, so the schema fully documents animal_id (positive integer pet id). The description adds no syntax, format, or sourcing guidance for the id beyond what the schema already states.

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 (medication information of one animal) and enumerates the payload (medications, doses, schedule). This clearly separates it from sibling reads like get_animal_feeding and get_animal_immunizations, though it never names those alternatives 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?

No when-to-use guidance is given: nothing tells the agent when a pet's medication record is the right call versus feeding, immunizations, or a reservation lookup. The constraints (must supply an animal_id, one animal at a time) are only inferable from the schema.

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 and openWorldHint, so safety is covered by structured data. The description adds useful context by identifying the underlying endpoint and the dashboard-widget semantics, but says nothing about freshness, timezone handling, or whether counts are scoped per location.

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, front-loaded with the purpose and return contents. The trailing API endpoint reference is extra but plausibly useful for debugging and 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?

With no output schema, the description does name the returned fields (check-ins, check-outs, overnights), which is what an agent needs. Minor omissions remain around timezone/location scoping and whether counts are totals or lists.

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% and the single parameter is documented as 'The date (YYYY-MM-DD)'. The description only echoes 'for one date', adding no format, range, or default detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb (Get) and resource (summary of reservations for one date) and enumerates the exact contents: check-ins, check-outs, overnights. The parenthetical about the Gingr dashboard widget anchors the concept, and it is clearly distinguishable from siblings like list_reservations or list_checked_in.

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

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

Usage is implied rather than stated: the description frames this as the aggregate dashboard widget for a single date, which signals it is for counts rather than record listings. However, it never explicitly says when to prefer this over list_reservations or list_checked_in, nor any exclusions.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds non-obvious behavioral context beyond that: passwords and payment-card references are stripped from the returned owner, which tells the agent the payload is sanitized. It does not cover not-found behavior or whether lookups are exact-match only.

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 clauses, front-loaded with the action and the alternative identifiers before the endpoint and redaction note. Every sentence carries information; there is no filler or repetition of 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 read-only single-record lookup with 100% schema coverage and no output schema to explain, the description covers the lookup modes, the selection rule, and a notable data-sanitization trait. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds the critical 'exactly one of' cardinality constraint that the schema does not express (zero required parameters, no oneOf/anyOf). That is meaningful semantics beyond the field docs, though it adds no format or matching detail for each identifier.

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 ('Get one owner (customer) record') and immediately scopes it to a single-record fetch, which cleanly separates it from the plural sibling gingr_list_owners. It even names the upstream endpoint (GET /api/v1/owner), removing any ambiguity about what is being retrieved.

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

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

Gives an explicit invocation rule: exactly one of owner id, pet id, reservation id, phone, or email. That is real when-to-use guidance absent from the schema. It stops short of a 5 because it never contrasts itself with sibling lookups such as gingr_list_owners or gingr_list_new_modified_owners for the bulk/updated cases.

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 openWorldHint=true, so the safety profile is covered. The description adds the meaningful constraint that this applies to existing future reservations, but says nothing about permissions, rate limits, or how the estimate is computed (e.g., does it reflect current pricing/services).

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 core purpose front-loaded and no filler. The API endpoint reference is marginally useful for traceability but is not information an agent needs to select or invoke the tool.

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

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

With no output schema, the description carries the burden of explaining what an 'estimate' returns, and it does not (total only? line-item breakdown? currency?). For a trivial one-parameter read it is nearly sufficient, but the return shape is a real 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 coverage is 100% with a single required reservation_id already documented in the schema. The description adds no syntax, format, or lookup guidance beyond what the schema provides, 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 states a specific verb and resource: get the estimated cost of an existing reservation. It is clearly distinguishable from list_invoices or get_transaction, but it does not explicitly contrast itself with those siblings, so it stops 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?

The parenthetical '(future)' implies the tool only applies to upcoming reservations, which is useful scoping, but no alternative is named and no when-not condition is stated. Usage is implied rather than directed.

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 openWorldHint=true, so the safety and reach profile is covered. The description adds only the underlying REST endpoint (GET /api/v1/get_subscription); it says nothing about not-found behavior, response shape, or auth requirements, so this is baseline rather than additive.

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 purpose is front-loaded ahead of the endpoint detail. Every sentence earns its place.

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

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

For a single-parameter read tool with no output schema, the definition is sufficient: identity, lookup key, and read-only nature are all clear. The only shortfall is the absence of any hint about the returned object or the not-found case.

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

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

Schema coverage is 100% and the single parameter is fully documented by the schema ('Subscription id.', integer > 0). The description adds no format, sourcing, or constraint detail beyond 'by id', so the schema carries the weight and a 3 baseline 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 ('Get one subscription by id') and glosses the domain term as 'membership package', so the agent knows what is being fetched. It implicitly distinguishes itself from the sibling gingr_list_subscriptions by being the singular, id-keyed lookup, but never names that sibling explicitly.

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

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

The phrase 'by id' implies usage (call it when you already hold a subscription_id), but there is no explicit when-to-use versus when-to-use-an-alternative guidance. The agent must infer that gingr_list_subscriptions is the route when no id is known.

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 openWorldHint=true, so the safety profile is covered. The description adds real invocation-shaping behavior beyond that: the hard 31-day maximum range and the underlying endpoint (GET /api/v1/timeclock_report). It does not mention pagination or result ordering, 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?

Two compact sentences: purpose and scoping constraint first, endpoint reference last. No filler, nothing redundant with the title or schema.

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

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

With no output schema, the description does carry the burden of conveying returns and it names the record contents (clock-ins/outs, hours). Required parameters and the key constraint are covered. It stops short of describing response shape or ordering, a minor gap for a straightforward report call.

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 (start_date, end_date, location_id, user_ids, include_deleted, include_clocked_in) is already documented in the schema. The description only restates the conceptual scope and adds no syntax or cross-field rules, 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?

Specific verb + resource + scope: 'Get staff timeclock records (clock-ins/outs, hours) at a location between two dates'. Parenthetical even names the record contents. No sibling tool covers staff timeclock data, so it 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?

States the selection constraints that govern use: a location plus a date range capped at 31 days. It does not explicitly name an alternative tool or say when not to use it, but no sibling overlaps this data, so there is little to disambiguate.

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 openWorldHint=true, so safety is covered. The description adds genuinely useful behavioral context beyond them: sensitive fields (card numbers, processor references, auth codes) are stripped from the response, and the underlying endpoint is disclosed.

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 outcome and followed by data-quality caveats; nothing is wasted. The trailing internal endpoint path ('Gingr: POST /api/v1/transaction') is slightly noisy for an agent but does not obscure the primary 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 and a single required parameter, the description carries the burden of explaining the return shape, and it does: items plus payment details with redacted sensitive fields. For this complexity level, the definition is nearly complete; 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% — transaction_id is documented with its type and bounds — so the schema does the heavy lifting. The description adds no new meaning about the parameter beyond implying a single record lookup, which is the expected baseline.

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 ('Get one point-of-sale transaction') and names the payload ('its items and payment details'), so the agent knows exactly what is fetched. It does not explicitly differentiate itself from sibling getters such as gingr_get_subscription or gingr_get_owner, but the resource name 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?

The description gives no when-to-use guidance, no mention of the required transaction_id as a prerequisite, and no pointer to alternative tools (e.g., a list-transactions sibling) for when the id is unknown. Usage is only inferable from the name and required parameter.

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 the safety profile (readOnlyHint=true, openWorldHint=true), so the bar is lower. The description usefully adds the shapes of data returned and cites the backing endpoint (GET /api/v1/back_of_house), but says nothing about result size, ordering, or whether 'today' is location-local time.

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 core purpose front-loaded and no repetition. The '(Gingr's Digital Whiteboard)' parenthetical and API-path suffix are mildly redundant with the title but do add orientation value.

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 (owner/pet names, times, run, status) and scoping the query. It is adequately complete for a read-only reporting call, though it could clarify timezone/scoping semantics for 'today'.

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_id, type_ids, full_day, and mins_future (including the cross-dependency between them). The description only echoes 'at a location' and 'by reservation type' without adding format or defaulting detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb ('Get') and a well-defined resource: today's checking-in/checking-out pets for a location, broken down by reservation type, with the fields returned (owner/pet names, times, run, status). This is clearly distinct from a generic reservation list, though it does not explicitly name sibling tools like gingr_list_checked_in or gingr_list_reservations to disambiguate.

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 'today's arrivals and departures' framing (a daily operations board), but there is no explicit when-to-use or when-not guidance and no named alternative for narrower queries (e.g., currently-checked-in pets). The full_day/mins_future note is a parameter behavior, 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 and openWorldHint, so the safety profile is covered. The description adds a real behavioral constraint not in the annotations: only data for the location the logged-in API user belongs to is returned, which materially affects the result set. It also exposes the underlying endpoint, but says nothing about pagination beyond the limit parameter.

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 front-load the core action and filters, followed by the location constraint and API endpoint. Nothing is redundant, though the raw endpoint line is marginal value for an agent.

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

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

For a read-only list tool with 10 fully documented parameters and no output schema, the description covers the resource, filters, and the important location-scoping caveat. Return shape and pagination behavior are the only notable gaps, and with no output schema they are minor.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema. The description's mentions of states and 'by dates or types' loosely map to restrict_to, from_date/to_date, and reservation_type_ids but add no syntax or format detail beyond the schema. 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 and resource ('List the reservations of one animal (pet)') with clear scope, which implicitly separates it from the broader gingr_list_reservations and gingr_list_owner_reservations. It does not name those siblings explicitly, so it falls just short of the top band.

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

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

The description sketches what kinds of filtering are available ('optionally only pending requests, current, future, past or wait-listed ones, by dates or types'), which implies usage. However, it never says when to choose this tool over gingr_list_reservations, gingr_list_owner_reservations, or gingr_list_cancelled_reservations, leaving routing 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 and openWorldHint=true, so the safety profile is covered. The description adds value beyond that by naming the returned fields, disclosing paging behavior, and exposing the underlying route and filter syntax (GET /api/v1/animals with filters as params[<field>]).

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: identity and returned fields first, filterability second, paging and the underlying route last. No filler, and the most decision-relevant content is front-loaded.

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

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

For a read-only list tool with no output schema, the description covers what is returned, how results can be narrowed, and that results are paged, which is enough to call it correctly. It stops short of describing the paging envelope (e.g. next_offset) or default limit, which an agent would have to get from 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 coverage is 100%, so the baseline is 3, but the description goes further by mapping the filterable concepts (owner, exact name, species, breed) to the parameters and stating the params[<field>] convention used to pass them. That mapping is meaning the schema alone does not convey.

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 animals (pets)") and enumerates the fields returned (species, breed, birthday, weight, owner, notes) plus the available filters. This is unmistakably distinct from sibling tools like gingr_list_owners or gingr_list_animal_reservations, so an agent can select it without opening the schema.

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

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

The description implies usage by calling the filters "optional" and noting the result is paged, so an agent can infer that filtering and paging are supported. However, it never states when to reach for this tool versus siblings (e.g. gingr_list_animal_reservations) and gives no exclusions or prerequisites, leaving usage 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 and openWorldHint, so the safety profile is covered. The description adds genuinely new behavior: the 31-day maximum window between start_date and end_date, and the paged nature of the response, plus the underlying POST endpoint. It stops short of noting auth requirements or what happens when the window is exceeded.

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, no redundancy, with the resource and the critical 31-day constraint front-loaded before the paging note and endpoint detail.

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 filtered list tool with no output schema, the description covers what is queried, the date-window restriction, and that results are paged, which is enough to invoke it correctly. It would be stronger if it sketched the returned fields or explicitly tied paging to the offset/next_offset contract, but nothing essential is missing.

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

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

Schema description coverage is 100%, so every parameter (limit, offset, end_date, start_date, location_id) is already documented in the schema, including YYYY-MM-DD formats and the next_offset paging hint. The description only restates the date-range semantics and adds the 31-day constraint, matching the baseline for high-coverage schemas.

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 ('List the reservations that were cancelled') plus scope ('between two dates, at most 31 days apart'), which clearly sets it apart from the active-reservation siblings by virtue of the 'cancelled' qualifier. It never explicitly names a sibling such as gingr_list_reservations or gingr_list_owner_reservations to contrast against, so it falls short of the top mark.

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 description — an agent can infer it should call this when it needs cancellations in a date window — but there is no explicit when-to-use guidance, no statement of when-not-to-use it, and no named alternative for related listing needs.

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 openWorldHint=true, so the safe-read profile is covered. The description adds 'Paged' and the underlying endpoint/POST-with-filter detail, which is useful, but says nothing about return shape, page-size behavior beyond the schema, or rate limits.

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

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

Two tight sentences: the what/scope first, then paging and the backing API call. No filler, nothing repeated, and the most important information is front-loaded.

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 adequately conveys that reservations for currently checked-in pets are returned and that results are paged. It is complete enough to call correctly, though a note on how the location filter interacts with the 'checked in' scope would close the last 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% and all three parameters (limit, offset, location_id) are documented in the schema, including the next_offset paging hint. The description adds no semantics 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 ('list the reservations') and narrows scope precisely to those 'checked in right now (the pets currently on site)'. That scope alone separates it from siblings like gingr_list_reservations and gingr_list_cancelled_reservations without needing to open their schemas.

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 parenthetical '(the pets currently on site)' gives a clear condition for selecting this tool over the general reservation lists. It stops short of naming an alternative tool or a when-not-to-use case, so it lands at clear-context rather than explicit-routing.

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 and openWorldHint, so safety is covered; the description adds the non-obvious pagination contract (per_page plus start, next page at start + per_page) and the implicit 2019-08-01 lower bound on returned records, which the annotations do not 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?

Three tightly packed sentences, front-loaded with the mode selection, followed by filters, pagination, and the underlying endpoint. Every sentence carries distinct information 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?

For a 6-parameter read-only list tool with no output schema, the description covers filtering, defaults, and pagination well enough to call it correctly. The only gap is that it never hints at the shape of the returned invoice/estimate records, which no output schema supplies either.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by explaining the pagination arithmetic (next page = start + per_page) and restating the complete=true/false-to-invoices/estimates mapping in prose, which clarifies intent beyond the terse schema blurbs.

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 (List) and resource (invoices/estimates) and immediately disambiguates the dual mode via the complete flag, including which mode is the default. An agent can tell exactly what this returns without opening the schema.

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

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

The description supplies operating context (records created on or after 2019-08-01, optional closed_only and date-range filtering) but never says when to choose this tool over the sibling list_* tools or states any prerequisite. Usage is implied by the filter semantics rather than explicit.

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

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

With readOnlyHint and openWorldHint already declared, the description adds useful context beyond annotations: the exact return shape (id value + name label) and the underlying GET endpoint. It does not cover auth, rate limits, or pagination, but for a simple read-only list it adds meaningful operational detail.

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 tightly packed sentences with zero waste: purpose and output first, then the key usage insight, then the endpoint. The most important routing advice is front-loaded and easy to scan.

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 parameterless list tool with no output schema, the description supplies the missing return shape, the endpoint, and the integration role ('most other tools take a location_id'). An agent has everything needed to call it and use its result correctly.

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

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

The tool has zero parameters, so the baseline is 4. The description adds no parameter semantics because none exist, but it does clarify the output mapping of id and name, which helps the agent use the result.

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 (locations/facilities of this Gingr app) and specifies the returned shape (id as value, name as label). It also positions the tool relative to its siblings as the prerequisite call for any tool needing a location_id, so an agent can identify it without opening the schema.

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

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

The phrase 'Good first call: most other tools take a location_id' gives clear usage context and a strong routing signal to call this before other operations. It lacks explicit when-not-to-use guidance and does not name specific alternatives, keeping it short of 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, and the description adds worthwhile context beyond them: pagination is disclosed, the 366-day window cap is a real operational constraint, and the underlying Gingr endpoint is POST despite the read-only hint, which pre-empts confusion. It stops short of describing result contents or total-count 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 compact sentences with zero filler, ordered purpose → constraint/paging → backing endpoint. Every clause earns its place and the differentiating scope detail is front-loaded.

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 paged list tool with no output schema, the definition covers the essential calling contract: bounded date range, paging via the schema's next_offset hint, and the 366-day rule. Only the shape of returned owner records is left unspecified, which is a minor gap for a list endpoint.

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 3 is the baseline, but the description adds a genuine semantic constraint the schema omits: the 366-day maximum span between start_date and end_date. That cross-parameter rule is exactly the kind of meaning the schema cannot express and materially affects correct 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?

Specific verb+resource with a precise scope qualifier: owners 'created or modified between two dates (at most 366 days apart)'. This clearly separates it from the broader gingr_list_owners, though it never names that sibling explicitly. An agent can infer the delta-listing purpose from the filter semantics alone.

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 'at most 366 days apart' constraint and 'created or modified' framing imply the intended use case (delta/sync listing over a bounded window), but there is no explicit when-to-use statement, no exclusion of the sibling gingr_list_owners, and no guidance on which to pick for a full listing. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds a non-obvious behavioral constraint the annotations do not: only records from the location the API user is logged into are returned, and it discloses the underlying POST endpoint despite the read semantics. It does not mention result ordering or pagination beyond the schema's limit.

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 core scope front-loaded, followed by the location caveat and endpoint. Slightly redundant 'Gingr:' prefix on the endpoint line, but otherwise 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?

For a 10-parameter read tool with full schema coverage and annotations, the description supplies purpose, filter dimensions, and the important location-scoping constraint. Return-format details are unnecessary since no output schema is expected to be explained here, though pagination/ordering behavior is left unstated.

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 restrict_to enum and limit bounds is already documented in the schema. The description only restates the filter categories (dates, types, pets) and the state list that mirror the schema, adding no syntax or interaction details beyond it. Baseline 3 applies.

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

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

States a specific verb and resource with an explicit scope ('reservations of one owner'), which cleanly separates it from gingr_list_reservations (all owners) and gingr_list_animal_reservations (one pet). The optional state/dimension filters are enumerated up front, so an agent knows exactly what this returns.

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 scope ('of one owner' plus filterable by dates, types, pets), and the location caveat gives real deployment context. However, it never states when to prefer this over the sibling listers (gingr_list_reservations, gingr_list_animal_reservations) or any prerequisite beyond the owner id.

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 openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavior the annotations cannot convey: the result set is paged, and passwords and payment-card references are stripped from the response, which tells the agent what data it can and cannot expect.

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

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

Three tight sentences, no filler: purpose and payload first, filters second, paging and redaction last. Fragments like 'Paged.' carry real information rather than padding.

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

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

With no output schema, the description correctly summarizes what comes back and what is redacted, and all eight optional parameters are schema-documented. The only soft spot is pagination: it says 'Paged' but does not mention limit/offset or next_offset, which the schema does cover, so the gap is small.

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% and every filter parameter is already documented with exact-match semantics, so the description's restatement of the filterable fields adds little. The one extra hint is how filters map upstream (params[<field>]), which is not directly actionable on the MCP surface. 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 (List) and resource (owners / pet parents / customers), and enumerates the returned payload (contact details, balance, reservation counts). An agent can immediately separate it from gingr_get_owner (single record) and gingr_list_new_modified_owners (incremental sync).

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 explains that filtering is optional and by exact-match fields, and flags the result as paged, which implies a browsing/retrieval use case. But it never names an alternative (e.g. gingr_get_owner for one owner, gingr_list_new_modified_owners for changed-since sync) or states when not to use it, so routing must be inferred from the sibling 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=true and openWorldHint=true, so the safety profile is covered externally. The description adds genuinely useful behavior beyond that: the lists are paged, and it maps each kind to its underlying Gingr endpoint. It stops short of stating auth requirements, rate limits, or result shape, so a 3 is right with annotations carrying the main load.

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, both front-loaded with the highest-value information (what kinds exist, then the species_id caveat), with the endpoint mapping compressed to a trailing list. Dense but nothing is padding; the endpoint list is marginally redundant for an agent but aids disambiguation.

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, fully schema-documented list tool this covers the essentials: what can be listed, the one conditional parameter dependency, and paging. With no output schema, it could say more about what each record contains, but the annotation and schema already carry the bulk of what's needed.

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 baseline is 3, but the description goes further by giving real semantics to the bare enum values ('vets' = veterinarians with details, 'retail_items' = items for sale) and by noting the paged nature of limit/offset. It does not expand on limit/offset defaults, which the schema already handles.

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') plus resource ('reference data') and then enumerates the exact six kinds, each glossed in plain English ('vets (veterinarians with details)', 'retail_items (retail items for sale)'). An agent can distinguish this from the resource-specific siblings like gingr_list_locations or gingr_list_reservation_types without opening a schema.

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

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

Gives an explicit conditional precondition — immunization_types 'needs species_id' — which is actionable usage guidance. It does not name when NOT to use it or point at alternatives, but the sibling tools all cover different resources, so the routing risk is low.

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 openWorldHint=true, so safety and external data access are covered. The description adds the sort order ('newest first') and content types, but doesn't disclose pagination behavior, rate limits, or what 'recently' means. With annotations covering the safety profile, a 3 is appropriate for the modest additional context.

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 concise sentences with no waste, front-loading the core purpose and then providing the API endpoint and sort order. Every element earns its place.

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

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

For a simple read-only list tool with a complete schema and annotations, the description covers the essentials: what it lists, content types, sort order, and the API path. It doesn't need to explain return values (no output schema) or safety (annotations cover it). It could mention pagination or what 'recently' means, but it's largely complete.

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

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

Schema coverage is 100%, so the schema already documents both parameters with their ranges and defaults. The description doesn't add any parameter-specific information beyond what's in the schema, which is the correct baseline when the schema is complete.

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 ('List recently uploaded report card files') and clarifies the content scope ('photos and videos shared with pet parents'), plus the sort order. It distinguishes itself from sibling list tools like gingr_list_owners or gingr_list_invoices by naming the resource, though it doesn't explicitly contrast with the other list 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 description implies usage through 'recently uploaded' and 'newest first', but offers no explicit when-to-use guidance or alternatives. There's no mention of when to filter by location_id versus not, though the schema parameter clarifies it comes from gingr_list_locations.

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 openWorldHint=true, and the description adds real value on top: the hard 30-day range cap, the returned paging envelope (total, next_offset, items), and the underlying POST /api/v1/reservations endpoint with checked_in=false. It does not mention auth or rate-limit behavior, but the added operational constraints go well 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?

Dense but front-loaded: purpose and scope come first, then the constraint, then the return shape, then the endpoint. Nothing is redundant, though the trailing endpoint reference is more implementation trivia than agent-facing guidance.

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 response envelope (total, next_offset, items) and the paging parameter semantics. Combined with a 100%-covered input schema and read-only annotations, an agent has enough to call it correctly; only sibling routing is left implicit.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema; baseline is 3. The description reinforces the 30-day constraint on start/end and the paged nature of limit/offset, but adds no new syntax or format meaning 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 and resource plus the enumerable scope ('reservations (boarding, daycare, grooming, training…) between two dates'), which an agent can distinguish from narrower siblings like gingr_list_animal_reservations or gingr_list_owner_reservations. It does not, however, explicitly name those siblings or say this is the unfiltered, organization-wide variant, so differentiation is implicit rather than stated.

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

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

The 30-day window limit and paging note imply when the tool is applicable, and '(checked_in=false)' hints that checked-in reservations belong to gingr_list_checked_in. But there is no explicit 'use this when / use X instead' routing against the many reservation-listing siblings, so usage must be inferred.

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

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

Annotations cover readOnlyHint and openWorldHint, so the safety profile is already known. The description adds useful context about the returned payload shape (ids) and the purpose of those ids, which is behavioral value beyond the annotations.

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

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

Three sentences, front-loaded with the core action, followed by usage and endpoint. No filler; every sentence 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 simple list tool with annotations covering safety and open-world access, the description supplies the resource meaning, id-usage guidance, and endpoint. Nothing essential 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 coverage is 100%, so both parameters (id, active_only) are fully documented in the schema. The description adds no extra semantics about parameter syntax or defaults. 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?

Specific verb+resource: 'List the reservation types... with their ids.' The parenthetical enumerates concrete examples (boarding, daycare, grooming, training), and the API endpoint is named. It is clearly distinguishable from siblings like gingr_list_reservations or gingr_list_services_by_type.

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 downstream usage: 'Use the ids to filter reservations or to read a type's add-on services.' This tells the agent why and when to call it, though it doesn't explicitly name an alternative tool or state 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 declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds only the raw endpoint path ('GET /api/v1/get_services_by_type'), which is plumbing rather than behavior — no word on permissions/scoping, whether location_id narrows results, or response shape.

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 carries the meaning and the example is compact and clarifying. The trailing 'Gingr: GET /api/v1/get_services_by_type' is marginal filler for an agent that cannot call the raw endpoint anyway.

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-only list with a fully documented schema, the description is adequate: it says what the list contains and gives an example. Without an output schema, a brief note on what each returned service includes would have closed the last 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%: type_id and location_id are both documented in-schema, including the chaining hint '(from gingr_list_reservation_types)'. The description adds only illustrative examples of services, not parameter meaning, 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 clear verb ('List') and a precise resource ('additional services (add-ons) allowed for a reservation type'), with a concrete example (baths, nail trims on a boarding stay) that pins down what an add-on is. No sibling tool covers services-by-type, so it is inherently distinguishable, but the description never explicitly contrasts itself with a related tool like gingr_list_reservation_types.

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

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

Usage is implied rather than stated: an agent can infer this is the way to discover which add-ons are valid for a given reservation type. There is no explicit when-to-use, when-not-to-use, or named alternative, so it lands at minimum-viable 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 and openWorldHint=true, so safety is covered; the description adds genuinely new behavioral context: results are Gingr-paged via limit+offset and cancelled records are excluded unless explicitly requested. It does not mention rate limits or ordering, which keeps it short of a 5.

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

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

Two tight sentences front-load the resource and scope, then cover filters and paging with no filler. The trailing 'Gingr: GET /api/v1/get_subscriptions.' is useful provenance but slightly redundant with the tool name.

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 seven-parameter, all-optional read tool with no output schema and read-only annotations already declared, the description covers filtering, paging and the deleted-record toggle adequately. It stops short of noting sort order or the general shape of returned subscription records.

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 seven parameters with bounds and defaults. The description restates the main filter axes (owner, location, package, billing day) and the paging model without adding syntax or nuance the schema lacks, which is the expected baseline.

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 ('List recurring subscriptions (membership packages)') and clarifies scope with the available filter dimensions. It implicitly separates itself from the singular sibling gingr_get_subscription, but never names it, so the sibling differentiation is left to inference.

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

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

It states that the owner/location/package filters are optional and that cancelled subscriptions appear 'if asked,' which implies the include_deleted behavior. However, it never says when to prefer this list tool over gingr_get_subscription or how it relates to owner lookups, 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.