Server Quality Checklist

Tool Scores

• search_catalogB
  3.2/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the full burden. It discloses what it returns ('matching entries with title, kind, owner, and catalog location path'), which adds useful behavioral context. However, it doesn't describe edge cases like no-match behavior, pagination, or rate limits. An output schema exists but the description could still add more detail on result ordering or exactness.

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

  Conciseness4/5

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

  Two sentences, front-loaded with the core verb and resource. Every sentence earns its place: the first states purpose, the second states return shape. Concise and efficient, though it could afford one more sentence for usage guidance.

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

  Completeness3/5

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

  For a two-parameter search tool with a simple output schema, this is reasonably complete. The description covers what it searches, where, and what it returns. Gaps: no clarification on how 'limit' interacts with results, no differentiation from search_collections sibling, and no statement about empty-result behavior. These are minor for a search tool but not entirely insignificant.

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

  Parameters3/5

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

  Schema description coverage is 0%, so the schema itself provides no documentation for 'term' or 'limit'. The description implies 'term' is a search query but doesn't state semantics like case-sensitivity, fuzzy matching, or whether it's a full-text search. However, with only 2 simple parameters and readable names ('term', 'limit'), the baseline burden is modest and the meaning is reasonably inferable.

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

  Purpose4/5

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

  The description uses a specific verb ('Search') plus resource ('the TechZone catalog') and name-checks the specific URL. It lists the searchable categories (environments, collections, products). It's clear what the tool does, though it doesn't explicitly distinguish from the sibling search_collections tool, so it doesn't quite reach a 5.

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

  Usage Guidelines2/5

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

  The description provides no when-to-use guidance or alternatives. Given the sibling tools include search_collections, get_catalog_entry, and get_collection, an agent could confuse which search path to take. No exclusions or context on when to prefer this over search_collections.

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

• whoamiA
  3.5/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the burden. It discloses the primary behavior (token validation and profile retrieval) and lists returned fields, which is reasonable for an identity check. However, it doesn't state whether invalid tokens cause errors, whether this is a safe read operation, or authentication requirements. As a benign, read-only identity tool with no annotations, a 3 is appropriate — adequate but with gaps around error handling and auth behavior.

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

  Conciseness5/5

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

  Two concise sentences, no filler, action-first structure.

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

  Completeness4/5

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

  Given the tool's simplicity (0 params, no nested objects), the description is largely complete. The output schema exists, so return values are structurally documented, and the description supplements by naming the semantic fields. One could argue for more, like invalid-token behavior, but for a parameterless self-identity check, this is near-complete.

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

  Parameters4/5

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

  The tool has 0 parameters, and schema coverage is 100% (trivially, since there are no properties). The description adds value by explaining what the tool returns (profile fields), which is the meaningful semantic content for a parameterless tool. With no parameters to document, the description's job shifts to clarifying the output contract, which it does.

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

  Purpose4/5

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

  The description clearly states the tool validates the TechZone API token and returns the current user's profile with specific fields (name, email, roles, persona, API entitlement). It uses a specific verb ('validates') plus a clear resource ('TechZone API token'), and the output content is enumerated. It doesn't explicitly distinguish from siblings, but there are no overlapping sibling tools that do something similar, so the differentiation is inherent.

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

  Usage Guidelines2/5

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

  The description implies usage as a token validation/identity check, but there is no explicit guidance on when to use it vs alternatives, nor any context about prerequisites (e.g., being authenticated). There's no exclusions or when-not-to-use guidance. The purpose is clear enough that an agent could infer usage, but it leans on implication rather than explicit guidance.

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

• get_catalog_entryA
  4.1/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the safety-profile burden. It doesn't disclose behavioral traits like read-only vs mutation, but 'Get' strongly implies a read operation. It does add the useful detail about how kind/name map to the location path. With no annotations, the behavioral disclosure is minimal but the operation type is evident from the verb.

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

  Conciseness4/5

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

  Two sentences, zero filler. The example (kind='system', name='redhat-openshift') is valuable and front-loaded. Compact and efficient, though a touch more structure or keyword emphasis would make it slightly better.

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

  Completeness4/5

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

  The tool is simple (3 parameters, output schema present, no nested objects), so the completeness bar is modest. The description explains the key derivation logic tying to search_catalog and covers the two required parameters. It doesn't discuss edge cases or return-value caveats, but the output schema covers return expectations. Adequate for the tool's complexity.

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

  Parameters4/5

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

  Schema description coverage is 0%, so the description must compensate. It explains kind and name via the /catalog/{namespace}/{kind}/{name} path, giving meaning to both parameters. It omits the namespace parameter explicitly, though it appears in the path template. This compensates well for the zero coverage, though namespace semantics could be a bit more explicit.

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

  Purpose5/5

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

  Clear specific verb+resource: 'Get one TechZone catalog entry by kind and name'. The description distinguishes it from siblings by clarifying its relationship to search_catalog — the kind/name come from a search_catalog result path. This is precise and easily actionable.

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

  Usage Guidelines4/5

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

  The description explicitly says kind and name come from a search_catalog result's location path, giving context on when/how to use it. However, it doesn't explicitly state when NOT to use it or name alternatives, though siblings like get_collection and get_reservation clearly differ. The derivation hint is useful and fairly clear.

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

• search_collectionsA
  4.1/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the burden. It discloses important behavior (that a result with no platforms is an umbrella collection and not reservable) which is genuinely useful behavioral context beyond schema. However, it doesn't disclose return format, pagination behavior, or rate limits. Given zero annotations, the description partially compensates but leaves behavioral gaps.

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

  Conciseness4/5

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

  The description is compact (about 50 words) and front-loaded with the core purpose in the first sentence. The workflow guidance and differentiation are valuable additions with no wasted wording. Slightly verbose in the middle section with the parenthetical, but overall efficient.

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

  Completeness4/5

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

  The tool is a search function with 3 parameters, moderate complexity, and an output schema present. The description covers the key workflow context, distinguishes from the sibling search tool, and warns about umbrella collections. It doesn't detail the output fields, but an output schema exists which reduces that burden. Fairly complete for a search tool.

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

  Parameters3/5

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

  Schema description coverage is 0%, but the parameters are fairly self-descriptive from their names and defaults (term, limit, include_retired with defaults stated in the schema). The description does not add any parameter-specific semantics beyond the schema. Baseline 3 applies since the schema is the primary source and names are reasonably clear, but the description misses the opportunity to clarify terms like term matching behavior or effect of include_retired.

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

  Purpose5/5

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

  The description states a specific verb+resource ('Search reservable TechZone collections by name') and clearly distinguishes from the sibling tool search_catalog by naming it explicitly and contrasting the separate Backstage deployer catalog. It also describes the precise workflow (pick result, inspect, reserve), showing exactly what the tool returns and its role.

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

  Usage Guidelines5/5

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

  Provides explicit when-to-use guidance (finding something to reserve), a step-by-step workflow (inspect with get_collection, check for platforms, then create_reservation), and explicitly distinguishes from the alternative search_catalog. This is exemplary usage guidance.

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

• check_expiringA
  4.2/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the burden. It discloses the default window behavior and exclusion criteria, which is useful. However, it doesn't add much beyond the obvious read-only nature implied by 'flag'/list semantics, and doesn't detail the output shape beyond hoursRemaining. Adequate but not rich.

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

  Conciseness5/5

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

  Three concise sentences, each earning its place: what it does, the default behavior, the use case, and the exclusion. Zero waste and front-loaded with the core action.

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

  Completeness4/5

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

  Has an output schema (which explains return values), a single simple parameter, and no annotations needed for a read-only flagging tool. The description covers the window, ordering, countdown field, and exclusions. Reasonably complete given the low complexity; could mention whether it requires prior list context, but that's minor.

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

  Parameters4/5

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

  Schema coverage is 0%, so the description must compensate for the single 'days' parameter. It does explain the parameter's effect ('within the next N days, default 3'), which covers what matters. Description fully compensates for the coverage gap on this simple parameter.

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

  Purpose5/5

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

  Specific verb+resource: 'Flag active reservations ending within the next N days.' Clearly distinguishes from siblings like list_reservations and get_reservation by its time-based expiry focus, and states the output ordering (soonest first) and countdown field (hoursRemaining).

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

  Usage Guidelines4/5

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

  Gives an explicit use-case question ('is anything about to expire?') and explicitly states what's excluded (deleted/expired reservations). It doesn't name a specific alternative tool for the when-not case, but the positive use-case is clear enough to guide selection.

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

• create_reservationA
  4.2/5.0
  Behavior4/5

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

  No annotations are provided, so the description carries the full burden of behavioral disclosure - and it does so well. It discloses that this is a state-changing operation consuming real capacity, explains default behaviors (template/region default to first available, start defaults to now, days defaults to 2 and may be policy-capped), and specifies the return value and follow-up polling. It's strong given zero annotation support, though it could mention idempotency or permission/authentication requirements.

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

  Conciseness4/5

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

  The description is genuinely dense but compact - a single paragraph that front-loads the critical side-effect warning before anything else. Every sentence adds value: safety warning, prerequisite validation, parameter defaults, and post-call behavior. Slightly long but warranted given the state-changing nature and 8 parameters; the warning is appropriately first.

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

  Completeness4/5

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

  For a complex mutation tool with 8 parameters, 0% schema coverage, and no annotations, the description is thorough. It covers prerequisites (reservable vs umbrella collection), all default behaviors, the success return, and the verification workflow (poll get_reservation). An output schema exists, so return details are partly covered there. It doesn't address error conditions or what happens on failure, leaving a small gap for a state-changing tool.

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

  Parameters4/5

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

  Schema description coverage is 0%, so the description must compensate, and it substantially does. It explains the meaning and data sources for template (deployment variant), region_name (region), start (ISO timestamp), and days (duration/cap). It doesn't explain collection_id, name, purpose, or description in depth, but since collection_id/name are self-evident and tied to required fields, this is a solid compensation for the 0% schema coverage.

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

  Purpose4/5

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

  The description clearly states the tool creates a reservation from a collection, with a specific verb (create), resource (reservation), and source (collection). It distinguishes from siblings like list_reservations and get_reservation by making the mutating/write nature explicit. However, the purpose is somewhat intertwined with behavioral caveats rather than being a crisp standalone purpose statement.

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

  Usage Guidelines5/5

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

  Excellent when/when-not guidance: explicitly warns it changes state and consumes real capacity, instructs to always confirm collection/name/region/duration with the user first. Also differentiates from alternatives by noting get_collection is the upstream source and get_reservation is the downstream poll target. This is clear usage context with explicit exclusions (umbrella collections are called out).

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

• get_collectionA
  4.3/5.0
  Behavior3/5

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

  With no annotations provided, the description carries full behavioral burden but only mentions it's a consultative read operation (get, consult). It doesn't disclose whether it returns all platforms/regions or paginates, nor what happens with invalid collection IDs. It's clearly read-only from the verb, but richer context on return shape or failure modes is missing.

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

  Conciseness4/5

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

  Two focused sentences with no wasted words. The first sentence establishes purpose and scope, the second gives usage guidance. Front-loaded and efficient. Minor deduction because the parenthetical listing of outputs (platforms, regions, datacenters, templates) could arguably be trimmed, but overall it's tight.

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

  Completeness4/5

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

  Given only 1 parameter, no annotations, and presence of an output schema that presumably documents the returned deployment options, the description is fairly complete. It explains what data is returned, where the ID comes from, and how to chain it with create_reservation. The main gap is not describing response structure, though the output schema mitigates this.

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

  Parameters4/5

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

  Schema coverage is 0%, so the parameter 'collection_id' is entirely undocumented by the schema ($ref-like plain string with no description). The description compensates meaningfully by explaining the parameter's source ('from a catalog entry or a reservation's collectionId'), giving the agent concrete provenance for where to obtain the ID. It doesn't specify format or type constraints, but the provenance guidance is strong.

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

  Purpose5/5

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

  The description has a specific verb+resource ('Get a TechZone collection's deployment options') and clarifies scope (platforms, regions, datacenters, templates). It distinguishes itself from siblings by specifying the collection_id source ('from a catalog entry or a reservation's collectionId'), which differentiates it from get_catalog_entry and get_reservation.

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

  Usage Guidelines5/5

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

  Explicitly states when to use it: 'Consult this before create_reservation to pick a region.' This provides clear prerequisite guidance and order-of-operations context. It names a specific alternative action (create_reservation) that should follow this call.

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

• cancel_reservationA
  4.6/5.0
  Behavior4/5

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

  No annotations are provided, so the description carries the full burden of behavioral disclosure. It explicitly flags the operation as DESTRUCTIVE and IRREVERSIBLE, warns to confirm with the user, and discloses the refusal-if-mismatch behavior. It does not describe what happens to dependent resources beyond 'its environment' or return-value behavior, but for a cancellation tool the core destructive contract is well disclosed.

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

  Conciseness5/5

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

  Three dense sentences with zero waste. The destructive warning (ALL CAPS) is front-loaded, the confirmation requirement and name-match rule are delivered precisely. Every sentence earns its place.

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

  Completeness4/5

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

  For a destructive 2-param tool with an output schema, this description is nearly complete. It covers the critical destructive nature, the confirmation requirement, the confirm_name constraint, and refusal behavior. It could arguably mention what the returned output indicates, but the output schema exists to cover that. Sibling differentiation is implicitly clear via the destructive framing.

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

  Parameters4/5

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

  Schema description coverage is 0%, so the description must compensate. The description explains the semantic role of confirm_name (must equal the reservation's exact name from list_reservations, refused if mismatched). It does not elaborate on reservation_id's source or format, but the description gives enough context that the agent can reasonably infer it comes from list_reservations/get_reservation.

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

  Purpose5/5

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

  Description states a specific verb ('Cancel (delete)') and resource ('a TechZone reservation and its environment'), clearly distinguishing from siblings like extend_reservation, get_reservation, and list_reservations. The destructive scope (reservation AND its environment) is explicit, making the tool's purpose unambiguous.

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

  Usage Guidelines5/5

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

  The description explicitly states when a pre-condition applies ('always confirm with the user first'), and documents the required confirmation behavior. It clearly explains that confirm_name must match the reservation's exact name from list_reservations, giving the agent actionable guidance on correct usage and the refusal behavior.

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

• list_reservationsA
  4.6/5.0
  Behavior4/5

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

  No annotations are provided, so the description carries the full burden of behavioral disclosure. It makes no claims about destructiveness or read-only nature (the listing implies read-only), and it clearly discloses what is NOT returned (credentials). It doesn't mention pagination or limits for a list operation, but the coverage of inclusions/exclusions is solid. The explicit credential exclusion is valuable transparency.

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

  Conciseness5/5

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

  Two sentences, zero waste. The first sentence lists what's returned with example status values; the second sentence covers the crucial exclusion and redirects to the sibling tool. Every word earns its place.

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

  Completeness4/5

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

  The tool is simple (0 params) and has both an output schema and clear sibling context. The description fully covers what the list contains and explicitly excludes, and redirects to get_reservation for deeper detail. Minor gap: no mention of sorting, filtering, or volume limits, but for a parameterless list tool with an output schema, this is adequate.

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

  Parameters4/5

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

  The tool has zero parameters (0% of schema to document), so the baseline is 4. The description does not need to elaborate on parameters since there are none. The description instead focuses on what the output contains, which is appropriate for a parameterless list tool.

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

  Purpose5/5

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

  The description is specific: 'List all of my TechZone reservations' with a clear enumeration of included fields (name, status, environment, region, dates) and even lists example statuses. It also explicitly contrasts against the sibling get_reservation tool, distinguishing its scope. This is a strong, specific verb+resource statement.

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

  Usage Guidelines5/5

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

  The description explicitly states when NOT to use this tool ('Credentials are never included here - use get_reservation for full details on one reservation'), naming the alternative. This directly addresses the sibling relationship with get_reservation and defines clear usage boundaries.

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

• extend_reservationA
  4.8/5.0
  Behavior5/5

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

  Explicitly discloses that 'THIS CHANGES STATE on TechZone', which is a critical behavioral trait. It also documents all possible return outcomes (extended, not_extendable, rejected, ambiguous) with explanations of what each means. Despite no annotations present, the description fully carries the transparency burden with actionable detail.

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

  Conciseness4/5

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

  Compact, front-loaded with the primary action in the first clause. The human-confirmation warning is prominent. The outcome enumeration is useful but slightly verbose; could be trimmed slightly. Overall well-structured and every sentence carries weight.

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

  Completeness5/5

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

  For a state-changing mutation tool with no annotations and no schema descriptions, this is highly complete. It covers the return contract via output schema/outcomes, explains side effects (state change), warns about destructive behavior, and describes each possible outcome including the 'ambiguous' edge case. Excellent coverage.

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

  Parameters4/5

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

  Schema coverage is 0% and there are only 2 params. The description adds meaning for 'days' (defaults to 1, extends 'past its current provisionUntil'). reservation_id is self-explanatory as a string identifier. Description doesn't describe format/validation for reservation_id, but the behavior of each param is reasonably covered.

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

  Purpose5/5

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

  Specific verb+resource+action: 'Extend a TechZone reservation's end date by N days' clearly states what it does. Distinguishes from siblings (get_reservation, cancel_reservation, create_reservation) by the specific action of extending end dates.

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

  Usage Guidelines5/5

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

  Explicitly states when to use (extend reservation) and provides clear behavioral guidance - ALWAYS confirm with user before calling, specifying what to confirm (reservation name + days). This is a strong usage directive that goes beyond typical tool descriptions.

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

• get_reservationA
  4.9/5.0
  Behavior5/5

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

  Critically, the description discloses that 'output may contain environment credentials' and applies a conditional call restriction ('only call this when the user asks about a specific reservation') to guard against unnecessary credential exposure. Since no annotations are provided, the description carries the full burden, and it meets it exceptionally well by flagging the sensitive-credential behavior.

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

  Conciseness5/5

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

  Two sentences, zero waste. Front-loads the core purpose, enumerates the returned content categories, then delivers the critical security caveat and usage condition. Every sentence earns its place.

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

  Completeness5/5

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

  For a single-parameter lookup tool with an output schema present, the description is complete. It specifies what details are returned (service links, access details, lifecycle dates, extension count), flags credential exposure risk, and gives the call condition. The output schema covers return structure, so no further return documentation is needed.

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

  Parameters4/5

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

  Schema coverage is 0%, so the description must compensate. It explains the source of the id ('from list_reservations') — a key semantic detail beyond merely naming the field. While it doesn't describe the id's format/type beyond schema, the sourcing context is the most valuable semantic addition. Slightly below 5 because it doesn't note what makes a valid id beyond 'id from list_reservations'.

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

  Purpose5/5

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

  Clear specific verb+resource: 'get full details for one reservation by its id'. Explicitly notes the source of the id (from list_reservations), distinguishes from siblings like list_reservations (plural/bulk vs single). The scope is precise and unambiguous.

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

  Usage Guidelines5/5

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

  Explicitly states when NOT to call: 'only call this when the user asks about a specific reservation'. The 'from list_reservations' instruction provides a clear prerequisite/source for the id. This gives strong usage guidance relative to the sibling list_reservations tool.

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