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

The description goes well beyond the annotations by detailing the confirmation workflow, account-defaulted reply-to fields, preview behavior, and the two-step confirmToken fallback. This is exactly the kind of behavioral context an agent needs beyond readOnlyHint/destructiveHint.

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 well-structured sentences with the primary action front-loaded. Every sentence earns its place by explaining the non-obvious confirmation flow. No filler or redundant restatement.

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 and a non-trivial confirmation workflow, the description explains both supported paths: native confirmation prompts and the fallback confirmToken sequence. It covers defaults, previews, and the repeat call necessary to proceed, so an agent has what it needs to call the tool correctly.

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

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

Schema coverage is 100%, so the schema already documents each parameter. The description adds valuable meaning beyond that: defaulting behavior for email and phone, preview semantics, and strict rules for confirmToken usage. This meaningfully supplements the schema.

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

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

The description names a specific verb and resource: 'Send a message to Crown Town Compost customer support.' It clearly distinguishes itself from the sibling tools, none of which are message-sending tools. The title and description align without redundancy.

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

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

The description provides clear context for when to use the tool: whenever a message needs to be sent to customer support. It also gives practical usage flow with the confirmation requirement. It does not name alternatives explicitly, but no sibling tool is a viable alternative for this action.

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

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

The annotations already cover readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is established. The description adds a useful enumeration of returned fields, but beyond repeating 'read-only' it offers no additional behavioral context such as authentication requirements, rate limits, or response-shape caveats.

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 first sentence states the purpose and key returned fields; the second adds the read-only constraint and names the alternative tool. 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?

This is a simple read-only tool with zero required parameters and one optional enum fully documented in the schema. The description names the returned data categories and the mutation alternative, and the annotations cover safety. 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?

The schema description for the sole parameter, view, is detailed and complete: it explains compact/full response shapes, what gets stripped, and why there is no field projection. With 100% schema coverage, the description does not need to repeat parameter semantics, 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?

The description uses a specific verb, 'Get', and clearly identifies the resource: account contact details and notification preferences. It also distinguishes itself from the sibling update tool by contrasting read-only behavior with crowntown_update_account. Any agent can tell exactly what this tool does 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 explicitly says this tool is read-only and directs the agent to crowntown_update_account when changes are needed. This is an explicit when-to-use/when-not-to-use pairing that requires no inference about alternatives.

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, and the description redundantly states 'Read-only,' adding no new behavioral information. It does disclose the exact content returned, which is useful context, but does not go beyond what annotations provide regarding safety or idempotency. Since annotations cover the safety profile, the description adds marginal value here.

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

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

The description is a single, information-dense sentence that front-loads the main purpose ('Get your dashboard summary') and then lists the specific fields. It is efficient, with every item adding value. However, the enumeration is somewhat long and could be structured into a bulleted list for readability, but it remains clear and concise for a 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?

With no parameters and no output schema, the description bears the full burden of explaining what the tool returns. It lists all key dashboard components explicitly, making it complete for a simple read-only getter. It does not mention error conditions or data formatting, but these are not critical for a tool of this simplicity, and annotations already cover idempotency and read-only behavior.

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 description has no parameter explanations to add. With schema coverage trivially at 100% and no parameters, the baseline is 4. The description does not mention any inputs, which is correct for a no-argument getter.

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 retrieves the account dashboard summary and enumerates the specific data included (account status, subscription, service dates, addresses, environmental impact). This distinguishes it from siblings like get_account (which likely focuses on account details only) and list_upcoming_services (which focuses on service dates). The verb 'Get' plus the resource 'dashboard' is specific and unambiguous.

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

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

The description implies when to use it—when you need an overall dashboard summary—but does not explicitly contrast it with sibling tools like get_account or list_upcoming_services. There is no 'use this instead of X' guidance, leaving the agent to infer the tool's scope from the listed fields. Given the rich sibling set, explicit routing would be helpful, but the description provides enough context for a reasonable choice.

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 idempotentHint, covering safety and non-mutating behavior. The description adds context about the lack of a guaranteed window from the provider and that the window is empirical, which is valuable for setting expectations. No contradiction with annotations.

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

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

The description is a single, information-dense paragraph. It front-loads the core output and then explains the empirical nature and read-only attribute. Slightly long but justified given the complexity of the observed window concept; no fluff.

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

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

For a single-parameter, read-only tool with no output schema and full parameter schema coverage, the description covers what the tool returns, the empirical basis, and the absence of a guaranteed window. It lacks explicit detail on the return format (e.g., how the window is structured), but given the tool's simplicity and annotations, it is sufficiently complete for calling correctly.

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

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

The only parameter, history_sample, is fully described in the schema with a clear meaning and constraints (max 100, exclusive min 0, default 60). The description does not add further detail beyond referencing service history, but since schema coverage is 100%, the baseline of 3 is appropriate.

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

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

The description clearly states the tool retrieves the pickup schedule for each service address, listing specific fields (pickup days, next service date, set-out-by time, and observed arrival window). It is distinct from sibling tools like list_upcoming_services and list_service_history by focusing on schedule details and empirical 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?

The description implies its use when needing schedule details, especially the observed time window. It references service history for derivation, but does not explicitly state when to use this tool versus siblings like list_upcoming_services or list_service_history. However, the uniqueness of the empirical window is clear enough for 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 declare readOnlyHint, idempotentHint, and openWorldHint. The description reinforces read-only behavior and adds useful context by specifying error classification ('no creds' vs 'bad creds' vs 'site error') and the exact fields reported. This goes beyond what 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?

The description is a single, information-dense sentence that front-loads the main purpose ('Confirm credentials are configured') and efficiently covers steps, output, and error handling. It is not bloated, though it could be broken into two sentences for readability. Every clause adds value.

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 healthcheck with no input and no output schema, the description covers what it does, what it returns, and error classification. It also states read-only behavior. It doesn't mention rate limits or auth prerequisites beyond credentials, but these are minor given the tool's simplicity and the annotations already covering safety.

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 description need not explain any parameter meaning. Baseline for 0 params is 4. The description adds nothing about parameters (as none exist) but does describe output shape, which is not directly relevant to this dimension.

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 ('Confirm', 'log in', 'fetch', 'report') and resource ('Crown Town Compost portal'), and clearly differentiates it from siblings by framing it as a healthcheck. It explicitly lists the output fields, so an agent can instantly see it's a diagnostic tool, distinct from get_dashboard or get_account.

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 its usage for verifying credentials and connectivity but does not explicitly state when to use it versus alternatives like crowntown_get_dashboard or crowntown_get_account. There is no 'use when...' or 'don't use when...' guidance, though the purpose is self-evident from the title and 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, openWorldHint, and idempotentHint, covering safety and side effects. The description adds behavioral details beyond those: it mentions 'Paginated' and specifies the output fields (including Stripe links). This extra context is valuable and does not contradict any annotation.

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

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

The description is a single, well-structured sentence that front-loads the core action and then lists the key output attributes. Every phrase adds value—'Read-only' reinforces safety, 'Paginated' signals behavior, and the field enumeration sets expectations. No redundant or extraneous 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 simple read-only listing tool with fully documented parameters and rich annotations, the description provides sufficient context: it states what it lists, the fields included, pagination, and safety. An agent can call it correctly without needing additional details. It omits error handling or edge cases, but these are not critical for such a straightforward operation.

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

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

The input schema provides 100% coverage with descriptions for all three parameters (page, per_page, payable_only). The description does not add additional semantic meaning beyond what the schema already conveys, so it meets the baseline for high schema coverage.

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

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

The description clearly states the tool's purpose: 'List your Crown Town Compost invoices' and enumerates the specific fields returned (number, date, amount, status, payable flag, links). This verb-resource structure distinguishes it from sibling tools like list_service_history and list_upcoming_services, which serve different data domains.

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 usage for invoice-related queries but does not explicitly state when to use this tool versus alternatives, nor does it mention exclusions. The title 'List billing history (invoices)' reinforces the domain, but there is no direct guidance such as 'use list_service_history for services.' The context is clear but not explicit about selection criteria.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, which cover the read-only and safe nature. The description adds valuable behavioral context by mentioning pagination and status filtering, which are not in the annotations. It also repeats 'Read-only,' which is redundant but consistent. No contradictions with annotations; the added details enhance transparency beyond what structured data provides.

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

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

The description is a single, readable sentence that front-loads the core action ('List past collection stops') and then provides details on fields and capabilities. It is efficient with no fluff or repetition (except the redundant 'Read-only,' which is minor). The structure is clear and scannable, though it could be broken into two sentences for even better readability.

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 list tool with no required parameters and a rich schema, the description covers the essentials: what it returns (fields listed), how to filter (status), and pagination. It does not describe the exact response format, but no output schema is provided and the field list gives a good idea. Given the low complexity and safe read-only nature, it is sufficiently complete for an agent to call 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% with detailed parameter descriptions for page, status, and per_page. The description only mentions 'filterable by status' and 'paginated,' which restate what the schema already explains. Since the schema fully documents the parameters, the description adds no extra semantic value beyond confirming the behavior. 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?

The description clearly states the tool's purpose: 'List past collection stops for your account' with a specific verb and resource. It also enumerates the returned fields (date, status, collection time, weight, services rendered), which aids understanding. The word 'past' and 'history' distinguish it from the sibling 'crowntown_list_upcoming_services' without explicit naming, but the intent is unambiguous.

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

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

The description implies when to use it ('past collection stops') and the sibling for upcoming is named, but it does not explicitly state alternatives or exclusions. There is no direct statement like 'use this for past services, use list_upcoming_services for future ones.' The context is clear but not spelled out, so it falls short of an explicit usage guideline.

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 idempotentHint. The description adds value beyond those by disclosing the exact fields returned and that skipped items are included ('currently scheduled or already skipped'). No contradictions with annotations.

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

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

Two sentences, no filler: the first states the core action and scope, and the second adds the read-only boundary and routing hint. Every clause earns its place, and key identifiers are front-loaded.

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 zero parameters, the description carries the burden of explaining what the agent gets back. It covers the essential fields (rid, clid, service date, scheduled/skipped status). Minor omissions like ordering or date range are acceptable given the openWorldHint and the read-only nature.

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 schema coverage is trivially 100% and the baseline is 4. There is no parameter meaning for the description to add, but it usefully explains what the return items contain.

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

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

The description names a specific verb ('List'), a specific resource ('upcoming scheduled collection days from the service calendar'), and the exact payload each result carries ('rid, clid', service date, status). This clearly distinguishes it from sibling tools like crowntown_skip_service and crowntown_list_service_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?

The description explicitly frames the tool as read-only and directs the agent to crowntown_skip_service for mutations ('to actually skip/unskip'). It does not explicitly differentiate from get_pickup_schedule or list_service_history, but the skip-related purpose and pointer to the mutation sibling are enough to guide selection.

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

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

The annotations already indicate destructiveHint=true, readOnlyHint=false, and openWorldHint=true. The description significantly adds behavioral context by detailing the confirmation mechanism: it forces a user confirmation, and in the fallback mode, it requires a two-step process with a confirmToken. It also clarifies that the tool notifies staff and asks for confirmation first, which aligns with the destructive hint and adds depth. There is no contradiction; the description complements the annotations by explaining the exact confirmation flow.

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

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

The description is compact and front-loaded with the core purpose in the first sentence, immediately followed by the confirmation mechanism. It avoids redundancy and focuses on essential behavioral details. However, the mention of MCP_CONFIRM_MODE assumes the agent knows this external concept, which might not be universally understood; a slightly more explicit explanation could be helpful, but it is not overlong. Overall, it is concise and structured effectively.

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 (two-step confirmation, potential side effects) and the absence of an output schema, the description provides comprehensive guidance: it explains the action, the confirmation requirements, the parameter usage, and the fallback mechanism. It covers edge cases like clients without elicitation support and clarifies the confirmToken's lifecycle. An agent has all necessary context to invoke the tool correctly without additional information.

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 well-documented. The description additionally emphasizes the confirmToken parameter's critical usage rules: only in fallback mode, never on first call, never invented, and must be passed back from the phase-1 response. This adds crucial semantic meaning beyond schema definitions, especially for an AI agent that must handle the two-step flow correctly. It doesn't elaborate on 'date' or 'comment' beyond what's in the schema, but the coverage is sufficient.

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's action ('Report that a scheduled collection was missed') and identifies the resource (Crown Town Compost staff). It includes critical details about the confirmation flow, distinguishing it from other tools like 'crowntown_skip_service' which might be confused for reporting issues. The explicit mention of the two-step confirmation process clarifies a unique behavioral aspect, ensuring an agent understands what this tool does beyond its name.

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 implicitly indicates when to use this tool: when a scheduled collection was missed. It contrasts with the sibling 'crowntown_skip_service' by emphasizing 'missed pickup' rather than a planned skip. However, it does not explicitly state when NOT to use this tool (e.g., for scheduling changes). It also references MCP_CONFIRM_MODE, which is an external contextual signal, but does not fully explain alternatives for staff contact beyond 'contact_support', leaving some room for 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?

It clearly discloses the confirmation behavior: a native prompt when supported, otherwise a two-step preview-and-confirmToken flow. This goes well beyond the annotations and is essential for correct invocation.

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

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

Three tight sentences with no filler. The action is front-loaded, and the confirmation flow is summarized efficiently with a pointer to MCP_CONFIRM_MODE.

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

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

The description covers the core purpose, required parameters, and the non-obvious confirmation/token behavior. Together with the 100%-covered schema and annotations, an agent has enough to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds real value by tying rid/clid to crowntown_list_upcoming_services and summarizing when confirmToken is needed, supplementing the schema's detailed parameter docs.

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: 'Skip (or un-skip) an upcoming collection day.' This is clear and concrete, though it does not explicitly differentiate the tool from sibling tools such as crowntown_report_missed_pickup.

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 explicit guidance on where to get the required ids ('Pass the rid + clid from crowntown_list_upcoming_services') and explains the confirmation flow. It provides clear context but does not state when-not-to-use or name alternatives.

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?

Even though annotations already declare readOnlyHint=false and destructiveHint=false, the description adds valuable behavioral detail: partial-update semantics, verbatim re-saving, preview of current/resulting state, and the two-phase confirmation flow with confirmToken. This is exactly the kind of nuance structured annotations 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?

The description is front-loaded with purpose and each sentence adds behavioral value. It is a bit dense around the confirmation flow, but nothing is filler and the structure keeps the most important usage upfront.

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 six optional parameters and no output schema, the description thoroughly covers update behavior, preview, confirmation prompt, and token fallback. Minor gaps remain around what happens if no fields are provided and what the final success response looks like, but these are not critical.

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 adds meaning by clarifying that only specified fields are changed and by explaining when and how confirmToken is used in the two-step fallback, which goes beyond the schema's field-level descriptions.

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 opening sentence uses a specific verb ('Update') and a clear resource ('contact details and/or notification preferences'), and the description's 'Reads your current account form, changes ONLY the field(s) you specify' clearly distinguishes this write operation from read-only siblings like crowntown_get_account.

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 first sentence provides clear context for when to use the tool: when a user wants to change account contact details or preferences. It does not explicitly list alternatives or exclusions, but no competing update tool exists among the siblings, so the usage context is sufficient.

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