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

Annotations only cover the safety profile (not read-only, non-destructive), and the description adds substantial behaviour: ID-vs-text lookup requirements for six fields, the rejection behaviour for fullPayment when the country disallows it, and the auth requirement ('MCP agent token scoped to the owning account'). This is meaningful context an agent cannot derive from 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?

Four sentences, each load-bearing: scope, partial-update rule, the IMPORTANT lookup warning, and the auth note. The first sentence is a long field list, but the critical warning is emphasised ('IMPORTANT') and not buried; minor trimming of the field enumeration would tighten it further.

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 30-param mutation tool with no output schema, the description covers change semantics, dependent lookup calls, country-gated field restrictions, and auth scope. Remaining gaps are only low-stakes formatting details (date/time string formats) and, since no output schema exists, no indication of what is returned.

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 only 43% schema coverage across 30 params, the description carries extra weight, and it does compensate for the hardest cases: it identifies countryId, petsAllowedId, childrenAllowedId, parkingId, cxPolicyId and stayTypeId as lookup IDs and names the exact source call for each. Many remaining string/date params (checkInTo/checkOutTo formats, city/state/postCode) are still undocumented in both places, keeping it below 5.

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 ('Update a Stay's organisational data') and then enumerates the exact field families it governs (address, check-in/out policy, pets/children/parking, cancellation policy, accommodation type, registration numbers, 'Why Choose Us'). This implicitly separates it from updateStayDetail/updateStayFacilities/updateStayContacts, but no sibling is named explicitly, 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?

Gives strong context: partial-update semantics ('Only fields supplied are changed') and a prerequisite workflow telling the agent to call getCountryOptions/getAdditionalInformationOptions/getCancellationPolicyOptions/getStayTypeOptions before constructing certain fields, plus the schema-side requirement to check fullPaymentAllowedByCountry first. It lacks an explicit 'use X instead of this tool when...' exclusion, so it is a solid 4 rather than a 5.

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