hairdora

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

Beyond the readOnlyHint/idempotentHint/destructiveHint annotations, it adds valuable behavioral details: other-organization appointments are deliberately reported as not found, and it explicitly lists excluded data (notes, reminders, contact details, organization data, payment data) and the 50-service cap. These are material traits an agent could not infer from annotations alone.

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 purposeful sentences with the core fetch action and id source front-loaded. Each sentence contributes distinct information: return fields, exclusions, and cross-organization not-found behavior; there is 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 single-parameter read operation with a full output schema and safety annotations, the description covers the remaining operational details an agent needs. Nothing critical is missing for correct invocation or interpretation.

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 appointmentId as a 24-lowercase-hex id returned by list_appointments. The description reinforces that provenance but adds no new format, constraints, or default semantics 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?

The description opens with a specific verb ('Fetch') and resource ('one tenant-scoped HairDora appointment') and ties the id to list_appointments, clearly distinguishing it from the list/get siblings. It further narrows the tool's scope by naming the returned fields.

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 establishes that the id must come from list_appointments, implicitly telling an agent when this tool applies: after obtaining an appointment id from the list call. It does not explicitly spell out 'use this instead of list_appointments when you need one appointment's details,' but the sibling context makes that obvious.

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 idempotentHint=true, so the safety profile is known. The description adds valuable behavioral detail beyond the annotations: it enumerates the exact fields returned, those excluded, and the behavior for clients owned by another organization (reported as not found). This enriches the agent's understanding of the response and error semantics.

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

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

The description is composed of three clear sentences: purpose, returned fields, and excluded/edge-case behavior. It is front-loaded with the core purpose and is reasonably concise. It could be slightly tighter, but every sentence adds necessary context.

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

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

For a single-parameter read operation, the description covers the essential information: what will be returned, what will not, and an important edge case. Since an output schema exists (though not shown in prompt), the return field enumeration is a helpful supplement. Nothing critical for calling this tool 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 input schema already fully documents the clientId parameter (type, pattern, and source). The description repeats 'from list_clients' but adds no new meaning. With full schema coverage, the baseline of 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?

The description uses a specific verb 'Fetch' and names the resource 'tenant-scoped HairDora client', plus the identifier source ('from list_clients'). It clearly differentiates from sibling tools by stating exactly which fields are returned and which are excluded, making it impossible to confuse with list_clients or other 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?

It implies when to use it: after list_clients, and for workflow chaining. It doesn't explicitly exclude alternatives, but the context 'needed for client and appointment workflow chaining' and the exclusion of detailed fields give implicit guidance. It also notes the cross-organization not-found behavior, which helps callers handle errors.

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

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

Beyond the readOnlyHint/idempotentHint annotations, the description reveals useful behaviors: it is tenant-scoped, explicitly excludes sensitive/internal fields like organization ids and payment configuration, and reports cross-organization salons as not found. This is meaningful behavioral context that annotations alone 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 dense sentences carry only relevant information: the primary purpose, the returned data shape and exclusions, and the cross-tenant behavior. The most important information is front-loaded, and 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?

With an output schema present and only one well-documented parameter, the description covers everything an agent needs to invoke the tool correctly. It explains scope, exclusions, and an important not-found edge case without redundantly restating 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 the parameter semantics are already fully documented in the schema. The description reinforces that salonId comes from list_salons, which is helpful, but it adds no format or syntactic details beyond what the schema already provides.

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

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

The description opens with a specific verb and resource: 'Fetch one tenant-scoped HairDora salon by an id returned from list_salons.' It clearly differentiates the tool from list_salons by specifying that a single salon is fetched using a previously returned id, and the field list makes the purpose concrete.

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 clear context by stating that the salon id must come from list_salons and that salons from other organizations are treated as not found. It does not explicitly name alternative tools or state when not to use this tool, but the provenance requirement effectively guides the agent on the correct workflow.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds valuable behavioral context: it returns a safe summary never exposing who occupies unavailable times, proves tenant ownership, and fails closed for other organizations. This goes 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?

Three tightly scoped sentences: purpose first, then the fixed window and return summary, then the safety/ownership guarantee. Every sentence earns its place with zero 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?

The output schema covers return values, and the description covers the window, the summary contents, and the privacy/ownership guarantees. For a single-parameter read-only tool, nothing an agent needs 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?

The single parameter salonId is fully documented in the schema (pattern, description, and reference to list_salons). The description adds no additional meaning 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?

The description opens with a precise verb and resource: 'Summarize bookable availability for one owned salon.' It also differentiates from siblings by specifying the single-salon scope and the fixed time window, so an agent can clearly tell it apart from the other get_/list_ 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?

The description provides clear context for when to use it — for one owned salon, with a fixed window — and explicitly states the ownership check and fail-closed behavior. However, it does not explicitly name alternative tools or state when not to use it, leaving that to inference from the sibling list.

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 mark it read-only/idempotent/non-destructive; the description adds sorting, server-side field exclusion, pagination cap, and hasMore truncation reporting. This goes well beyond the annotation safety profile.

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 and scope, then projection, then filtering/pagination. No filler or repetition of schema details.

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 a rich input schema, an output schema, and annotations, the description covers auth scope, sort, projection, filtering, pagination, and truncation. Nothing needed 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 covers all 5 parameters with per-parameter descriptions, so the baseline is 3. The description adds a compact semantic layer: filters are optional, startTime/endTime form a window, and limit caps results. This is useful but not a large amount of new per-parameter detail.

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

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

The description opens with a specific verb ('List'), a bounded resource ('appointments'), and scope ('authenticated user's organization'), plus sort order ('most recent start time first'). The field-projection sentence distinguishes it from detail/calendar tools, so an agent can select it without confusion.

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 clearly defines when to use it: for a bounded, sorted page of appointment summaries, with optional filters. It also states what is excluded server-side (notes, reminders, contact details, payments), which is an explicit when-not, though it does not name sibling alternatives like get_appointment or list_calendar_events.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety is covered. The description adds behavioral context about field exclusions (free-text titles, notes, chair ids, etc.), pagination with hasMore, and ordering—all beyond the annotations, which is valuable for an agent.

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

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

The description is compact and front-loaded: it leads with the primary purpose and scope, then lists returns and exclusions, then filters. Every sentence adds value without redundancy.

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 an output schema present, return format is already defined. The description covers scope, ordering, pagination, filtering, and server-side exclusions. For a read-only, non-destructive tool with four optional parameters, this is 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 all parameters are already documented with descriptions. The description reiterates that salonId and time filters are optional, but adds no new semantic details beyond the schema; this matches the baseline 3 for high coverage.

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 specifies the verb 'list', the resource 'non-appointment calendar blocks', the scope 'in the authenticated user's organization', and the ordering 'earliest start time first'. It also distinguishes from siblings by clarifying these blocks explain closures and open periods that appointments cannot reveal.

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 states when to use it: to understand closures and extra-open periods not visible via appointments, and it mentions optional filters (salonId, startTime/endTime). It implies appointments are handled by a different tool (list_appointments) without naming it, which is slightly less explicit than the 5-level benchmark.

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 indicate read-only, idempotent, non-destructive behavior. The description adds valuable behavioral detail: server-side field exclusion, bounded results, the limit cap, and hasMore truncation reporting. No contradictions with 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?

Every sentence contributes meaningful information: what is returned, what is excluded, and how pagination/filtering work. The most important scoping details are front-loaded, and there is 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?

The description is fully sufficient for an agent to select and invoke the tool correctly. It covers the return scope, exclusions, optional filtering, pagination limits, and truncation reporting, and an output schema exists so return-value details are not the description's responsibility.

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 both limit and salonId fully described in the schema. The description restates the default/maximum and filtering behavior but adds no new semantic meaning beyond what the schema already provides.

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 ('List') and resource ('clients'), and further specifies a bounded page within the authenticated user's organization. The scope is precise and the tool is clearly distinguishable from siblings like get_client and list_appointments.

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 clear context: this is for lightweight appointment workflow chaining and intentionally excludes full profile data. It implies that richer client details would come from get_client, though it does not explicitly state when to prefer an alternative.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds valuable operational details: bounded pagination, most-recent-first ordering, server-side exclusion of sensitive data, and hasMore for truncation. No contradiction; these traits go well beyond annotations.

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

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

The description is compact and front-loaded with the core purpose. Each sentence adds distinct information (fields returned, exclusions, filters, pagination) without redundancy or fluff.

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?

The description fully covers what the tool returns, excludes, its ordering, pagination behavior, and operational boundaries. Given the output schema exists, nothing essential is missing for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so each parameter is described. The description adds that filters are optional and clarifies the pagination semantics (hasMore indicates truncation), which is not in the schema. This goes beyond the baseline and provides useful context for interpreting limit and time-window parameters.

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

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

The description states a specific verb ('List') and resource ('payment records'), with a clear scope ('authenticated user's organization'), ordering ('most recent first'), and enumerates the exact fields returned. It also explicitly disclaims any fund-moving capability, distinguishing it from potential payment-mutation 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 explicitly states when to use it (for workflow chaining of payment references) and what it cannot do (charge, refund, transfer), giving clear when-not guidance. It also notes optional filters, providing usage context without naming sibling tools directly.

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?

The description adds substantial behavioral context beyond the readOnly/idempotent annotations: the source route is public, ownership is verified before calling, it fails closed, other organizations' salons are reported as not found, and provider roles are organization-wide. These details could affect an agent's expectations about results and error handling.

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

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

The description is dense but every sentence carries unique value: the core purpose, the auth/ownership behavior, the org-wide scope, the exclusions, and the not-found behavior. It is front-loaded with the primary action and avoids redundancy.

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-only list tool with an output schema, the description covers limit, scope, authorization failure mode, excluded fields, and cross-organization behavior. Nothing material is missing for an agent to decide whether and how to invoke this tool 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 schema already documents salonId with type, pattern, and provenance ('returned by list_salons'). The description reinforces that the salon must be owned by the authenticated organization but does not add new parameter-specific syntax or format details 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?

The description names a specific verb ('List'), a resource ('providers'), and precise scope ('for the organization that owns a known salon') while capping results at 100. It clearly distinguishes the tool's output from sibling tools by noting provider roles are organization-wide and excluding fields like staff ids, contact details, and schedules.

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 appropriate use: when you need provider display names for a salon's parent organization, and the salonId must come from known salons. It explains the authorization prerequisite (salon must belong to the authenticated tenant) but does not explicitly name alternatives or conditions for when not to use this tool.

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

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

Annotations already cover read-only, idempotent, and non-destructive hints. The description adds meaningful behavioral details: bounded paging, most recent ordering, limited fields returned, server-side exclusions, and the hasMore pagination indicator. This goes beyond annotations and gives the agent a clear expectation of 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?

The description is a single, well-structured paragraph that front-loads the core action, then addresses returned fields, exclusions, filters, and pagination. It is efficient with no fluff, though slightly verbose in enumerating exclusions and filters.

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?

The description covers purpose, scope, returned fields, exclusions, filters, and pagination. Since an output schema exists, detailed return values are not necessary. It omits the default limit and error handling, but those are captured in the schema, so the description is largely complete for an agent.

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 input schema provides 100% descriptive coverage for all six parameters. The description merely restates that filters are optional, adding no new semantic meaning beyond what the schema already defines. With full schema coverage, the baseline of 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?

The description clearly states the action (list a bounded page of salon quotes), scope (authenticated user's organization), and ordering (most recent first). It differentiates itself by focusing on salon quotes specifically, but does not explicitly name a sibling to contrast with, so it falls 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?

No explicit guidance on when to use this tool versus alternatives. It implies use for listing quotes and mentions optional filters, but does not state when not to use it or point to a sibling like get_quote or list_appointments for other needs. There is no mention of alternatives or 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 mark the tool as read-only and idempotent, and the description adds meaningful behavioral context beyond that: the 100-salon cap, the specific field subset returned, excluded categories, and the `hasMore` truncation indicator. This gives the agent an accurate model of the operation's 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 tight sentences with no filler. The core action and scope are front-loaded, followed by the field list, exclusions, alternative routing, and truncation behavior—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 zero-parameter, read-only list operation with an output schema, this description is complete. It tells the agent what comes back, what is omitted, when results are truncated, and where to go for deeper detail.

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 relevant context like the result limit and field selection, though there is no parameter-specific semantics needed beyond what the empty schema already confirms.

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'), a bounded resource ('up to 100 HairDora salons'), and the scope ('in the authenticated user's organization'). It also distinguishes itself from get_salon by clarifying that this is a light inventory, not a detailed configuration lookup.

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 tells the agent when to use a sibling: 'call get_salon for one selected salon's operational configuration.' It also defines what this tool is not for by listing excluded fields, so there is no ambiguity between list_salons and get_salon.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds meaningful behavior beyond that: it returns only a subset of fields, excludes internal metadata and organization data server-side, and reports truncation via hasMore. This gives the agent a clear model of the tool's 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?

The description is three sentences with no filler. The main action and scope are front-loaded, followed by field restrictions, filtering, and pagination details. 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?

The tool is simple, has an output schema, and the description covers scope, field filtering, optional filtering, and pagination truncation. Nothing an agent needs to invoke 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 description coverage is 100%, so the schema already documents limit and salonId. The description repeats the limit default/maximum and the optional salonId filter, but adds little new parameter-level meaning beyond what the schema provides.

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

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

The description opens with a specific verb and resource: 'List a bounded page of services offered across the authenticated user's organization.' It also states the exact returned fields, making the tool's scope and resource clear and distinguishable from sibling list_* 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?

The description gives clear context: it lists services across the organization, supports an optional salonId filter, and explains pagination with limit and hasMore. It does not explicitly name alternatives or state when not to use this tool, 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, idempotentHint, and destructiveHint, covering the safety profile. The description adds valuable behavioral context by enumerating what is excluded (client names, contact details, ids, etc.) and by describing the output as aggregate counts and 'safe' previews, which clarifies the scope and privacy guarantees 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?

The description is compact and front-loaded: it states the main purpose first, then what it shows, then what it excludes. Every sentence adds distinct value, with no redundancy or filler. The structure is efficient and easy for an agent to parse.

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 tool with a single parameter and an output schema (which exists, per context), the description covers the essential aspects: what the tool does, what data it returns, what it omits, and where the input comes from. The presence of the output schema means the description does not need to detail return formats. No critical information 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?

The schema already describes salonId and provides a pattern, giving 100% coverage. The description adds the crucial constraint that the id must come from list_salons, which is not in the schema, thereby guiding correct input sourcing. This extra semantic enriches the parameter definition beyond the schema alone.

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 clearly states the tool renders a bounded, tenant-scoped operational overview for a specific salon, listing exactly what aggregates and previews it shows and what it excludes. This distinguishes it from sibling get/list tools like get_salon or list_appointments, which would provide detailed or raw data. The verb 'render' plus the resource and scope make the purpose 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 notes that the salon id should come from list_salons, which is a useful prerequisite. However, it does not explicitly state when to prefer this overview over using individual tools like get_salon or list_appointments, nor when not to use it (e.g., when detailed client data is needed). The guidance is implied rather than explicit.

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