Nomad Stays

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

Goes well beyond the annotations by disclosing server-side price/availability re-validation, rejection behavior for stale quotes, the out-of-band payment model (member opens checkoutUrl in their own browser; no card details pass through), and the required NOMADSTAYS_MCP_AGENT_TOKEN 'bookings' scope. This is exactly the behavioral context annotations readOnlyHint/destructiveHint cannot 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?

Front-loads purpose in the first clause, then layers prerequisite, failure handling, and the payment hand-off rule. Every sentence carries distinct, actionable 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 tool with no output schema, the description still explains the return (hosted checkoutUrl) and the full lifecycle: quote → re-validate → create → hand off to member. Auth scope, error path, and payment constraints are all covered, leaving no operational gap.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters including defaults for contactName/contactEmail. The description reinforces that quoteId is the driving input but adds no new format, constraint, or example meaning beyond the schema, warranting the baseline 3.

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 ('Create a real booking from a quoteId') and the return value ('hosted checkoutUrl'), and names the sibling quoteStayBooking as the source of the required input. An agent can distinguish this from quoteStayBooking and the many create* application siblings 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?

Explicitly defines the prerequisite (a quoteId from quoteStayBooking), the failure path for stale/expired quotes ('call quoteStayBooking again'), and the mandatory post-call action (send the checkoutUrl to the member for them to pay). The when-to-use flow is fully specified with no ambiguity.

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 destructive=true, idempotent=false and readOnly=false, but the description adds far more: cancellation cannot be undone online, refund/credit lands in the wallet automatically, Custom policy ('request') only emails a request and leaves the booking active, and all three parties are emailed. It also names the required 'bookings' scope, which no annotation conveys.

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?

Front-loaded with the action, then preconditions, then consequences, then the policy exception, then scope — a logical reading order with no filler. It is dense at five sentences, but nearly every clause carries behaviorally load-bearing 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 destructive three-parameter mutation with no output schema, the description covers preconditions, irreversibility, financial outcome, the divergent 'request' path, notification side effects, and authorization scope. Nothing an agent needs to call it safely 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 pnr, reason and confirm are already documented, and the description largely restates confirm: true. It adds marginal context by framing confirm as a consent gate tied to the member's explicit statement, but adds nothing about reason or pnr 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 precise verb and resource scoped to "one of the caller's own paid Stay bookings under the Stay's cancellation policy", which is unmistakably distinct from the read-only getCancellationOptions and listMyBookings siblings. An agent knows exactly what object is affected and under what governing rules.

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 gating sequence: only call after getCancellationOptions returned canCancel: true, after relaying message and onCancel text to the member, and after the member explicitly agreed, with confirm: true required. The alternative/read tool is named and the precondition that routes to it is stated.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds only that it returns availability status and room details; it says nothing about rate limits, whether availability is real-time or cached, or what happens on invalid dates. Adequate given the annotation coverage, 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.

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

Two sentences, no filler, and the core action is front-loaded before the return-value note. 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 (4 flat params, no nested objects), and the description covers purpose and the gist of the response in lieu of an output schema. However, it omits the one thing an agent most needs here: how this differs from the other availability siblings, which is the main remaining ambiguity.

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% — every parameter, including roomType being optional and the ISO date format, is documented in the schema. The description adds no format, constraint, or default information 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+resource ('check if a specific stay is available') plus the required inputs and the return payload. It is clear on its own, but it never distinguishes itself from the many sibling availability tools (getRoomAvailability, findNearestAvailability, hasAvailabilityInWindow, getAvailabilityByMonth), so an agent cannot tell which of them to pick from this text 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?

No when-to-use or when-not-to-use guidance is given, and no alternative is named. The sibling list contains at least four other availability-checking tools, so the absence of routing guidance is a real gap rather than a minor omission.

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 only declare the generic mutation profile (readOnly=false, destructive=false, openWorld=false), but the description adds substantial context: no VAT/tourism-number/business-model rules, no application fee, no billing step at all, and the auth requirement (NOMADSTAYS_MCP_AGENT_TOKEN). This is exactly the behavioral disclosure annotations do not carry.

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?

Front-loaded with the core action, then the differentiators, then the prerequisite and token requirement. No filler, though the single long paragraph could be split for scanability.

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 mutation tool with no output schema and 8 loosely-specified params, the description covers workflow, prerequisites and auth. It stops short of explaining what the call returns or how the save/submit siblings fit, which an agent would still need to reason out.

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

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

Schema description coverage is only 13%, so the description must compensate. It names and prioritizes five fields (coworkingName, applicantName, applicantEmail, city, country) and clarifies the country format, but leaves address, website and telephone unaddressed and does not explain the required-vs-optional mismatch (all 8 params are non-required in schema yet described as needed for submit).

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 ('Start a new Coworking Application for the caller') and explicitly contrasts itself with the Stay/Experience application siblings, saying it is 'Much simpler'. An agent can separate this from createStayApplication and createExperienceApplication without opening 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?

Gives a concrete prerequisite ('Call getCountryOptions first') and describes the intended workflow (once the five key fields are present, nextAction goes straight to 'submit'). No explicit when-not-to-use or pointer to saveCoworkingApplication/submitCoworkingApplication siblings, which would be needed for 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?

Goes well beyond the annotations (which only say non-read-only, non-destructive, closed-world): discloses server-side country-specific rule enforcement, that rejections name the specific field/reason, the 4-day minimum, profile-based name defaulting, and the required NOMADSTAYS_MCP_AGENT_TOKEN. This is exactly the behavioral context annotations cannot carry.

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 dense paragraph, front-loaded with the action, then workflow, then constraints, then auth requirement. Every clause conveys actionable 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 28-param, all-optional create tool with no output schema, the description covers purpose, prerequisite resolution, server-side validations, and auth. The only minor gap is that it never indicates what the successful call returns (e.g., an application ID) that a subsequent save would need.

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

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

With 28 parameters and only 36% schema coverage, the description compensates meaningfully by linking experienceCountryId/postalCountryId/businessModelId to their resolver tools and explaining the VAT/tourism/business-model constraints. It adds cross-parameter semantics, though many remaining fields (maxPax, website, comments, facilities) are left to their bare names.

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

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

States a specific verb+resource ('Start a new Experience Application') and immediately positions it against the sibling saveExperienceApplication and siblings like createStayApplication/createCoworkingApplication. An agent knows exactly what this creates.

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?

Explicit workflow ordering: call getCountryOptions and getBusinessModelOptions first to resolve the ID params, and the relationship to saveExperienceApplication for later field completion is spelled out. This is when-to-use guidance with concrete prerequisites rather than implied usage.

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 the safety profile (readOnly=false, destructive=false, openWorld=false), and the description adds substantial non-obvious behavior: server-side country-specific rule enforcement, rejections that name the offending field, profile-based name defaulting, and the required NOMADSTAYS_MCP_AGENT_TOKEN. The main gap is that no output schema exists and the description never says what a successful call returns.

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?

Front-loaded with the action, then prerequisites, then behavioral caveats, in a tight sequence with no filler. It is dense but every clause adds actionable information, so length is justified rather than padded.

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 24-parameter, zero-required tool with no output schema, this covers prerequisites, defaulting, validation behavior, and auth, which is the important surface area. It omits the approval/submission lifecycle (that submitStayApplication is the eventual finalizer) and any statement of what the call returns, which are meaningful gaps at this parameter count.

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

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

Schema description coverage is only 33% against 24 parameters, so the description carries a heavy burden. It clarifies the country/model ID resolution path and the applicant-name defaulting, but roughly two-thirds of the parameters (zip, mobile, website, hasKitchen, downloadSpeed, workFacilities, laundryFacilities, etc.) are explained in neither place.

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 ('Start a new Stay Application for the caller'), clearly differentiating it from the save/submit/read siblings in the same family. It does not explicitly contrast itself with createCoworkingApplication or createExperienceApplication, but the 'Stay' qualifier plus the draft-creating framing make the scope 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?

Gives real operational guidance: call getCountryOptions and getBusinessModelOptions first, and use saveStayApplication later for incremental filling. It stops short of stating when NOT to use it (e.g., that submitStayApplication must follow to finalize), so the lifecycle guidance is implied rather than complete.

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 only declare readOnly=false, openWorld=true, destructive=false; the description goes well beyond them by disclosing the downstream workflow (enquiry routed to the Nomad Stays team, availability checked, email reply within one working day), the auth requirement ('bookings' scope), and the fact that member identity is supplied by the account.

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?

Front-loaded with the core purpose and trigger, and each sentence adds a distinct instruction (workflow, identity, consent, alternative). It is slightly long, but no sentence is filler except perhaps the redundant timing 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 4-parameter mutation with no output schema, the description covers trigger, routing, downstream outcome, identity handling, and required scope. An agent has everything needed to decide and invoke 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 the baseline is 3, but the description adds real meaning: it tells the agent what to put in 'message' (who is travelling, work needs, questions) and that name/email must not be collected. It says nothing extra about nights or arrivalDate 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 ('Send an enquiry about a Stay that can't be booked right now') and immediately scopes the trigger condition. It explicitly distinguishes itself from bookStay and quoteStayBooking, so an agent can route correctly 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?

Gives explicit when-to-use conditions (quoteStayBooking finds no bookable package, or the Stay page says it isn't bookable online) and an explicit when-not-to-use rule ('Use bookStay instead whenever a quote succeeds'). It also adds a consent guardrail ('Only send an enquiry the member has asked for').

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 the safe-create profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the description's job is to add context. It contributes the auth requirement (agent token scoped to the owning account), which is genuinely beyond the annotations. It says nothing about idempotency, duplicate-name behavior, or what the call returns, so it adds one useful fact but not rich behavioral 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?

Two sentences, zero filler, and the core action is front-loaded ahead of the conditional detail. Nothing is repeated from 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?

For a 12-parameter mutation relying on a 100%-covered schema plus annotations, the description covers purpose and auth adequately. The one real gap is that no output schema exists and the description never says what comes back (e.g. the new package id), which an agent chaining into updateStayPackage would want.

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 schema is unusually rich — it already explains the tier enum, the buyPrice/sellPrice derivation, and the currency/room prerequisites. The description's 'optionally with initial price tiers' merely restates the prices parameter. Baseline 3 is correct here since the schema does all the heavy lifting.

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: 'Create a new pricing package on a Stay', with a secondary clause covering the optional tiers. The verb 'Create' separates it cleanly from the sibling updateStayPackage and deleteStayPackage without needing to name them. Slightly short of a 5 because it never acknowledges those siblings or the getMyStayPackages read path.

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 one prerequisite ('Requires an MCP agent token scoped to the owning account') and notes the tiers are optional, which is useful context for invocation. However it offers no when-to-use/when-not guidance and never points at updateStayPackage for modifying an existing package. Usage is implied by the verb 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 flag this as a non-read-only, non-destructive write, and the description adds substantial context beyond that: the Boutique-stay 6-room cap with rejection-once-full behavior, the 'one per Boutique1-6 slot' assignment rule, and an auth requirement ('MCP agent token scoped to the owning account'). These are exactly the operational constraints annotations cannot express.

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

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

Four tight sentences, front-loaded with the core action before prerequisites and constraints. Every sentence carries load (prerequisite calls, capacity cap, auth), though the density is right at the edge of what a single paragraph can hold cleanly.

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 mutation tool with no output schema, the description covers the action, prerequisite tool calls, server-side edge cases (boutique slot auto-assignment, 6-room cap), and authorization scope. An agent has everything needed to invoke it correctly without further inference.

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 parameters are already fully documented in the schema (including boutique-specific behavior for roomTypeFK and mcpRoomId). The description adds the source tools for the FK values, but does not add syntax or meaning beyond what the schema already provides, so the baseline of 3 is correct.

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

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

States a specific verb and resource: 'Create a new room on a Stay', which cleanly separates it from the updateStayRoom/deleteStayRoom siblings by inherent verb contrast. However it never names those siblings or otherwise explicitly routes the agent away from them, so it falls short of full sibling differentiation.

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 concrete prerequisites — call getRoomTypeOptions(stayId) and getRoomFacilityOptions() first to obtain valid FK values — which is actionable when-to-use guidance. It lacks an explicit statement of when NOT to use it (e.g., use updateStayRoom to modify an existing room), so no exclusions are 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 destructiveHint=true and readOnlyHint=false, so the destructive nature is covered. The description adds value beyond that: the authentication requirement (NOMADSTAYS_MCP_AGENT_TOKEN) and the mandatory discovery step before deletion. It stops short of saying whether deletion is reversible or what happens on a bad fileName, but it meaningfully extends the annotation set.

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, zero filler, and the destructive action plus its prerequisite are front-loaded. Every clause 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 destructive 4-parameter tool with full schema coverage, annotations covering safety, and no output schema needed, the description supplies the two things structured data cannot: the auth requirement and the correct call order. Adequate and self-contained.

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%, with roomArea's photos/workspace distinction and the fileName provenance already documented in the schema itself. The description's mention that fileName comes from getMyStayRooms largely restates the schema text, 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 with clear scope: 'Delete one photo from a room's gallery.' The room-vs-stay boundary is implied but never contrasted with the sibling deleteStayPhoto, so an agent must infer which one applies. Clear, but no explicit sibling differentiation.

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 prerequisite workflow (call getMyStayRooms first to obtain the exact fileName), which is real ordering guidance rather than inference. It does not state when-not to use it or contrast with deleteStayPhoto, but the positive guidance is concrete and actionable.

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 destructiveHint=true, but the description adds material detail beyond them: the deletion is permanent, it cascades to all price tiers, it is a hard delete unlike the soft room deletion, and it requires an MCP agent token scoped to the owning account. That is exactly the extra context an agent needs before an irreversible mutation.

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 with zero filler; the destructive nature is front-loaded, then the cascade scope, then the auth requirement. Every sentence carries information the agent needs.

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 two-param mutation with no output schema and annotations covering the safety profile, the description covers the irreversible nature, cascade side effects, and auth requirement. Nothing needed 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?

Both parameters are fully documented in the schema (100% coverage) with their EntryID semantics, so the schema does the heavy lifting. The description adds no further detail about packageId format, lookup, or validation, making this a baseline 3.

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 ('Permanently delete a pricing package') and names the cascade target ('all its price tiers') from a Stay. An agent can distinguish it from createStayPackage/updateStayPackage 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?

Gives clear context for choosing this tool ('Permanently delete', only when hard removal is intended) and contrasts it with room deletion, which is soft. It stops short of naming an explicit alternative for reversible changes or stating preconditions like package ownership beyond the token requirement.

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 destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds value beyond them by disclosing the required auth token (NOMADSTAYS_MCP_AGENT_TOKEN) and the single-file deletion scope. It does not state whether the deletion is permanent or recoverable, which would have earned 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?

Three short sentences, front-loaded with the action, then the prerequisite, then the auth requirement. No filler or redundant restatement of schema content.

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

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

For a 3-parameter destructive write with no output schema, the description plus annotations cover action, scope, prerequisite lookup, and auth. Coverage is strong; only the irreversibility/consequence of the deletion 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 each parameter is already documented, including fileName's provenance and the area enum's room-photo exclusion. The description's instruction to obtain fileName via getMyStayPhotos is a workflow aid rather than new per-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 specific verb and resource with a clear scope constraint: 'Delete one photo from a Stay.' An agent can tell this deletes a single photo rather than reordering or uploading. However, it never names its nearest siblings (deleteRoomPhoto, reorderStayPhotos, uploadStayPhoto) to sharpen the boundary, 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?

Gives an explicit prerequisite workflow: 'Call getMyStayPhotos first to find the exact fileName.' That reliably routes the agent through the right discovery call before invoking this tool. It stops short of stating when NOT to use it — the room-photo exclusion lives only in the schema's enum description.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description still adds genuine value by disclosing that the delete is a SOFT delete (implying the record may be recoverable rather than purged) and naming the auth scope required. It stops short of saying whether the action is reversible or what it cascades to.

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 zero filler, and the soft-delete qualifier is front-loaded right after the verb where it matters most.

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 destructive mutation this is nearly complete: the annotations carry the safety signal, both params are fully documented, and the description supplies the soft-delete nuance and auth requirement. It omits downstream effects (e.g. impact on bookings or photos tied to the room), which would have rounded it out.

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

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

Schema coverage is 100% and both parameters are already documented, including the pointer to getMyStayRooms for roomId. The description adds no parameter-level meaning 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 ('Delete (soft-delete) a room from a Stay'), and the 'from a Stay' scoping plus the room/photo distinction separates it from siblings like deleteRoomPhoto and deleteStayPhoto. An agent can pick this tool 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?

It gives a prerequisite ('Requires an MCP agent token scoped to the owning account'), which is real usage context, but offers no when-to-use vs when-not guidance or any named alternative. Usage is only implied by the destructive verb.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that – it searches a window and may adjust length of stay – which is non-obvious for a read query, though it doesn't state the return 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?

Two sentences, front-loaded with the core purpose and followed by the mechanism. No filler; every clause 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 read-only tool with a fully documented schema and no output schema, the description covers purpose, trigger condition, and search behavior adequately. The one gap is that it doesn't hint at what is returned (e.g., candidate dates and adjusted stays), which the absent output schema leaves 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 all five parameters are already documented, including the default 90-day window and ISO date format. The description adds no syntax or format detail beyond the schema, so 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?

States a specific verb+resource: finding nearest available dates and searching alternative check-in dates with LOS adjustment. It is clearly a fallback/alternative-finder distinct from simple availability checks, but it doesn't explicitly name siblings like checkStayAvailability or hasAvailabilityInWindow to sharpen the distinction.

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

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

Gives a clear triggering condition: 'when requested dates are not available.' This tells the agent when to reach for it, but it names no alternatives or exclusions, so the agent must infer that direct availability checks are a separate 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 declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely non-obvious context beyond that: the values are lookup IDs, not booleans, and a NOMADSTAYS_MCP_AGENT_TOKEN is required. It stops short of describing the shape or size of the returned list, which is the remaining gap.

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 zero filler. The resource enumeration is front-loaded, the boolean-vs-lookup warning comes before the usage instruction, and the auth requirement is a single trailing clause.

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-enum, read-only lookup with no output schema, the description supplies enough: purpose, values-not-booleans warning, downstream usage, and an auth prerequisite. The only omission is how the returned options are structured (e.g. id/label pairs), which would help an agent map a name to a writable ID.

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 an enum, so the baseline is 3; the description earns extra by explaining what the values mean semantically (lookup IDs such as 'Yes', 'No', 'On Request') and why the enum choice matters for the downstream writes. It does not restate the enum itself, which is correct.

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

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

The description names the specific verb (list valid values) and resource (Additional Information picklists: Children Allowed, Pets Allowed, Parking), and ties itself to the updateStayOrganisationalData workflow. An agent can distinguish it from siblings like getRoomTypeOptions or getCountryOptions 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?

It explicitly prescribes the moment of use: 'call this to find the right value before writing petsAllowedId/childrenAllowedId/parkingId', naming the dependent tool and the exact fields it feeds. This is a clear when-to-call rule with an implied alternative (do not guess a value).

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds no behavioral context beyond that — nothing about result size, ordering, caching, or stability of the reference list. The grouping detail is structural rather than behavioral.

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 with no filler; the grouping is stated before the internal table names, so an agent gets the useful part first. Nothing can be cut without losing 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?

No output schema exists, so the description carries the burden of describing returns, and it does disclose that results are grouped into Stay Amenities and Room Amenities. It is less clear about the actual item shape (whether each amenity carries an ID usable in updateStayFacilities or getStaysByAmenities), which is the one remaining gap for a lookup tool this simple.

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

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

The tool takes zero parameters, so the baseline of 4 applies. The description correctly adds no parameter information and instead spends its words on the shape of 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 (all possible amenities), and goes further by naming the two groups the result is split into. It implicitly differentiates itself from the narrower sibling getRoomAmenities by covering both stay and room amenities, though it 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?

Usage is only implied: the description suggests this is the full reference catalog, which an agent would use to discover valid amenity values before filtering or updating. There is no explicit when-to-use, no prerequisites, and no alternative tool named (getRoomAmenities, getRoomFacilityOptions, getFacilityGroups all overlap partially).

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the useful 'active only' filtering qualifier, but says nothing about ordering, return shape, or whether categories can be empty — modest added value beyond the structured fields.

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 purpose stated first and the routing guidance second. Every clause 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 no-arg, read-only enumeration with no output schema, the description covers purpose, scope, and usage sufficiently. The only minor gap is not characterizing the returned category list (e.g., name/identifier fields), which an agent might want.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain; the baseline for a no-arg tool applies. Nothing in the description misleads about inputs.

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 ('Returns all active lifestyle/genre categories') with an explicit scope qualifier ('available in NomadStays'). It is clearly distinguishable from the sibling getStaysByLifestyle, which it names directly.

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 states when to use it ('to discover what lifestyle categories exist') and the condition that follows ('before searching with getStaysByLifestyle'), naming the exact alternative tool. Nothing about routing is left to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful return-shape context ('all possible check-in dates and their corresponding available periods'), but says nothing about pagination, date formats, or behavior when no windows qualify.

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 core purpose and followed by the return shape; no filler. The second sentence is slightly redundant with the first but still earns its place by clarifying output.

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 four-parameter read tool with full schema coverage and safety annotations, the description covers purpose and rough output but omits sibling routing, error/empty-result behavior, and any date-format expectations. It is adequate but leaves clear gaps for an agent choosing among the many availability tools.

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

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

Schema description coverage is 100% and each of the four required parameters (year, month, stayId, minLengthOfStay) is documented in the schema with examples and ranges. The description only alludes to minLengthOfStay and month, adding no format or constraint detail beyond the schema, so the baseline 3 applies.

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

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

The description states a specific verb (Get), resource (available booking windows), and scope (a specific month filtered by minimum length of stay), which is concrete and actionable. It does not, however, distinguish itself from close siblings such as getRoomAvailability, checkStayAvailability, hasAvailabilityInWindow, or findNearestAvailability.

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

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

There is no when-to-use guidance and no mention of alternatives, despite several overlapping availability siblings (checkStayAvailability, hasAvailabilityInWindow, findNearestAvailability, getRoomAvailability). The 'minimum length of stay' constraint is the only implicit selection signal.

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?

Adds substantial behavior beyond the annotations: status is re-verified live against Airwallex when not already confirmed paid, results are tenant-scoped to the caller's own account, and a specific token with the 'bookings' scope is required. These are exactly the freshness, authorization, and data-isolation facts an agent needs and that readOnlyHint does 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 tight sentences, front-loaded with the action and key, followed by the freshness guarantee and the auth/scope constraints. No filler or restated 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 single-parameter read with no output schema and annotations already covering the safety profile, the description covers the remaining unknowns: freshness of the result, tenant isolation, and the required credential/scope. 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?

Schema description coverage is 100%, and the pnr description already maps to its source ('returned by bookStay'). The tool description adds only 'by PNR', so it does not meaningfully extend 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 ('Check a Stay booking's real payment status by PNR') and adds a scoping qualifier ('real payment status') that distinguishes it from sibling status-like tools such as getPurchaseStatus and listMyBookings. An agent can identify the target record type and the required key 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?

Gives clear framing for use ('never trust a client-supplied claim of success', implying it should be called to verify after booking) but does not explicitly name an alternative tool or a when-not condition. Context is clear without exclusions, which caps this at 4.

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/non-destructive, so the bar is lower, yet the description adds real value: it discloses the required NOMADSTAYS_MCP_AGENT_TOKEN credential and clarifies the field is read-only and cannot be edited via MCP or host UI. It doesn't cover return shape, which is the only remaining gap.

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; the parenthetical is dense but each clause (read-only, not editable, token requirement) earns its place. Slightly convoluted nesting keeps it from a 5.

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 no-arg enum lookup with no output schema, the definition covers purpose, safety, and auth. It stops short of describing the returned value structure, which an agent might want, but the essentials are present.

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

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

The tool takes zero parameters, so the baseline is 4. The parenthetical identifies the field the values map to (businessModelId), which gives useful context, but there is no parameter syntax to explain.

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 (valid values for a Stay's listing/business model) and names the underlying field businessModelId. An agent can distinguish it from sibling enum lookups such as getStayTypeOptions or getRoomTypeOptions.

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?

Implied usage is clear from the options-style name and the 'valid values' framing, but the description never states when to call this versus the many sibling *Options tools or what the returned values feed into.

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

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

Annotations already cover safety (readOnly, non-destructive), but the description adds context they cannot: the required 'bookings' scope, the constraint that only the caller's own paid bookings qualify, the closed enumeration of possible states, and a mandatory user-facing disclosure step. This is materially more than the annotations provide.

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

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

Front-loaded with purpose, then returns, then workflow rules, then auth, with no filler sentences. It is a dense single block that would read faster split into short lines for return fields and constraints, but nothing is redundant.

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?

There is no output schema, and the description compensates by naming the return fields (state, canCancel, cancellationType, deadlineUtc, message, onCancel) and enumerating the state values. For a read-only pre-flight check, nothing needed 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 coverage is 100%, so 'pnr' is already documented, but the description adds scoping meaning the schema does not: the booking must be the caller's own and paid. It does not add format hints, which is fine given a fully covered single string parameter.

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

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

States a specific verb and resource: checks whether one of the caller's own paid Stay bookings can still be cancelled, and what the member would get back. It also distinguishes itself from the nearest sibling by framing itself as the pre-check that must run before cancelBooking.

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?

Explicit sequencing ('Always call this first... before offering cancelBooking') and an explicit prohibition with its trigger condition ('When state is expired... do not offer cancelBooking'). The agent knows both when to call this and when to withhold the follow-up 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 declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds context the annotations do not: the required NOMADSTAYS_MCP_AGENT_TOKEN auth precondition. It says nothing about result size or ordering, which is a minor gap for a fixed enumeration list.

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 followed by the cross-reference and auth note. No filler, no repetition of the title or annotations.

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 must convey what comes back, and 'List valid values' does so adequately for a simple enumeration endpoint. It also names the consuming field and the auth requirement, leaving only return formatting unspecified.

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

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

There are zero input parameters, so the baseline is 4. The description still adds meaning by explaining what the returned values are for — they populate the cxPolicyId argument of another tool — linking output to a sibling's parameter.

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

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

States a specific verb and resource ('List valid values for a Stay's cancellation policy') and disambiguates from the many other *Options siblings by naming the exact field it feeds (cxPolicyId in updateStayOrganisationalData). An agent can distinguish this from getRoomTypeOptions, getCurrencyOptions, etc. 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?

The description ties the tool to its consumer: it supplies valid values for cxPolicyId in updateStayOrganisationalData, which tells the agent exactly when to reach for it. It does not state any exclusions or prerequisites beyond that, so it stops short of a full when/when-not statement.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is covered; the description adds the non-obvious operational requirement of NOMADSTAYS_MCP_AGENT_TOKEN and discloses the returned content (name and 2-letter code). It does not mention result ordering or size, but those are minor for a static reference list.

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 the consuming field, with no filler or repetition of the title.

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

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

With no output schema and no parameters, the description covers what an agent needs: the payload fields (name, 2-letter code), the field it feeds, and the auth prerequisite. Only the envelope format of the result (list vs. keyed object) is left unspecified, which is a small gap.

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

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

The tool takes zero parameters and the schema is an empty object, so there is nothing for the description to disambiguate; baseline 4 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) plus resource (valid values for a Stay's country) and the exact field it populates (countryId in updateStayOrganisationalData), which cleanly separates it from sibling option-listers like getCurrencyOptions and getStayTypeOptions.

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 reference to countryId in updateStayOrganisationalData gives clear context for when this tool is needed (before populating that field), but it does not state exclusions or name alternative sources of country data such as getStaysByCountry.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real context beyond them: the response contains a nextAction hint and a missingFields list of exactly which required fields are empty, plus the NOMADSTAYS_MCP_AGENT_TOKEN auth requirement.

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

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

Two tight sentences with no filler, and the scope statement is front-loaded ahead of the return-shape and auth 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 no output schema, the description usefully discloses the two key return elements (nextAction, missingFields) and the auth prerequisite, so an agent knows what it will get back. It stops short of describing failure behavior for an invalid applicationId, which is a minor 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?

Only one parameter (applicationId) and schema description coverage is 100%, so the schema already documents it fully. The description adds nothing about the parameter, which is the expected baseline when the schema carries the load.

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 ('the full current state of one Coworking Application'), making the singular scope explicit against the many-valued listCoworkingApplications and distinguishing it from the sibling getExperienceApplication/getStayApplication tools.

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

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

Usage is only implied: an agent can infer this is the single-record read versus the list, and the 'if incomplete' phrasing hints at a pre-submit check, but there is no explicit when-to-use/when-not or named alternative in the description itself (the listCoworkingApplications pointer lives in the schema, not the description).

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is fully covered. The description adds the use-case context (currencyFK) but no additional behavioral details such as return format or any 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?

A single, front-loaded sentence with no filler. Every word contributes to identifying the resource and its intended use.

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

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

For a no-parameter, read-only option-list tool with no output schema, the description is complete: it names the returned items (currency ids/codes) and the intended usage. 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?

The tool takes zero parameters, so there are no parameter semantics to clarify. The baseline score of 4 applies because the description cannot and need not compensate for any schema gaps.

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

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

States a specific verb (List), resource (valid currency ids/codes), and immediate purpose (for use as a package's currencyFK). The resource itself distinguishes it from sibling option-listing tools like getCountryOptions or getStayTypeOptions.

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 ties the tool to a concrete scenario: obtaining a currency identifier for a package's currencyFK. It does not name alternatives or state when not to use it, but the context is clear enough for an agent to know when to call 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 cover the safety profile (readOnlyHint=true, destructiveHint=false), so the bar is lower. The description still adds real value beyond that: it discloses the response shape (nextAction hint, missingFields list) and the required NOMADSTAYS_MCP_AGENT_TOKEN, which 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?

Two sentences, zero waste, with the core purpose front-loaded and the return content and auth requirement following. Every clause 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?

There is no output schema, so the description takes on the burden of describing returns and does so (nextAction hint, missingFields list for incomplete applications), plus notes the token requirement. For a single-parameter read tool 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 description coverage is 100% for the single applicationId parameter, so the schema already carries the meaning. The description adds nothing about the parameter beyond that baseline, so 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+resource ('Get the full current state of one Experience Application') that is plainly distinguishable from getStayApplication and getCoworkingApplication by the resource noun. It is clear and specific, but never explicitly contrasts itself with those sibling getters.

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 (fetch the state of an existing application) rather than stated. There is no when-to-use/when-not guidance, and the only routing hint toward listExperienceApplications lives in the schema parameter description, not the tool description itself.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered structurally. The description adds a genuinely non-obvious requirement – the NOMADSTAYS_MCP_AGENT_TOKEN auth need – which the annotations do not convey. It stops short of describing result volume or 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?

Three short sentences, each load-bearing: what it lists, the examples that make the resource concrete, the routing instruction, and the auth prerequisite. The call-first guidance is front-loaded where an agent will see it.

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 listing tool with no output schema, everything needed to call it correctly is present: purpose, example return values, sequencing relative to consumers, and the auth token. Nothing material 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?

There are zero input parameters, so the baseline is 4 and there is nothing for the description to compensate for. The example group names give the agent a sense of the value domain it will receive, a modest bonus over the empty 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 ('List every facility/checkbox group name'), supplies concrete example values, and scopes it to the platform. An agent can immediately distinguish this discovery call from the getMyStayFacilities/updateStayFacilities siblings that consume its output.

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 prescribes when to call it: 'Call this first if you don't already know the exact group name to pass to getMyStayFacilities/updateStayFacilities.' It names the downstream alternatives and the condition (unknown group name) that selects 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 declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds genuine context beyond that by disclosing the return shape (full article content, title, slug, categories), which matters because there is no output schema. It omits error/not-found behavior, which keeps it out of 5 territory.

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, zero filler, with the action and its scope front-loaded before the return-value note. Every clause 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 one-parameter read tool with full annotation coverage, the description covers what the tool does and what it returns, compensating for the absent output schema. Only the not-found/error path is unaddressed, a minor gap at this complexity.

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 fully documented in the schema, including the WordPress post ID format and an example. The description only restates 'by its ID' and adds no syntax or constraint detail beyond the schema, so the baseline 3 applies.

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

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

Names a specific verb and resource ('Fetch a specific NomadStays Help Center article by its ID') and scopes it to a single record, so it is distinguishable from listHelpCenterCategories. It does not, however, name searchHelpCenter, the sibling an agent is most likely to confuse it with.

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 its ID' implies the caller must already have an ID, which hints at the lookup-vs-search split, but the description never states when to use this instead of searchHelpCenter or where IDs come from. Usage is left 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 destructiveHint=false, so safety is covered. The description adds genuine value beyond that by scoping exclusions ('bank or tax-ID details — never exposed via MCP') and disclosing an auth requirement (NOMADSTAYS_MCP_AGENT_TOKEN). It does not describe response format, but for a single fixed fetch that is minor.

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, front-loaded with the core purpose, followed by the exclusion boundary and then the sequencing/auth notes. Every sentence carries information; no filler.

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

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

With no output schema and no parameters, the description compensates by naming the fields returned and the fields deliberately withheld, plus the auth prerequisite and call sequencing. Nothing an agent needs to invoke this 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 tool takes zero parameters, so per the rubric the baseline is 4. There is nothing for the description to clarify about inputs, and none is needed.

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 (Get) plus resource (host account's business profile), with an explicit enumeration of what is returned: legal business name, VAT/business registration numbers, and business-entity status. An agent can distinguish it from sibling readers like getMyStayOrganisationalData 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?

Explicitly states 'Call this before updateHostBusinessProfile,' which tells the agent the sequencing relative to a sibling write tool. It lacks broader when-to-use framing against other getMy* readers, but the sequencing instruction is concrete and actionable.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds the auth requirement (NOMADSTAYS_MCP_AGENT_TOKEN) and the read-before-write role, both of which are real behavioral context. It does not discuss pagination or failure modes, but for a single-record read that is a minor gap.

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?

Front-loaded with the core action, then the returned fields, then the usage rule and auth note — a sensible order with no filler sentences. The long field enumeration is dense but each item is load-bearing since there is no output 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 compensates by naming the return fields, plus it covers the single required parameter and the token requirement. An agent has everything needed to call this correctly and understand what comes back.

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?

Only one parameter, and schema coverage is 100% — the schema itself explains stayId is the EntryID and points to getMyStays. The description adds no syntax, format, or edge-case detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource ('Get a Stay's contact/owner/manager details and social media links') and then enumerates the exact fields returned (owner/manager/booking contacts, host display name, seven social platforms). That enumeration functionally distinguishes it from adjacent members like getMyStayDetail or getMyStayOrganisationalData without needing to name 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?

Gives explicit sequencing guidance: 'Call this before updateStayContacts so the agent knows current values,' which both names the sibling alternative and states the trigger condition. It stops short of a full when/when-not treatment (e.g., using it purely for read/reporting purposes is not addressed).

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds value beyond them by disclosing the auth requirement (NOMADSTAYS_MCP_AGENT_TOKEN) and the read-before-write workflow rationale. It adds real context rather than restating 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 short sentences, each earning its place: what it returns, when to call it, and the auth prerequisite. The returned content is front-loaded 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 single-parameter read-only getter with no output schema, the description enumerates the return fields (title, description, listed status), names the auth token, and states the workflow context. That is nearly complete, with the only minor gap being a fuller comparison against sibling getters.

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 stayId parameter already documents itself as the EntryID with a pointer to getMyStays. The description adds no parameter-level detail, so the baseline 3 for fully covered schemas 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 ("Get") plus precise resource ("current title, description, and listed status for one of your Stays"). It is clearly distinguishable from sibling list tool getMyStays and from getStayByID. An agent understands the exact content returned 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?

Explicitly tells the agent to call this before updateStayDetail and explains why (avoiding accidental overwrites), which is strong when-to-use guidance tied to a named sibling. It lacks any when-not-to-use or distinction from getMyStays/getStayByID, so it falls short of a full 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, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely useful context beyond that: the auth token requirement (NOMADSTAYS_MCP_AGENT_TOKEN) and the fact that the response merges platform-wide options with per-Stay selections. No rate-limit or pagination detail, so not 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?

Front-loaded with the core behavior and the options-vs-selections distinction, then prerequisites, then examples, then auth. Efficient, though the repeated group-name list overlaps with the schema description and could be trimmed.

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

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

No output schema exists, and the description compensates by explaining the return shape (all supported languages plus the currently selected ones). With prerequisites, auth requirement and scope all stated, an agent has everything needed to call this 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 description coverage is 100%, so both parameters are already documented, including the group examples and 'EntryID' for stayId. The description largely repeats those examples; its only marginal addition is clarifying that group scopes to a single checkbox group. Baseline 3 is correct.

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

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

States a specific verb and resource ('Get the available options AND current selections for one facility/checkbox group on a Stay') and gives a concrete worked example ('Languages Spoken'). The dual-return nature (options + selections) distinguishes it clearly from getFacilityGroups (options only) and updateStayFacilities (mutation).

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

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

Explicitly routes the agent to getFacilityGroups when the group name is unknown, and lists common group names to reduce that need. It does not, however, contrast against updateStayFacilities or explain what to do with the returned selections, so the 'when not to use' side is thin.

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/non-destructive, but the description adds substantial non-obvious context: Wi-Fi is a recency-of-test score rather than a speed rating, Operator Information carries an owner-only missingItems list, Stay Details auto-recalculates after MCP edits to details/contacts/facilities/photos, and the call requires NOMADSTAYS_MCP_AGENT_TOKEN. These are exactly the behavioural traits annotations cannot express.

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?

Front-loaded with the core purpose and the enumerated score list before the caveats. The trailing notes are dense but each one prevents a real misinterpretation (Wi-Fi semantics, owner-only fields, recalculation timing), though the passage could be tightened with bullets or shorter clauses.

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?

There is no output schema, so the description carries the return-value burden and does so: six named scores, an overall percentage, and a missingItems label list. It also covers auth requirements and recalculation timing, leaving nothing an agent needs to call and interpret this 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?

Only one parameter and schema coverage is 100%, with the schema itself explaining that stayId is the EntryID found via getMyStays. The description adds no further parameter syntax or format detail, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Get the Stay's listing-completion scores') and enumerates the exact six component scores plus an overall percentage. An agent can distinguish this from getMyStayDetail or getMyStays without opening any schema, since it is explicitly a derived scoring view rather than raw Stay data.

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

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

Gives a concrete triggering situation: 'Use this when a host asks how far along they are with onboarding or what's left to finish.' That is a clear usage context, but it does not name an alternative tool or state when not to use it (e.g. versus getMyStayDetail for raw field values).

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds real non-annotated context: the NOMADSTAYS_MCP_AGENT_TOKEN credential requirement and the fact that the result represents current values to diff against before an update. It says nothing about error behavior (e.g. unknown stayId), 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?

Three compact sentences: what is returned first (the enumerated data), then the sequencing guidance, then the credential requirement. Every sentence carries distinct information and nothing is repeated from 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?

With no output schema, the description compensates by enumerating the returned data categories, and it covers invocation prerequisites (token) and the downstream tool it feeds. For a single-parameter read-only fetch, an agent has everything needed to call and interpret 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?

There is a single required parameter with 100% schema description coverage, and the schema already explains that stayId is the EntryID discoverable via getMyStays. The description never mentions the parameter at all, so it adds no meaning beyond the schema; baseline 3 applies when the schema does all 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?

Specific verb (get) plus a named resource (a Stay's organisational data) and an explicit enumeration of the fields returned: address, check-in/out policy, pets/children/parking, cancellation policy, tourism/land-registration numbers. This cleanly separates it from siblings such as getMyStayDetail, getMyStayFacilities, and getMyStayContacts without needing to open 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?

Gives an explicit workflow condition: call this before updateStayOrganisationalData so the agent knows current values, which names the sibling it complements and the sequencing rationale. It does not state any when-not-to-use case or contrast itself with the other getMyStay* readers, so it falls just short of fully 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=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the auth requirement (NOMADSTAYS_MCP_AGENT_TOKEN) and enumerates the returned price-tier fields, which is genuine extra context. It does not discuss pagination or result limits, keeping 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?

Three tight sentences: what it returns, when to call it, and what auth it needs. Front-loaded with the return content, no filler or restated name/title.

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-param read tool with no output schema, the description is complete: it names the returned fields, the auth requirement, and the sequencing with the create/update siblings. An agent has everything needed to call 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% and the single stayId parameter is fully documented in the schema (including a pointer to getMyStays). The description only implies the stay scoping with 'on one of your Stays', adding no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb (List) and resource (pricing packages on one of your Stays) and even enumerates the fields returned (days, buy price, sell price, comparison price, listed status). This clearly separates it from getMyStayDetail, getMyStayRooms, and other sibling getters.

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 prescribes the call context: 'Call this before createStayPackage or updateStayPackage', naming both sibling alternatives and the motivating reason (hosts forget what they've set). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered; the description goes further by disclosing the return format (viewable CDN URLs, not filenames) and the token requirement. It stops short of describing ordering, counts, or behavior when a Stay has no photos, so it is strong but not exhaustive.

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: purpose and scope first, followed by the sequencing guidance and the auth constraint. Every sentence adds information an agent would otherwise have to guess, and nothing is repeated from the annotations.

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 compensates by characterizing the return value as full CDN URLs and by covering the auth prerequisite and pre-mutation use case. Minor gaps remain around empty-result behavior and whether results are grouped by area, but an agent has enough to call 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 description coverage is 100% and the single parameter is fully documented in-schema ('The Stay's EntryID (use getMyStays to find it)'), so the description adds only an indirect pointer to its own resource scope. Baseline 3 applies when the schema already carries parameter meaning.

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 every current photo for a Stay') and enumerates the areas covered (listing gallery, hero, workspace gallery, host), which clearly separates it from siblings like getMyStayDetail or getMyStayRooms. It also specifies the return form (full https:// CDN URLs rather than filenames), so an agent knows exactly what it gets.

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 instructs 'Call this before deleteStayPhoto or reorderStayPhotos to see current filenames,' naming the sibling tools and the sequencing condition that selects this tool. It adds the auth prerequisite (NOMADSTAYS_MCP_AGENT_TOKEN), leaving little to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false. The description goes beyond them by disclosing that facilities are resolved to names rather than raw IDs, photos are returned as viewable CDN URLs, and that an agent token is required. It does not discuss pagination or result limits, keeping 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 dense sentences, front-loaded with what is returned, followed by the when-to-use routing. No filler or repetition.

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

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

With no output schema, the description carries the return-value burden and does so (rooms, bed setup, occupancy, facilities, photo URLs). The auth prerequisite is also stated, so an agent has everything needed to call 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% and the single stayId parameter is already documented with the pointer to getMyStays. The description adds no format or constraint detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (List) and resource (all rooms configured on one of your Stays) and enumerates the returned payload (bed setup, occupancy, facilities, photos). It is clearly distinguishable from sibling reads like getMyStayDetail or getMyStayFacilities.

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 instructs to call this before createStayRoom, updateStayRoom, deleteStayRoom, deleteRoomPhoto, and reorderRoomPhotos, and gives the reason (show current values, find the right roomId/fileName). This names alternatives and the condition that selects 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 declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond the annotations by stating the required NOMADSTAYS_MCP_AGENT_TOKEN and listing the returned fields (stayId, title, listed status). It does not disclose pagination, sorting, or rate limits, 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?

The description is two sentences, front-loaded with the primary purpose. Every sentence carries useful information: ownership scope, return fields, usage guidance, and authentication requirement. There is no redundancy or waste.

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?

Given a zero-parameter, read-only list tool with no output schema but rich annotations, the description covers everything needed: what it returns, why to use it, and the authentication requirement. Return value semantics are explained inline, compensating for the missing output schema. No critical call-time information is absent.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. There are no parameter semantics to clarify, and the description correctly omits parameter details. No additional meaning beyond the empty schema is needed.

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 and resource: list all Stays owned by the account bound to the MCP agent token. It clearly differentiates from public search tools like getStaysByCountry and from the singular detail tool getMyStayDetail by emphasizing ownership and the account context. It also names the return fields, making 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?

It explicitly states the primary usage: use this to find a stayId before calling any other owner-scoped tool. This gives clear context for invocation and workflow position. However, it does not name a specific alternative tool or state when not to use it, so it falls short of the 5-level example that names the alternative and exclusion condition.

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 readOnly/destructive annotations, the description discloses the single-supported-product limitation, the fixed price (EUR 39), the meaning of the isWaivedForCaller return value, the automatic waiver behavior, and the required NOMADSTAYS_MCP_AGENT_TOKEN. That is substantial behavioral context the annotations do not carry.

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 zero filler; the highest-value fact (only product 8 is supported) and the return-value semantics are front-loaded. 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 annotations covering the read-only safety profile and no output schema present, the description fully compensates by explaining the return value, the waiver outcome, the product limitation, and the auth requirement. 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 description coverage is 100% and the schema already tells the caller to use 8 for the Stay Application fee. The description only adds the EUR 39 value, which is useful but marginal beyond the structured field, so the baseline 3 applies.

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

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

States a specific verb+resource ('Look up a Nomad Stays product's price and purchasability') and narrows scope immediately ('currently only product 8, the Stay Application fee'). An agent can distinguish this from sibling read tools like getPurchaseStatus and from the purchaseProduct mutation.

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 frames the follow-up path clearly: if isWaivedForCaller is true, 'there's nothing to pay and purchaseProduct will process the waiver automatically', which routes the agent to the correct next tool. It stops short of an explicit when-to-use/when-not statement or naming alternative tools directly, but the context is unambiguous.

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 a safe read (readOnlyHint=true, destructiveHint=false), but the description adds real value beyond them: it discloses that 'paid' is only ever returned after a fresh server-side verification, lists the four possible statuses, and names the required NOMADSTAYS_MCP_AGENT_TOKEN. That auth requirement and the freshness guarantee are not in the annotations or schema.

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

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

Three tight sentences, purpose front-loaded, followed by the usage rule and the enumerated statuses plus auth requirement. 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?

With no output schema, the description compensates by enumerating the possible return statuses. The auth dependency is stated and the verification behavior is explained, so an agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 100% and the single saleId parameter is documented in the schema as 'the saleId returned by purchaseProduct'. The description adds nothing 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: 'Check whether a purchase has been paid.' The status enum (pending, paid, failed, waived) further pins down scope. It doesn't explicitly distinguish itself from the similarly-named getBookingStatus sibling, so the differentiation is only implicit in the noun 'purchase' vs 'booking'.

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

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

Gives a strong when-to-use rule: never trust the member's own claim of payment, always poll this instead. This is actionable guidance an agent can follow. It does not, however, address exclusions or contrast with the getBookingStatus sibling.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful return content (room details, facilities, WiFi download/upload and jitter) but does not disclose operational behavior such as rate limits, authentication needs, or error handling.

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

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

Two sentences, front-loaded with the core purpose and scope. The second sentence slightly restates that facilities are returned, but overall it is efficient and well-structured.

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

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

No output schema exists, so the description carries the burden of describing return values; it does so at a high level (room details, all facilities, network performance data, WiFi metrics). It is sufficient for a simple read tool, though it could specify the return shape more concretely.

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 roomId is fully documented in the schema as the unique identifier (tbStaysRoom.EntryID). The description adds no further semantic detail about the parameter, 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 ('facilities and amenities') scoped to 'a specific room', and explicitly includes WiFi metrics. This differentiates it from sibling getAllAmenities (which lacks room scope) and getMyStayFacilities (which is stay-scoped rather than room-scoped).

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

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

Provides an implicit usage condition ('for a specific room'), but does not state when to prefer it over getAllAmenities, getRoomFacilityOptions, or getMyStayFacilities, nor any prerequisites. No explicit when-not guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered without prose. The description adds real value beyond them by disclosing the return granularity — a per-night available/not-available status — which is important since no output schema exists. It still doesn't say whether results reflect live inventory or cached data, which limits it below a 5.

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

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

Two short sentences with zero redundancy: the first states the operation and scope, the second states the return value. Front-loaded and appropriately sized for a simple three-parameter read.

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, three-parameter tool with full schema coverage and no output schema, the description supplies both the query semantics and the response shape, which is what an agent needs to call and interpret it. The remaining gap is boundary context — how it differs from the other availability tools in this large sibling set.

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

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

Schema description coverage is 100%, so all three parameters (roomId, checkIn, checkOut) are already documented with format details, establishing the baseline of 3. The description does not add anything the schema lacks, such as whether checkOut night is included in the per-night list or how check-in/check-out ordering is validated.

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 ('Check'), a specific resource ('a specific room'), and a precise scope ('each night in a date range'), plus the return shape (available/not available per night). That is far more specific than a generic 'get availability'. It does not name the related siblings it must be distinguished from (checkStayAvailability, getAvailabilityByMonth, hasAvailabilityInWindow, findNearestAvailability), so an agent has to infer the boundary itself.

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 per-night granularity and single-room scope imply the use case — you call it when you need night-by-night availability for one room rather than a whole-stay or month-level answer. However, there is no explicit statement of when to use this versus the several sibling availability tools, and no prerequisites (e.g. whether roomId must be a valid stay room).

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely non-obvious behavior — Wi-Fi is mandatory and always included even when not explicitly selected — plus the NOMADSTAYS_MCP_AGENT_TOKEN auth requirement, both of which affect how an agent interprets and reuses the result.

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 clauses: what is listed, the Wi-Fi caveat, the auth requirement. Front-loaded with the purpose, zero filler, and every sentence carries information an agent needs.

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 still characterizes the return set (every room-level option, with examples) and flags the mandatory Wi-Fi inclusion, and it notes auth. It stops just short of full completeness by not clarifying its relationship to the closely named sibling option-listing tools.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. It does usefully name the consumer field (roomFacilityFk) that the returned option identifiers feed into, which is extra semantic value beyond an empty 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 precise verb+resource (list every room-level amenity/facility option) and anchors it to a concrete use site — the roomFacilityFk field in createStayRoom/updateStayRoom — plus example values. An agent can distinguish it from getAllAmenities, getRoomAmenities, getFacilityGroups and getStayTypeOptions without opening any schema, even though it doesn't name those siblings explicitly.

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

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

Usage is implied rather than stated: by tying the output to roomFacilityFk in createStayRoom/updateStayRoom, it signals this is the lookup to run before writing room data. However, with near-identical siblings (getRoomAmenities, getAllAmenities, getFacilityGroups) no when-to-use-this-vs-that guidance is given, leaving the agent to guess which option-list is the right one.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond that: the valid value set is conditional on the Stay (boutique fixed range vs. standard restricted to already-used types) and it discloses the required NOMADSTAYS_MCP_AGENT_TOKEN, which isn't in structured fields.

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, all front-loaded and purposeful: purpose, dependency rule, auth requirement. The middle sentence is dense but carries genuinely useful domain logic rather than redundant phrasing.

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

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

No output schema exists, but the description makes clear the return is the set of valid room-type values, including the conditional logic that determines them. It is complete enough to invoke correctly; only minor detail on the returned structure is absent, which is acceptable for an options-list tool.

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

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

Only one parameter, and schema description coverage is 100% (stayId is documented as 'The Stay's EntryID'). The description adds no format or syntax detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (List) and resource (valid room types for a specific Stay's rooms) and ties the output to the roomTypeFK consumed by createStayRoom/updateStayRoom. This clearly separates it from the sibling getStayTypeOptions, which deals with Stay types rather than room 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?

The parenthetical naming roomTypeFK in createStayRoom/updateStayRoom effectively tells the agent when this lookup is needed. It gives clear context but does not explicitly name alternatives or exclusion conditions among the many other *Options tools.

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 (readOnly, non-destructive, closed-world), but the description adds two things they cannot: the NOMADSTAYS_MCP_AGENT_TOKEN auth requirement and the conditional return detail (nextAction hint, missingFields only when incomplete). That is real added context, though it says nothing about error behavior for an unknown or unauthorized applicationId.

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, zero padding: the purpose and payload lead, the auth prerequisite follows. Everything is front-loaded and each clause 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?

With no output schema, the description correctly compensates by naming the notable return fields (nextAction, missingFields). Combined with the auth requirement and a fully documented single parameter, an agent has what it needs to call this correctly; only edge-case failure 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?

Only one parameter and schema description coverage is 100%, so the schema already explains applicationId and where to get it. The description adds no format, range, or validation detail beyond that, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Get the full current state of one Stay Application') and scopes it to a single record, which cleanly separates it from listStayApplications and the save/submit siblings. It even previews the payload shape (nextAction hint, missingFields), so an agent knows exactly what it retrieves.

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: fetching one application by ID is the natural complement to listing, but the description never says when to prefer this over listStayApplications or the getCoworkingApplication/getExperienceApplication variants. The pointer to listStayApplications for ID discovery lives in the schema, not the description, so routing guidance here is only inferable.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds one useful behavioral fact—that the id is matched against two internal fields—but says nothing about return shape, pagination, or what happens when no match is found.

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

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

Two tight sentences with no filler, and the core purpose is front-loaded. The second sentence slightly overlaps the parameter schema description rather than adding fully new information, keeping it just under a 5.

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 annotations covering safety and no output schema, the description is nearly sufficient. It could note what happens on a missing record, but nothing critical to invoking it correctly is absent.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by noting the id also matches StayId in addition to EntryId, which is meaningful semantics for the parameter (though it is mildly inconsistent with the schema's own 'searches the EntryId field' text).

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: 'Returns full details for a single stay.' An agent understands the operation clearly. It does not, however, distinguish itself from close siblings like getMyStayDetail or getStaysBy* lookups, 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?

There is no explicit when-to-use guidance, no prerequisites, and no mention of alternatives among the many siblings (getMyStayDetail, getStaysByCountry, etc.). Usage is only implied by the name and verb.

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/openWorldHint/destructiveHint, so safety is covered. Beyond that the description adds real behavioral context: result ordering (most first), exact row fields, and precise definitions of 'stays' (live public listings) vs 'bookableNow' (currently listed for booking). It does not state pagination or result-size 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?

Front-loaded with the core behavior, then row fields, then usage examples. Every sentence carries information; the example question list is slightly verbose but justified for routing clarity.

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?

Despite no output schema, the description enumerates the returned columns and defines both metrics, so an agent knows exactly what it gets back. Combined with a single optional parameter fully covered by the schema, nothing needed for correct invocation 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 continent parameter is already documented. The description reinforces it as optional and implies the filter applies per country, but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource+aggregation ('how many stays ... in each country') and ordering ('most first'), clearly distinguishing it from the listing sibling getStaysByCountry. An agent can tell this is a count/aggregation tool 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?

Gives concrete example questions ('which countries have the most stays', 'how many stays do you have in Spain') that anchor when to use it, plus the optional continent filter condition. It does not explicitly name the alternative (e.g., getStaysByCountry for listing actual stays), so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely useful behavioral context by disclosing that matching spans two separate amenity sources (tbStayFacilities and tbRoomFacilities), which tells the agent why some amenity hits won't appear on the stay record itself.

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

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

Four short sentences, front-loaded with the core purpose and then the matching-model detail, with no filler. Slightly more verbose than needed given the schema repeats the matchType and WiFi-speed semantics.

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?

A read-only search tool with a fully documented schema and no output schema, so return-shape detail isn't required. It covers purpose, matching mode, and the optional numeric filter adequately; only minor gaps remain, such as case-sensitivity of amenity names and how limit interacts with result truncation.

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 matchType's enum and minWifiSpeed's Mbps unit is already documented in the schema. The description's restatement of matchType semantics adds confirmation but no new meaning, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Find all stays that have specific amenities') and immediately scopes it to both stay-level and room-level amenity sources. This clearly separates it from pure-location siblings like getStaysByLocation and the WiFi-only getStaysByWiFiSpeed, though it never names any 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?

Explains the matchType choice ('any' vs 'all') and the optional WiFi speed filter, which is real usage guidance. However it gives no when-to-use-this-vs-alternative routing, e.g. why an agent would pick this over getStaysByWiFiSpeed or getStaysByLifestyle, and no exclusions or prerequisites are stated.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds only the country-optional/global-search note, which is largely duplicated in the schema, and says nothing about result ordering, pagination, or the limit behavior.

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

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

Three sentences, front-loaded with the core purpose and examples. The middle sentence about the optional country overlaps with the schema but is short and does not bloat the definition.

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 search tool with a fully documented schema and safety annotations, the definition covers purpose and example usage adequately. It omits any hint about return shape or ordering (no output schema exists), which leaves a modest gap.

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

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

Schema description coverage is 100%, so all seven parameters are already documented in the schema. The description restates the optional-country behavior but adds no format, syntax, or constraint details beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb (Search) and resource (stays) constrained by budget and duration, which is a distinct filter axis from siblings like getStaysByAmenities or getStaysByCountry. It does not explicitly name or contrast any sibling, but the budget/duration scope makes it readily distinguishable.

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?

Two concrete example queries ('somewhere to stay for 1 month under EUR 1000' and 'a place in Spain for 1 month under EUR 1000') give clear context for when to reach for this tool. It stops short of naming alternatives or stating when NOT to use it.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, covering the full safety profile. The description adds essentially nothing beyond that: it does not describe result ordering, how partial matches behave, pagination, or what happens when the default limit of 15 is exceeded. A simple read tool with complete annotations needs little, but this adds no new behavioral 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 short sentences with zero filler; the core action is front-loaded in the first sentence and the parenthetical examples are compact. Nothing is wasted.

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

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

For a simple two-parameter read tool with 100% schema coverage and no output schema, the description is close to sufficient: the agent knows the source, the filter, and the input shape. Only the result shape (ordering, typical payload size) is left implicit, which is a minor gap given the tool's simplicity.

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

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

Schema description coverage is 100%, so both parameters (continent and limit) are already fully documented in the schema, including the default of 15. The description's continent examples duplicate the schema's examples rather than adding format constraints or matching semantics. Baseline 3 applies when the schema does the heavy lifting.

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 ('Returns stays from the NomadStays database filtered by continent'), so the agent knows exactly what it retrieves. However, it never distinguishes itself from the many sibling filters (getStaysByCountry, getStaysByLocation, getStaysByBudget), so the agent must infer which filter applies.

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?

'Search by continent name' implies the usage context and the examples ('Europe', 'Asia', 'Africa') show expected input, but there is no stated when-to-use or when-not-to-use guidance relative to the sibling country/location/budget filters. Usage is implied rather than explained.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds that results come from the NomadStays database and that name matching is partial ('Antigua' matches 'Antigua and Barbuda'), which is mildly useful behavioral context, but nothing about result ordering or pagination.

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

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

Two short sentences, front-loaded with the core action and followed by the input format. No filler, though the parenthetical examples duplicate the schema descriptions.

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 lookup with no output schema, the description covers what is needed to invoke it, but omits return-shape expectations, result ordering, and whether results are paginated beyond the limit parameter.

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 (countrycode, limit) are already documented in the schema, including the default of 15 and the partial-name example. The description's examples restate what the schema provides, so baseline 3 is appropriate.

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

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

States a specific verb+resource ('Returns stays from the NomadStays database') and the scoping criterion (country code or name). It is clearly distinguishable from siblings like getStaysByContinent or getStaysByAmenities, though the description never explicitly names the alternative facets.

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's emphasis on searching by country, but there is no explicit when-to-use guidance, no mention of when to prefer getStaysByLocation/getStaysByContinent, and no stated prerequisites.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds one genuine behavioral fact — a stay can belong to multiple lifestyle categories — but says nothing about result ordering, pagination, or what happens when a category matches nothing.

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 verb and resource, with no filler or repetition of the tool name. The second sentence is brief and informative, though marginally less essential than the first.

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 only 2 fully documented params and annotations carrying the safety profile, the definition is nearly self-sufficient. However, there is no output schema, so the description should say a bit more about the shape of the returned stays (fields, ordering, paging) than the bare phrase 'Returns stays'.

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

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

Schema description coverage is 100%: the schema already documents the default limit of 15 and the partial-match semantics of 'lifestyle', and even points to getAllLifestyles. The description only restates the same example categories, adding no syntax or matching detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (Returns), resource (stays from the NomadStays database), and the exact filter facet (lifestyle/genre category) with concrete examples. The lifestyle facet inherently distinguishes it from the many getStaysBy* siblings (byAmenities, byBudget, byCountry, byWiFiSpeed), so an agent can route correctly 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?

The description gives no when-to-use or when-not-to-use guidance and names no alternative among the getStaysBy* family. The only routing hint ('Use getAllLifestyles tool to see all available categories') lives in the input schema, not the description, so usage must be inferred from the purpose 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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavior context by disclosing the exact fields matched (City, State, location_name, location_country, location_description), but says nothing about pagination, result ordering, or behavior when no match is found.

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 what the tool returns, then the searched fields, then the usage cue. Every clause earns its place with no 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 two-parameter read-only search with no output schema, the definition covers purpose, fields searched, and usage context. What is missing (return shape, ordering, empty-result handling) is minor for this tool class given the annotations already carry the safety profile.

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 both parameters are already documented in the schema, including the same example values. The description's mention of matched fields largely duplicates 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 and resource ('Returns stays ... that match a location search term') and names the five fields searched. It is clearly distinguishable from the structured siblings (getStaysByCountry, getStaysByContinent) via the 'flexible location searches' framing, though it never names an alternative directly.

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 when-to-use directive ('Use this for flexible location searches') with concrete examples spanning city, region, and theme terms. It does not state when NOT to use it or route to the more specific sibling tools, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description usefully adds that results are limited to 'listed and not suspended' stays, but says nothing about return shape or pagination behavior.

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

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

A single sentence with no filler, and the scope qualifier ('listed and not suspended') is included efficiently. It is appropriately sized, though it is terse enough that a little more routing context could have been added without bloat.

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-required-parameter, read-only list tool with a fully documented schema and no output schema, the description covers the essential scope. The main gap is the absence of guidance on what the results contain or how many, though the limit parameter gestures at result sizing.

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 both parameters are fully documented by the schema; the description's mention of '10Mbps' merely restates the schema's default for minWiFiDownloadSpeed. It adds no syntax or format detail beyond structured data, making the 3 baseline correct.

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

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

States a specific verb (Find) and resource (stays) with an explicit filter criterion (WiFi download speed greater than 10Mbps), which clearly separates it from siblings like getStaysByAmenities or getStaysByBudget. It does not explicitly name those siblings, 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?

Usage is implied by the filter semantics — an agent can infer it is for speed-based stay discovery — but the description never states when to prefer this over getStaysByAmenities, getStaysByBudget, or getStaysByLocation, 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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds an auth prerequisite (NOMADSTAYS_MCP_AGENT_TOKEN) that annotations do not express, which is genuinely useful; it stops short of describing the returned value 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 sentence with the output meaning front-loaded, followed by the auth requirement. Every clause earns its place with no filler.

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

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

For a zero-param lookup an agent mainly needs to know what the list is for, which the description supplies by naming the target parameter. It does not describe the option payload (e.g. id/label pairs) and there is no output schema, a minor gap for an option-listing tool.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. The description correctly redirects the agent to where these values are consumed rather than describing non-existent inputs.

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 valid values for a Stay's Main Accommodation Type') and explicitly ties the output to the consuming parameter (stayTypeId in updateStayOrganisationalData). This lets an agent distinguish it from the many other *Options siblings 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?

Implies the usage context by naming updateStayOrganisationalData as the consumer, so an agent knows to call this before setting stayTypeId. There is no explicit when-not-to-use guidance or comparison against other option tools (e.g. getRoomTypeOptions), but the intended context is clear.

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, openWorldHint, and destructiveHint, so the safety profile is covered. The description adds useful behavioral context: it efficiently finds ANY qualifying window without checking every day, which clarifies the algorithm and result 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 definition is two tight sentences with the core purpose and the key alternative front-loaded. Every sentence earns its place and there is no redundant text.

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 availability check with no output schema, the description gives enough context to invoke it correctly and interpret the result as a yes/no availability test. It could explicitly state the return shape, but the annotations cover the safety profile and the use case is clear.

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 input schema already documents all four parameters. The description reinforces the relationship between date range and minimum length of stay via an example, but adds no new parameter 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 states a specific verb and resource: it checks whether a stay has any open booking window of a minimum length within a date range. It clearly distinguishes itself from checking individual dates via checkStayAvailability.

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 explicitly says to use this to filter search results to stays with real availability in the near future, gives a concrete example, and names the alternative it replaces: repeated calls to checkStayAvailability.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond them: the draft/submitted states returned, the four possible nextAction values, the absence of a pay_application_fee step, and the required NOMADSTAYS_MCP_AGENT_TOKEN auth.

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?

Front-loaded with the core action and return shape, then the usage rule, then the auth requirement. The fee-comparison sentence is slightly tangential but still earns its place by preempting a wrong assumption about a payment step.

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?

There is no output schema, yet the description describes what is returned (applications with a nextAction hint and its enumerated values) and the auth prerequisite. For a no-parameter read tool, 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. No misuse risk from undocumented inputs.

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 (caller's Coworking Applications), and scopes it to draft and submitted states with the returned nextAction hint enumerated. It is readily distinguishable from getCoworkingApplication (singular fetch) and the listExperience/StayApplications 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?

Gives a concrete when-to-use rule: call this to find an in-progress application's applicationId before resuming it. It does not explicitly name an alternative tool or state when not to use it, but the retrieval-before-resume framing provides clear context.

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 read-only, non-destructive, closed-world behavior, so the bar is lower. The description adds real value beyond them: the draft/submitted scope, the enumerated nextAction hints returned, and the required NOMADSTAYS_MCP_AGENT_TOKEN auth, though it says nothing about pagination or result volume.

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 resource and scope, then the return hints, then the actionable usage tip and the auth requirement. No filler.

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

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

No output schema exists, so the description usefully compensates by enumerating the nextAction values an agent will receive. The only remaining omission is result size/pagination behavior, which is minor for a caller-scoped list.

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

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

The tool takes no parameters, so per the rubric the baseline is 4. There is nothing for the description to disambiguate; the 100% schema coverage is vacuous here but no gap is left open.

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 caller's Experience Applications') and scopes it to drafts and submitted, which cleanly separates it from sibling listStayApplications/listCoworkingApplications and from getExperienceApplication.

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

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

Gives a clear when-to-use: 'Call this to find an in-progress application's applicationId before resuming it.' It does not explicitly name the alternative (getExperienceApplication) for fetching a single known application, so it stops short of full when-not guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing the returned fields, which matters because no output schema exists; it does not mention pagination or result-size 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 sentences, zero filler, purpose front-loaded in the first clause and return shape in the second. 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 parameterless, read-only listing tool with annotations covering safety and no output schema, the description supplies everything needed: what is listed, that it is exhaustive, and what each item contains.

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

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

The tool takes zero parameters, so the baseline is 4. There is nothing for the description to clarify beyond confirming that the call is unfiltered and returns all categories.

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 (List) plus resource (NomadStays Help Center categories), and it enumerates the fields returned, so an agent immediately knows what it gets. It never names a sibling such as searchHelpCenter or getHelpCenterArticle, so differentiation is implied by the resource 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.