Nexwin AI

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds the note that no account connection is needed, which is valuable behavioral context not present in the annotations. No contradictions 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?

The description is two sentences with no filler. The purpose is front-loaded ('Explains what Nexwin is and how to sign up') and the usage condition follows directly. Every word 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, zero-parameter informational tool with an output schema present and annotations already carrying safety properties, this description is complete. It covers the purpose, the trigger conditions, and the lack of authentication requirement — nothing an agent needs 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 has zero parameters, so the baseline is 4 per the rubric. The schema is fully covered (100%) and there is nothing for the description to add about parameters. The description correctly avoids inventing parameter details.

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 the specific verb 'explains' and names the resource 'Nexwin', stating exactly what it does: explain what Nexwin is and how to sign up. It also implicitly distinguishes from siblings like create_booking, which are action-oriented, by focusing on informational content.

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 specifies when to use the tool: 'when the user asks what Nexwin is, what it does, or how to get started.' It also adds the condition 'no account connection needed,' giving clear context for when this is the right tool versus more functional siblings.

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?

Discloses a lot beyond the annotations: transactional all-or-nothing semantics with per-row error reporting, the 100-item cap, the 'executes immediately' timing, the rule that identical units become one asset with a quantity, and the receptionist-notification side effect. None of that is derivable from the schema or the safety hints alone.

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

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

Front-loaded with the core action and scope, then constraint, then semantics, then prerequisite – a logical order with no filler sentences. It is dense but every sentence carries information; a shorter variant would lose the atomicity and quantity rules.

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 write tool with an output schema, no return-value description is needed, and the description covers atomicity, error behavior, limits, side effects, and the prerequisite call. The annotations cover the safety profile (non-destructive, non-idempotent), leaving no critical gap for an agent before invoking.

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?

Adds real meaning the schema cannot: it explains every bookingType enum value (nightly, day, date_range, not_applicable) and clarifies the quantity modeling convention (identical units collapse into one asset with a quantity). It leaves hideName, checkInTime, checkOutTime, and description to the schema, so it is not fully covering.

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 ('Adds bookable assets (rooms, campsites, vehicles, equipment) to the connected Nexwin account') plus scope limits (up to 100 per call) and a side effect (notifies the live receptionist). This is clearly distinguishable from siblings like list_assets, import_customers, and create_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 concrete use case ('set up a whole list the user has pasted or uploaded') and a sequencing rule ('Call list_assets first to avoid clashing names'). It stops short of saying when not to use it or what to do about existing assets, so it is strong but not exhaustive.

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 this is a non-read-only, non-destructive, non-idempotent write with no open-world access. The description goes beyond them with real operational context: no login is provisioned, nobody is emailed, and the call returns a teamMemberId. It stops short of explaining duplicate handling, which matters given idempotentHint=false.

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, each carrying a distinct fact: what it does, the no-email behavior, the alternative tool, the internal-only flag, the return value. Lead sentence is the most important and nothing is 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?

An output schema exists, so the description needn't enumerate return fields, yet it still names teamMemberId. Combined with the no-login/no-email disclosure and the explicit sibling routing, an agent has everything needed to select and invoke this correctly against a 5-param schema.

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

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

Schema description coverage is 60% (email and isInternalOnly documented; firstName, lastName, timezone bare). The description reinforces isInternalOnly's meaning but adds nothing for timezone format, name constraints, or what email is used for beyond the schema's own note. Baseline 3 applies since the schema carries most of 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 and resource ('Adds a person to the connected Nexwin account's team') plus the defining constraint that no login is created. The sibling tool invite_team_member is named directly, so an agent can separate the two without reading either 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?

Explicit routing rule: 'Use invite_team_member instead if they need to sign in.' It also gives a per-parameter usage rule for isInternalOnly ('someone callers should never be told about by name'), covering both tool selection and option selection.

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 destructiveHint=true and idempotentHint=false, but the description goes well beyond them: it discloses the deletion semantics (won't appear even as canceled), the side effects (Zoom meeting, calendar event removal, customer email), irreversibility, and the required user-confirmation flow. This is rich, non-redundant 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?

Front-loaded with the core action and its destructive nature, then side effects, then the preconditions. Every clause carries information the agent needs; nothing is padding.

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

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

With an output schema present, return values need no explanation, and the description covers the mutation's consequences, irreversibility, side effects, and confirmation protocol. Nothing needed 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 coverage is 100%, so the baseline is 3, but the description adds real meaning by tying confirm to an explicit user 'yes' about a specific booking and reiterating appointmentId's origin. It reinforces the schema rather than merely restating it.

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 (cancel a booking) and immediately clarifies the scope by defining it as PERMANENT DELETION rather than a status change — which is exactly the distinction that separates it from reschedule_booking among the siblings. An agent can select it unambiguously.

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, that it cannot be undone, where appointmentId comes from (get_bookings), and the exact conversational precondition plus the confirm: true gate before invoking. No conditions are 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=false, idempotentHint=false and openWorldHint=true, so the write/non-idempotent character is known. The description adds real context beyond that: immediate execution with no confirmation step, an outbound customer confirmation email, and a documented conflict failure mode ('Fails if the team member is already booked'). Auth/permission requirements are still unspecified.

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 dense sentences, all load-bearing: purpose and side effect first, then prerequisites, then conditional parameters, then failure mode. 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?

An output schema exists, so return values need no explanation, and the annotations cover the safety profile. The description covers prerequisites, conditional requirements and the conflict failure, leaving only minor gaps such as behavior if the confirmation email fails or any rate/permission constraints.

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 only 50%, and the description compensates by encoding conditional parameter requirements that the schema does not express: customerEmail for online bookings, customerEmail or customerPhone for in-person, and the source of teamMemberId/timezone. It could say more about meetingAddress and title, which remain purely schema-defined.

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 ('Creates a new appointment on the connected Nexwin account') plus the immediate side effect of emailing the customer a confirmation. This is distinguishable from read-oriented siblings like get_bookings and from reschedule_booking without opening either 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 prerequisites ('Get teamMemberId and timezone from list_team_members first') and explicit branching rules for meetingType ('Online bookings require customerEmail ... in-person bookings need customerEmail or customerPhone'). It stops short of stating when NOT to use this tool, e.g. pointing at reschedule_booking for existing appointments.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds real behavioral value by describing what gets returned: contact details, call/chat frequency, and last-conversation topic. It does not mention match-count behavior or ambiguity handling, keeping it at a 4.

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 action and resource, followed by return content and example use cases. No filler or 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?

An output schema exists, so return values need not be explained, yet the description still usefully previews them. Purpose, search semantics, and use cases are all covered for a simple two-parameter read 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%, so both parameters are already documented in the schema; the description's mention of 'part of a name, phone number or email address' mirrors the search parameter without adding format or syntax detail. The limit parameter is not addressed in the description at all, 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 (looks up), resource (customers on the connected Nexwin account), and the matching mechanism (partial name, phone, or email) in the first sentence. This clearly distinguishes it from siblings like import_customers or get_call_chat_history.

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 concrete example questions it answers ("has Sam called before?", "what did Sam want last time?"), which gives clear usage context. It stops short of naming an alternative tool or stating when NOT to use it, so it falls just below the explicit when/when-not bar.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds the connected-account scope and output fields, but it does not disclose behaviors such as data freshness, authentication requirements, or rate limits. This is adequate but not exceptional.

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 that lists the key result dimensions with no filler. Every word contributes meaning and the structure is easy to scan.

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

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

For a no-parameter read-only tool with a rich output schema and readOnly/idempotent annotations, a one-sentence summary of what is returned and the account scope is complete. 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 has zero parameters, so there is no parameter ambiguity for the description to resolve. The baseline of 4 applies; the description appropriately focuses on what data will be returned rather than parameter details.

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

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

The description names a specific verb and resource ('get account usage summary') and enumerates the exact data returned: plan, subscription status, minutes/messages used, and wallet balance for the connected Nexwin account. This clearly differentiates it from siblings like about_nexwin or get_bookings.

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

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

The description implies the natural use case — checking plan, usage, and wallet for the connected account — but gives no explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives like about_nexwin. The intended usage is inferable but not 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 the read-only/idempotent, closed-world profile, so the bar is lower, yet the description still adds real behavior: the business-timezone interpretation of 'today', the 30-day ceiling, newest-first ordering, and the followUpsOnly filtering effect. It stops short of noting pagination/truncation behavior against maxItems, which is the only meaningful 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?

The opening sentence front-loads purpose, followed by concrete user-intent phrasings, return shape, and parameter guidance in a compact flow with no filler. It is longer than the minimum but nearly every clause carries routing or parameter information; a tighter phrasing of the return summary would earn 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?

With an output schema present, the description is not obliged to enumerate return fields, yet it still previews the totals and per-conversation entries, so the agent knows what to expect. Combined with the usage and parameter guidance, nothing needed to select or call the tool 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 already 100%, so baseline would be 3, but the description adds semantics the schema does not: 'today counts as day 1, in the business's timezone' and the mutual-exclusivity between lastDays and startDate/endDate. It also translates followUpsOnly into an intent ('who do I need to call back?'), though maxItems is left unaddressed.

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

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

The description names a specific verb and resource ('Summarises what happened on the connected Nexwin account over a period') and grounds it in real user questions ('what's happened the last two days?', 'anything I need to follow up?'). It clearly distinguishes itself from get_call_chat_detail by naming it as the route to full transcripts, and from get_account_usage_summary by scoping to calls/chats activity.

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

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

It states exactly when to use the tool, when to set followUpsOnly ('who do I need to call back?'), and explicitly names the alternative for a related need (get_call_chat_detail for a full transcript). The date-window rule (lastDays OR startDate/endDate, 30 days max) removes the main invocation 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context beyond that: it shows settings 'as callers hear it', notes business hours are read-only, and mentions listing the last few published versions for restore.

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 front-loaded with the main purpose and then enumerates the returned fields in a single long sentence, followed by two short sentences for usage. It is informative but somewhat run-on; the enumeration could be tightened, though every item is relevant to the receptionist setup.

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 the tool is a read-only, zero-parameter operation with an output schema, the description provides everything needed: what it returns, why to call it (before update_ai_setup), and its relation to restore_ai_setup_version. No critical behavioral or usage information 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 document. The baseline for zero-parameter tools is 4, and the description correctly does not fabricate parameter details.

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 ('Shows how... is set up right now') and resource ('AI receptionist'), and explicitly distinguishes itself from update_ai_setup and restore_ai_setup_version. An agent can tell exactly what this tool returns without opening the schema.

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

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

It gives clear context: call before update_ai_setup to base changes on current wording, and use it to get the version list needed by restore_ai_setup_version. It does not explicitly state when not to use it, but the alternatives are named and the primary use case is well-defined.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavior beyond annotations: it discloses the 30-day maximum range, 25-result limit, and the specific fields included in each booking (appointmentId, teamMemberId, ISO startTime/endTime, timezone), plus the connected-account 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?

Three concise sentences front-load the core purpose and limits, then add relation to sibling tools and account requirement. No filler or redundant restating of the title or schema. 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?

Given the tool's moderate complexity, the presence of an output schema, and rich annotations, the description covers the essential operational context: purpose, date range limits, result cap, key fields, sibling-tool usage, and account prerequisite. No critical information 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?

The schema already provides descriptions for startDate and endDate ('YYYY-MM-DD, business-local'), giving 67% coverage. The description adds the 30-day max range constraint and clarifies the result fields, which aids parameter interpretation, but it does not address the optional status parameter's meaning or filtering behavior beyond the enum in the schema. Overall, it adds some value but the schema still carries the main parameter burden.

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 ('Lists'), a clear resource ('appointments/bookings in a date range'), and adds the account scope ('connected Nexwin account'). It also distinguishes the tool's output by noting fields needed for sibling tools reschedule_booking and cancel_booking, so an agent can identify its role without opening the schema.

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

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

The description clearly implies when to use this tool: to retrieve bookings in a date range, especially when needing appointmentId and teamMemberId for reschedule_booking or cancel_booking. It also notes the 'Requires a connected account' prerequisite. It does not explicitly state when not to use it or name an alternative for listing bookings, but the context is clear enough.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so safety is covered. The description adds the requirement for a connected account, which goes beyond annotations, and notes it fetches a 'full transcript' implying a potentially large payload. However, it doesn't elaborate on performance or error behavior. With annotations carrying the safety profile, this adds modest value, so a 3 is appropriate.

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 with zero fluff. The verb and resource are front-loaded, and the auth requirement is placed at the end as a concise precondition. Every word 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 fetch tool with two params, an enum, and an output schema (which covers return values), the description is nearly complete. It covers what the tool returns (full transcript/detail), how to identify the target (id), and the auth prerequisite. It doesn't mention error scenarios or timeouts, but these are minor gaps given the output schema and 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 coverage is 50% – only 'id' has a description ('The callId or chatId from get_call_chat_history'), while 'channel' only has an enum. The description says 'for one call or chat' which clarifies that 'channel' distinguishes between the two, and 'by id' aligns with the id schema. It adds some context beyond the schema but doesn't fully compensate for the missing channel description, so it meets the baseline.

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

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

The description clearly states the verb 'Fetches' and the resource 'full transcript and detail for one call or chat, by id.' It distinguishes this from the sibling 'get_call_chat_history' by focusing on a single item via id, making the purpose unmistakable.

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 provides clear context: you need an id from history ('by id') and a connected account is required. While it doesn't explicitly name alternatives or say 'use when you have an id', the structure implies this tool is for retrieving a specific record after listing, and the auth requirement is a useful precondition. No exclusions or alternative-routing are given, so it's not 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 establish that the operation is read-only, idempotent, and non-destructive. The description adds meaningful behavior beyond that: it requires a connected account and deliberately omits full transcripts. Nothing contradicts 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?

One tight, front-loaded sentence states the core action, the scope, the date constraint, the transcript limitation, and the prerequisite. 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 read-only listing tool with an output schema and safety annotations, the description covers purpose, scope, and the key prerequisite. It is complete enough for an agent to invoke correctly, though it could have made the limit behavior slightly more explicit.

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 50%, and the description compensates slightly by mapping 'calls or chats' to the channel enum and 'date range' to startDate/endDate. However, the limit parameter is not explained in prose, and the description does not add format or constraint details beyond what the schema already shows.

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 ('Lists'), a clear resource ('recent calls or chats'), and a scope ('connected Nexwin account', 'date range'). It also distinguishes itself from the sibling get_call_chat_detail by explicitly noting it returns no full transcripts.

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

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

The description gives clear context for when the tool is appropriate: recent calls/chats in a date range for the connected account. However, it never explicitly states when to prefer get_call_chat_detail or which conditions rule this tool out, leaving the sibling distinction mostly implied by 'without full transcripts.'

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 by disclosing dedup rules (rows matching an existing phone or email are skipped), a validation rule (rows without a first name are skipped), that existing customers are never modified, that nobody is contacted, that the result reports counts of each skip type, and that it executes immediately. This is exactly the side-effect profile an agent needs for a mutation tool.

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?

Six short sentences, front-loaded with what the tool does and the batch limit, then progressive detail on dedup, immutability, and side effects. Every sentence carries distinct information with no repetition of the schema.

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

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

For a write tool with an output schema already present, the description covers the essentials: what gets written, what gets skipped and why, what is left untouched, and that no one is contacted. An agent can call this 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 0% at the top level, so the description must carry the load, and it does: it explains the 200-row cap, the required first name, and that phone/email drive duplicate detection. It stops short of describing the remaining item fields (notes, address, lastName) beyond what the schema itself implies.

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 ('Adds customers to the connected Nexwin account'), quantifies scope ('up to 200 in one call'), and names the source ('a list the user has pasted or uploaded'). No sibling tool does bulk customer import, and the description makes that role obvious against lookups like find_customer.

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 usage context is clear - bulk onboarding of a pasted/uploaded list - which implicitly routes the agent away from single-customer tools. However, it never names an alternative (e.g. find_customer for lookup) or states when not to use this tool, so the guidance is contextual rather than explicit.

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

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

Annotations only say this is a non-read-only, non-idempotent, open-world write. The description adds substantial context beyond that: the invite is pending until acceptance, the link expires in 24 hours, the invitee starts with calendar-only access, additional access is granted elsewhere in the dashboard, and the email is dispatched immediately on call. That is exactly the side-effect detail an agent needs before invoking.

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 dense sentences, front-loaded with the core action, then the alternative, then access scope, then the immediacy warning. Every sentence carries distinct information, though it runs slightly long for a single tool description.

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

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

With an output schema present, return values need not be described. The description covers the action, the alternative, the timing/expiry behavior, the default permission scope, and the pre-call check — 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 coverage is only 40% (role and timezone are documented; email, firstName and lastName are not). The description only touches the email parameter indirectly ('check the address with the user first') and adds nothing about name fields. Since the undocumented params are largely self-explanatory, this is adequate but does not fully compensate for the coverage gap.

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 (emails an invitation) and resource (team member / Nexwin account) with a clear outcome: they get their own login and become a member on acceptance. It explicitly distinguishes itself from the sibling add_team_member by contrasting the two use cases.

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?

Names the alternative tool (add_team_member) and the exact condition that selects it ('a person who only needs to be bookable and won't sign in'). It also gives an operational precondition: check the address with the user first because the email sends immediately.

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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety and idempotency profile is fully covered elsewhere. The description adds account scope and lists the kinds of attributes returned (type, unit count, booking mode, check-in/out times), but since an output schema exists it need not and does not go further into return format, pagination, or result size.

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

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

Two sentences, both front-loaded: the first defines the resource and its examples, the second gives the routing/ordering cue. No filler, no restatement of the title, and 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?

With zero parameters, an output schema present, and rich annotations, the description carries the only remaining burden — what this resource is and when to call it — and it does both. Nothing an agent needs to select or invoke the tool is missing.

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

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

The tool takes zero parameters (empty object schema), so there are no parameter semantics to document and the baseline of 4 applies. Nothing in the description misleads about inputs; a brief note that no arguments are required would have been a small bonus.

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 ('Lists the bookable assets on the connected Nexwin account') and immediately defines the domain in a way that separates it from the sibling list_team_members: 'things customers book rather than people, such as hotel rooms, campsites, vehicles or equipment.' An agent can distinguish this from other list_* tools 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 an explicit workflow cue with a named sibling: 'Call this before add_assets to see what is already there.' The 'rather than people' phrasing implicitly steers away from list_team_members without naming it, so there is no explicit when-not statement, keeping it just short of 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds the prerequisite 'Requires a connected account,' which is an authorization need not present in annotations, and adds the 'active' filter on team members, further describing behavior. It doesn't describe error cases or pagination, but the bar is lower given annotations; the addition of auth context earns a 4.

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, both earning their place. The first sentence front-loads the primary purpose with the exact action and result. The second sentence provides crucial usage direction and a prerequisite. There is no fluff or 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 zero-parameter, read-only list tool with an output schema and comprehensive annotations, the description is complete. It covers what the tool does, its prerequisite, and its intended use within the workflow. The output schema handles return value details, and annotations cover safety, so 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 has zero parameters, so there are no parameter semantics to add. The baseline for 0 parameters is 4, and the description appropriately avoids any parameter discussion. It does mention the output fields (teamMemberId, timezone) which aligns with the output schema, adding value beyond the empty input 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 clearly states the tool lists active team members with their teamMemberId and timezone, using the specific verb 'lists' with a clear resource. It also distinguishes the tool from siblings by specifying it returns team member identifiers and timezone, which is not ambiguous with other list-like tools like get_bookings or get_account_usage_summary.

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

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

The description explicitly tells the agent when to use this tool: 'Call this before create_booking to get a real teamMemberId and the timezone to book in.' This is a clear usage context with a named companion tool, but it doesn't explicitly state when not to use it. The guidance is adequate and actionable, though not exhaustive.

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 destructiveHint=true and non-idempotent, but the description adds exactly the context they cannot carry: the login is deleted (sign-in blocked), connected calendars are disconnected, the action is irreversible, and recovery requires re-inviting. It also documents the authorization invariants (owner protected, no self-removal), which are pure 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?

Four sentences, all load-bearing: consequence, irreversibility, invariants, and the required confirmation protocol. The destructive scope is front-loaded with 'PERMANENTLY', so an agent knows the stakes before reading 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?

With an output schema present, return values need no explanation; the description instead covers everything that matters for a destructive two-param operation: source of the ID, side effects, irreversibility, blockers, and the mandated confirmation dialogue. Nothing an agent needs to call this 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 coverage is 100%, so the baseline is 3; the description meaningfully raises it by tying teamMemberId to list_team_members as its source and by spelling out the conversational confirmation flow that makes confirm: true valid. It stops short of adding format or edge-case detail beyond that.

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 removes a team member') plus scope ('from the connected Nexwin account'), and names the source of the ID (list_team_members). It is unambiguously distinguishable from siblings add_team_member, invite_team_member and update_team_member 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?

Explicitly states preconditions and prohibitions: the account owner cannot be removed, nobody can remove themselves, and the call requires telling the user who will be removed and getting an explicit yes before passing confirm: true. It also points to list_team_members as the way to obtain teamMemberId, so the agent has a full operational path.

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 destructive/non-idempotent, but the description adds genuinely new behavioral context: the customer is emailed, and the operation executes immediately once confirm: true is passed. That execution-timing and side-effect disclosure goes well 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?

Three tight sentences, front-loading what the tool does before the confirmation protocol and the immediate-execution warning. 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?

An output schema exists so return values need no explanation, and the description covers the safety-critical confirmation flow and side effect. Nothing an agent needs in order to call 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?

Schema coverage is 100%, so all five parameters (including ISO 8601 formats, timezone default, and the confirm gate) are already documented in the schema. The description only restates the confirm requirement and appointmentId origin, adding little beyond the structured data. 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 ('Moves an existing booking ... to a new time') plus a side effect (emails the customer). This clearly distinguishes it from siblings cancel_booking and create_booking without needing to open either 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 prescribes the pre-call workflow: tell the user which booking (customer, current time) is moving where, get an explicit yes, then pass confirm: true. It also names the prerequisite source for appointmentId (get_bookings), leaving nothing 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?

Goes well beyond the destructiveHint/readOnlyHint annotations: it discloses that the change goes live for callers immediately, that the restore is itself saved as a new version, that unmanaged settings are left alone, and that versions published from the dashboard omit their area list so the service area is left untouched and the result reports this. The confirmation protocol is also spelled out.

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 that front-loads what the tool does and what it affects, then the dashboard caveat, then the confirmation requirement. Every clause carries information, though the length sits near the upper bound for a two-parameter tool.

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

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

Covers the mutation's blast radius, the version-source question, the dashboard-version edge case, and the approval requirement; with an output schema present it need not describe return values, and 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: it tells the agent where version numbers originate and that confirm must only be true after explicit user approval, reinforcing the schema's own wording with procedural context.

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 (restore earlier published settings) and frames it as the inverse of two named siblings, update_ai_setup and update_service_area. An agent can distinguish it from get_ai_setup (read) and the update tools (forward mutation) immediately.

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 condition that selects this tool (undoing changes made by the update tools) and where valid version numbers come from (get_ai_setup or an update result), plus an explicit prerequisite to get user approval before calling. It stops short of stating when not to use it, e.g. that settings outside those tools' reach cannot be changed here.

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, idempotentHint=false and not read-only, but the description adds substantial context beyond them: the change is applied live to real callers at once, all changes are atomic ('applied together or not at all'), they are versioned and reversible via restore_ai_setup_version, and handbook notes are never auto-removed. No claim contradicts 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?

Front-loaded with the purpose and the live-immediately consequence, and most sentences carry actionable rules. It is on the long side, with a fully worked temporary-note example that consumes real space, but the content is mostly load-bearing rather than padding.

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

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

For a destructive, non-idempotent mutation with a gate parameter, the description covers everything an agent needs: the confirmation protocol, atomicity, reversibility, field-level semantics, and the follow-up call required to undo a note. An output schema exists, so return values need not be explained.

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 50% schema coverage the description compensates well: it enumerates the editable fields, gives the allowed afterHoursAction values, notes aboutYourBusiness is capped at 500 characters, and explains that sendConfirmationEmail takes true/false and what append/remove do semantically (append to end vs remove one exact piece, neither = full replace). It adds meaning beyond the schema's structural definitions, though the field enum itself is already in 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 (changes) and resource (the connected account's AI receptionist answer settings), plus the critical scope fact that changes go live for real callers immediately. It is clearly distinguishable from get_ai_setup (read) and restore_ai_setup_version (undo) among the 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 explicit prerequisites ('Call get_ai_setup first'), a mandatory workflow ('tell the user exactly which settings will change... get their explicit yes; then pass confirm: true'), and names the alternative modes (append vs remove vs full replace) with the condition that selects each. It also routes temporary changes to the append pattern rather than 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 flag destructiveHint=true and non-idempotent, but the description adds the traits that matter most: the change goes live for real callers immediately, it can still be undone via restore_ai_setup_version, and an ambiguous place name causes a no-op with an error listing the matches. It also documents the structural constraint that a listed area cannot be partially excluded.

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 core action and its immediate-live consequence are front-loaded in the first sentence, and virtually every subsequent sentence carries rules an agent cannot infer elsewhere. It is however a very dense block of run-on clauses, and the audience/permission framing near the end could be tightened without losing meaning.

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

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

With an output schema present, the description need not explain return values, and it still covers prerequisites, confirmation requirements, ordering, geography-specific rules, coverage semantics, and reversibility. Nothing needed to invoke this correctly in either region 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 already 100%, so the bar is higher than baseline, yet the description still adds real semantics: a postcode adds every suburb in it, region is the Qatar municipality type, coverAll narrows rather than widens when areas are also added, and outOfAreaPolicy's two enum values are expanded into actual caller outcomes (reject = told, not booked; flag_for_review = details taken). Some of this duplicates the schema description text for confirm and coverAll, keeping it short of a 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?

"Changes which places the connected account's AI receptionist serves" names a specific verb and resource, and the description distinguishes this mutation from the sibling read tools get_ai_setup and update_ai_setup. An agent can tell immediately this is the service-area setter rather than the general AI-setup updater.

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

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

It states the prerequisite ("Call get_ai_setup first"), the required conversation flow (tell the user the exact places, get an explicit yes, then pass confirm: true), and the ordering rule that remove runs before add so one call can swap areas. Alternatives and when-not conditions (coverAll is "not combined with add or remove") are explicit.

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

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

Adds substantial behavior beyond the annotations: partial-update semantics ('Only the fields given are changed'), an authorization constraint for role/isInternalOnly, and a required human-confirmation step before the call. Annotations only say readOnly=false, destructive=true, idempotent=true, openWorld=false; the description supplies the operational constraints those hints cannot.

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 resource and the field list, then the constraints and the confirm protocol. Every clause earns its place; nothing is restated from 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?

A partial-update mutation tool with 7 params and an output schema present, so return values need no explanation. Permissions, confirmation, and which fields are optional are all covered; an agent has everything needed to invoke it correctly.

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

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

Schema coverage is 71% and the description reinforces the meaning of leadTimeMinutes (notice before a booking), travelBufferMinutes (gap around bookings) and isInternalOnly (name hidden from callers), which the schema largely already carries. It adds the cross-parameter rule that unspecified fields are left untouched, but adds no format detail 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 ('Changes') and resource ('a team member's settings') and enumerates the exact mutable fields. It also disambiguates sourcing of teamMemberId from the sibling list_team_members, so it is distinguishable from add_team_member or remove_team_member 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 a concrete call protocol ('tell the user who is being changed and how, and get their explicit yes; then pass confirm: true') and a permission prerequisite (only the account owner can change role or isInternalOnly). It does not explicitly name when to choose this over a sibling tool, 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.