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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world. The description adds genuinely useful context beyond them: it reports real permission status, includes version info, and explicitly states it does not request permissions, which matters for a diagnostics 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?

A single front-loaded sentence covering the resources, followed by one behavioral caveat and a compact version/permission tag. No filler, though the bracketed metadata is slightly terse.

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 explained, and there are no parameters to document. The description covers scope, permission behavior, and version, leaving nothing an agent needs missing.

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

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

The tool takes zero parameters, so there is nothing for the description to clarify; baseline is 4. Schema coverage is 100% and the description correctly introduces no parameter discussion.

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 (Inspect) with concrete resources: helper, macOS permission status, configuration, version, native availability. An agent can tell what it returns. However, it does not differentiate itself from sibling bridge tools like bridge_list_capabilities or bridge_get_operation.

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

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

Usage is only implied: an agent would infer this is the diagnostic entry point. There is no explicit when-to-use or when-not-to-use guidance relative to the sibling bridge tools, though 'Does not request permissions' hints at a boundary.

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

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

Annotations already declare readOnly/idempotent/non-destructive/non-open-world, so the bar is lower, yet the description still adds value: it clarifies the call performs no re-execution, is a readback of saved state, and notes 'permissions: none'. It does not mention rate limits or failure modes, keeping it at a solid 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?

Two tight sentences, front-loaded with the core action and followed by usage context; no filler. The trailing version/permissions tag is metadata rather than description, which slightly dilutes the prose.

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 and annotations cover the safety profile, so the description need not explain return values. It adequately covers what the tool does and when to call it, leaving only minor gaps such as behavior on a missing or expired idempotency key.

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

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

Schema coverage is 100% and both parameters already carry descriptions ('Original write tool name', 'Original _idempotencyKey'). The description only echoes the notion of using the original name and key, adding little syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Read the status and saved result of a write') and clarifies it does so 'without executing it again', which conceptually separates it from re-running the sibling write tools. It stops short of naming any sibling, so it is clear but not fully differentiated.

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 conditions for use: 'while waiting for approval or resolving an uncertain result', and instructs the caller to reuse the original tool name and idempotency key. There are no explicit exclusions or named alternatives, but the triggering context is concrete.

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 read-only, idempotent, non-destructive, and non-open-world behavior. The description adds meaningful context beyond that: by default it returns compact metadata, includeSchemas expands to full input/output schemas, adapter narrows to one family, and no permissions are required. It does not mention rate limits or pagination, but for this simple read-only tool that is a minor gap.

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

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

The description is two sentences plus a bracketed version/permission note. It is front-loaded with the core purpose, then moves to parameter guidance, and contains no filler 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 discovery tool, the description covers purpose, parameter behavior, output-format choices, and permission context. An output schema exists, so return values need no further explanation. It could go slightly further by stating when an agent should call this before invoking sibling tools, but nothing critical is missing.

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

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

Schema description coverage is 0%, so the description must carry the burden. It explains both parameters: includeSchemas retrieves full input/output schemas, and adapter filters to one capability family. The enum values themselves are self-explanatory, though the description does not state defaults or that adapter accepts exactly one family.

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 clear verb and resource: 'Discover compact tool metadata.' The adapter enum families make the scope concrete (bridge, network, calendar, etc.), so an agent can distinguish this meta-tool from the specific action siblings. It falls short of a 5 because it doesn't explicitly contrast itself with those 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?

It provides parameter-level usage ('Set includeSchemas to retrieve full schemas', 'adapter to filter one capability family') but gives no explicit when-to-use guidance or conditions. The discovery purpose is implied by the name and description, but there is no stated alternative or trigger condition.

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

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

Annotations already declare the safety profile (readOnly=false, destructive=false, idempotent=true, openWorld=true), so the bar is lower. The description adds genuinely new context: the required 'calendar' permission and that it returns the persisted native ID. It stops short of explaining the approval/_idempotencyKey workflow, but the permission disclosure is real value beyond 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?

A single front-loaded sentence plus a compact bracketed metadata tag. No wasted words, and the core purpose is stated first.

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

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

With an output schema present and 100% schema coverage plus annotations covering safety, the description only needs purpose, scope, and permission context, all of which it supplies. The main gap is cross-tool routing guidance, which would round it out.

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

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

Schema description coverage is 100%, so all 9 parameters, including timezone, calendarId, and _idempotencyKey semantics, are already documented in the schema. The description adds no parameter-level detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Create a single, nonrecurring EventKit event') and scopes it to nonrecurring events, which distinguishes it from a recurring-create or update path. It does not explicitly name siblings like calendar_update_event, but the verb+resource pair 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?

No explicit when-to-use guidance and no named alternatives. The 'single, nonrecurring' scoping implies the tool cannot be used for recurring events, but the agent gets no routing help vs calendar_update_event, calendar_find_free_slots, or calendar_list_events.

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=true and readOnlyHint=false, so the safety profile is known. The description adds genuine context beyond them: the human-approval requirement, which explains the _approvalId gate and signals a non-immediate, two-step workflow, plus the 'one occurrence' deletion scope.

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

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

Two short sentences plus a version/permission tag; the destructive action, its scope and the approval precondition are all front-loaded with zero 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?

Output schema exists, so return values need not be explained, and the schema covers parameters. The description covers scope and the approval precondition, leaving only minor gaps such as whether deletion is reversible and how approval is obtained.

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

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

Schema description coverage is 100%, so the schema already documents id, _approvalId and _idempotencyKey fully. The description's 'one occurrence' phrasing hints that id targets an occurrence, but it adds no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb (delete) and resource (event), and adds the important scope qualifier 'one occurrence', which tells the agent this removes a single instance rather than a recurring series. It does not explicitly contrast with other calendar tools, but the resource 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 'Requires human approval' clause establishes a real precondition, but there is no explicit when-to-use guidance versus siblings such as calendar_update_event or any guidance on handling the approval/idempotency flow. Usage is implied rather than directed.

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/destructiveHint, so the safety profile is covered. The description adds real behavioral context beyond that: which events count as busy (non-free, non-cancelled), the selected-calendar scoping, the no-working-hours inference boundary, and the required 'calendar' permission.

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 tightly written clauses with the core action front-loaded and no filler; the version/permission suffix is the only low-value element.

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 annotations carry the safety profile. The description covers boundaries and scope well; the only gap is the unaddressed durationMinutes/timezone semantics for a 5-param 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 coverage is 60%. The description maps loosely to parameters ('requested range' → start/end, 'selected calendars' → calendarIds), but durationMinutes has an empty schema description and no compensating explanation, and timezone semantics are unaddressed. Baseline 3 for partial coverage that is only marginally compensated.

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

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

States a specific verb+resource ('Find free intervals') and clarifies the computation basis ('using non-free, non-cancelled calendar events'). This clearly distinguishes it from siblings like calendar_list_events, though it does not name an alternative explicitly.

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

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

The clause 'does not infer working hours' and 'Bound to selected calendars' give boundary conditions that imply the intended usage context, but there is no explicit when-to-use/when-not guidance or routing to sibling tools such as calendar_list_events.

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=true, so the safety profile is covered. The description usefully adds the permission scope ('permissions: calendar') and version, but the ambiguous 'write support' phrase sits awkwardly against the readOnly annotation and could confuse the agent.

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?

Extremely short and front-loaded, with the action first and metadata bracketed at the end. The only wasted corpus is the ambiguous 'and write support', but overall it is tight.

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 params, rich annotations, and an output schema, the description covers the essentials. What is missing is routing context relative to the other calendar tools and any clarification of what 'write support' means, which leaves a real gap for an agent choosing between siblings.

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?

Zero parameters with 100% schema coverage, so there is nothing for the description to compensate for; baseline 4 applies. No parameter syntax or format detail is needed.

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

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

States a clear verb+resource ('List EventKit calendars'), which is enough to distinguish it from calendar_list_events. However, the trailing phrase 'and write support' is vague and muddies what the tool actually does, leaving the agent unsure whether it merely lists calendars or also performs/reports something write-related.

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

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

No guidance on when to use this versus calendar_list_events, calendar_find_free_slots, or any sibling. The 'permissions: calendar' tag hints at a prerequisite but doesn't tell the agent anything about selection context or exclusions.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description still adds real value beyond them: the 366-day maximum span, the requirement for explicit UTC offsets and an IANA timezone, and the 'permissions: calendar' authorization requirement, none of which appear in the annotations.

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

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

Three compact clauses with the range bound and timezone requirement front-loaded before the version/permission tag. The bracketed metadata is marginally useful but is the only element not directly helping an agent call the 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?

With an output schema present, return values need no explanation, and annotations cover the safety profile, so the description is nearly sufficient. The remaining gaps are the undocumented 'limit' cap/behavior and whether calendarIds defaults to all calendars, which an agent would need to guess.

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?

At 60% schema coverage, the description reinforces the start/end/timezone formats already documented in the schema but adds the non-obvious 366-day span limit that the schema does not express. It says nothing about 'limit' (empty schema description) or what calendarIds defaults to, leaving part of the coverage gap unfilled.

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

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

States a specific verb and resource ('List events') plus a scoping qualifier ('intersecting a bounded time range'), which cleanly separates it from calendar_find_free_slots and calendar_list_calendars. It does not name any sibling explicitly, so it stops short of full differentiation.

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

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

There is no guidance on when to choose this tool over calendar_find_free_slots or calendar_list_calendars, and no stated exclusions. Only hard constraints (366-day bound, timezone requirement) are given, which are validation rules rather than usage routing.

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

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

Annotations already declare the full safety profile (non-readOnly, idempotent, non-destructive, openWorld). The description adds the recurring-series scoping behavior and the required 'calendar' permission, which are genuine additions not covered by annotations. It does not describe what happens to unspecified fields or any rate/permission failure behavior.

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

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

Two tight sentences with the operation and scope front-loaded, plus a compact permission/version tag. No filler, though the bracketed tag is slightly meta rather than task-oriented.

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 and annotations cover the safety profile, so the description needn't explain returns. With complete parameter documentation and an explicit permission requirement, an agent has enough to invoke it correctly; only sibling routing is left implicit.

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

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

Schema description coverage is 100%, so every one of the 10 parameters is documented in the schema itself (including _idempotencyKey reuse rules and calendarId defaulting). The description adds no parameter-level detail beyond the 'native ID' phrasing, so the baseline 3 is appropriate.

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

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

States a specific verb+resource ('Update one occurrence of an event') and its scope ('by native ID'), which clearly separates it from calendar_create_event and calendar_delete_event. It does not explicitly name those siblings, but the operation 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 line 'Recurring series are not bulk modified' implies the tool operates on a single occurrence rather than a whole series, which is useful scoping. However, it never states when to choose this over calendar_create_event/calendar_delete_event, and gives no prerequisites or exclusions beyond that hint.

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

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description still adds real value beyond them: plain-text-only format limitation, 'current' versus history scope, and 'permissions: none' as an auth requirement.

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

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

Two short sentences, front-loaded with the action and scope constraint. The bracketed '[v1.0.0; permissions: none]' tag is partly useful (permissions) but the version string is filler that slightly dilutes the signal.

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 annotations carry the safety profile. Scope, format limitation, and auth needs are all covered, leaving nothing an agent needs in order 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?

The tool takes zero parameters, so the baseline is 4 and there is no parameter semantics to document. The description correctly implies a no-argument call and adds no misleading parameter hints.

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 ('Read current plain-text clipboard') and narrows scope with 'only', which separates it from history-import behavior. It does not name the sibling clipboard_write, so the differentiation is scope-based rather than explicit routing.

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?

'Does not import Raycast Clipboard History' is an effective when-not boundary that tells the agent this tool is not the path for history retrieval. There is no positive statement of when to prefer it over alternatives such as system_get_selected_text, so the guidance stops just short of full routing.

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

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

Annotations already declare this as a write, idempotent, non-destructive, open-world operation. The description adds meaningful context beyond them: it only writes plain text, it replaces the existing clipboard contents, and it requires no permissions. It 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?

A single front-loaded sentence states the action and scope with no wasted words. The bracketed version/permission note is compact and does not obscure the core instruction.

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 write tool with an output schema, full parameter descriptions, and safety annotations, the description covers the essential purpose, text format, and permission level. It could more explicitly note the overwrite of prior clipboard contents or the optional human approval flow, but it is largely complete.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters, including the required idempotency key and optional approval ID. The description adds only the 'explicit plain text' qualifier for the text parameter, which is marginal; 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 ('Replace') and resource ('system clipboard'), plus the text scope ('explicit plain text'). It does not explicitly distinguish the operation from the sibling clipboard_read, but the action itself 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 gives no when-to-use guidance, no conditions selecting it over clipboard_read, and no exclusions. It only states what the tool does, leaving usage context entirely 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 write (readOnlyHint=false), idempotent (idempotentHint=true), non-destructive, and open-world behavior, so the safety profile is covered. The description adds useful context beyond that — the write lands in the 'default writable container' and requires the 'contacts' permission — but does not explain what an existing duplicate does or how the idempotency key behaves.

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?

Extremely compact: a single front-loaded purpose clause plus a bracketed metadata tag. No filler, and the verb+resource leads. The bracket tag is slightly cryptic but does not bloat the text.

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

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

For a simple create tool, the description covers purpose, target container, and the governing permission, while annotations cover safety and an output schema covers return values. Little an agent needs is missing beyond optional usage routing toward contacts_update.

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

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

Schema description coverage is 100%, so all six parameters (including givenName, _idempotencyKey, and _approvalId) are already documented in the schema. The description adds no field-level meaning beyond what the schema provides, so the baseline of 3 applies.

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

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

The description states a specific verb (Create) and resource (a contact), and narrows the target with 'in the default writable container'. It distinguishes itself from the read-oriented siblings (contacts_get, contacts_search) and the mutating contacts_update by virtue of being the sole create operation.

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

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

Usage is only implied: 'Create a contact' tells the agent what to do but gives no explicit when-to-use condition, no prerequisites, and no reference to alternatives such as contacts_update. The 'permissions: contacts' tag hints at an auth requirement but does not spell out the trigger conditions.

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 permission scope ('permissions: contacts') and the 'accessible' gating notion, which is real added context, but it says nothing about behavior for missing or inaccessible contacts.

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?

Very tight and front-loaded: the action and the identification method come first. The bracketed version/permission tag is slightly noise-like but carries permission 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?

An output schema exists so return details needn't be described, annotations cover the safety profile, and the single parameter is fully documented. Purpose, identifier method, and permission scope are all present; only edge-case behavior is left unstated.

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

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

Schema description coverage is 100% and the id parameter is fully documented as 'Stable native object ID'. The description's 'by identifier' corroborates but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (Read) and resource (contact) plus the identifier method, which distinguishes it from contacts_search and the mutation siblings contacts_create/contacts_update. It doesn't name a sibling explicitly, so it falls short of 5.

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

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

The phrase 'by identifier' implies the caller must already have an ID (as opposed to contacts_search which finds them), but there is no explicit when-to-use, when-not, or named alternative. Usage is only implied.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description earns credit for adding non-obvious context: results are basic fields only, limited-access contacts may come back incomplete, and it is gated behind the 'contacts' permission. This is exactly the kind of caveat 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?

Two tight sentences with the core action front-loaded, followed by a compact result caveat and a permissions tag. No filler, though the version bracket is mild boilerplate.

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

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

For a read-only search with an output schema and full annotations, the description supplies the one thing structured fields don't: that results may be partial for limited-access contacts. Missing only minor detail like ordering or pagination, which matters little alongside the limit parameter.

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

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

Schema description coverage is 50% — 'query' is documented as 'Name query' but 'limit' has an empty description, and the tool description never clarifies result-count behavior. 'By name' mildly reinforces the query meaning, so a 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 (Search) and resource (authorized Contacts) with a clear scope ('by name'). It is naturally distinguishable from contacts_get/contacts_create/contacts_update, though it never names a sibling explicitly.

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

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

The 'by name' scoping implies when this tool applies (name-based lookup), but there is no explicit when-to-use vs when-to-use-contacts_get guidance and no stated prerequisites. Usage is inferable but not spelled out.

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=true and openWorldHint=true, so the bar is lower, but the description adds non-trivial context: email/phone fully replaces that collection rather than appending, and the '[permissions: contacts]' tag discloses the authorization scope. It stops short of describing the human-approval gate implied by the _approvalId parameter and 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?

Two short sentences plus a metadata tag, front-loaded with the update scope and then the field-replacement rule. No filler; the only marginal element is the version/permission tag, which still carries operational 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?

An output schema exists, so return values need no explanation, and the description covers the partial-update contract, replacement semantics and permission scope. The main omission is the approval/idempotency workflow, which is left entirely to the schema's parameter descriptions.

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

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

Schema description coverage is 100%, so the schema already documents all seven parameters, making 3 the baseline. The description reinforces which fields are updatable (name, email, phone) and clarifies replacement semantics for two of them, but adds no syntax or validation 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 (update) and resource (contact), and scopes it to 'only specified ... fields', which distinguishes a partial patch from a full replace. It never names a sibling such as contacts_create or contacts_search, so the differentiation comes from the name rather than the text.

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

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

There is no explicit when-to-use, when-not-to-use, or alternative routing guidance. The phrase 'only specified' implies partial-update behavior, but an agent gets no signal about when this beats contacts_create or what prerequisites (existing contact id, approval) apply.

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 declare readOnly=false, idempotent=true, and destructive=false, so the safety profile is partly covered. The description adds genuinely new context: the operation is confined to authorized roots, it refuses to overwrite, and it requires no permissions, which is useful beyond the structured hints.

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?

It is short and front-loads the core action, but the second sentence about 'Rename' is out of place and misleading for a copy tool, so it does not fully earn its place. The version/permissions tag is compact metadata but adds little.

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, and annotations cover the safety profile. The description supplies the scope constraint and overwrite behavior, making it largely complete, though the missing when-to-use guidance leaves a small gap.

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

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

Schema description coverage is 100%, so the schema already documents source, destination, _approvalId, and _idempotencyKey. The description only restates that destination is an absolute path, adding nothing beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('copy file') plus a scope constraint ('inside authorized roots') and a behavior ('refuse overwrite'), which distinguishes it from siblings like finder_move_file and finder_rename_file. The trailing sentence 'Rename accepts a destination absolute path' is confusing because it references a different operation name, slightly muddying the purpose.

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 constraints but no when-to-use guidance or routing against alternatives such as finder_move_file or finder_rename_file. An agent must infer from the name alone when a copy is preferred over a move or rename.

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=true and destructiveHint=false, so the safety profile is covered structurally. The description adds that only a 'single' directory is created (implying non-recursive behavior) and notes 'permissions: none', but omits approval triggers, overwrite behavior for existing paths, and error semantics that matter for a write 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?

The operative sentence is front-loaded and wastes no words. The bracketed version/permission tag '[v1.0.0; permissions: none]' is metadata clutter of limited value, but the description remains short and readable.

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 and annotations cover the safety profile, so return values need not be described. However, for a write operation whose schema exposes an _approvalId gate, the description leaves the approval path and failure modes unexplained, which is a meaningful gap for correct invocation.

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

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

Schema description coverage is 100%, so all three parameters including _idempotencyKey and _approvalId are documented in the schema itself. With no params needing description compensation and the description aligning with the schema's 'authorized roots' wording, the baseline is met and slightly exceeded by reinforcing the root constraint.

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

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

States a specific verb and resource ('Create a single directory') and constrains scope with 'within an authorized root'. This distinguishes it from the other finder mutation siblings like finder_write_file and finder_move_file, though no sibling is named explicitly.

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

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

The phrase 'within an authorized root' implies a precondition, and the schema's _approvalId parameter hints at an approval workflow, but the description never states when to use this tool versus alternatives or when an approval ID is required. Usage is only inferable.

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

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

Annotations already carry the safety profile (readOnly, idempotent, non-destructive), but the description adds genuine behavioral value: it will not follow directory symlinks and it requires no permissions ('[permissions: none]'). It omits pagination/ordering context tied to limit.

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 carries the scope and symlink constraint, followed by compact version/permission metadata. No wasted prose, though the bracketed tag is tangential to tool selection.

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 explained, and the description covers scope, symlink behavior, and permissions. The undocumented limit parameter and lack of ordering/pagination context leave a gap for a 500-max listing tool.

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

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

Schema coverage is only 50% (path is documented, limit has an empty description), and the description adds no parameter meaning at all. It does not explain what limit controls or how it interacts with the non-recursive listing.

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

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

States a specific verb (list) and resource (immediate directory entries) with scope qualifiers ('within authorized roots', 'without following directory symlinks'). The 'immediate' (non-recursive) wording implicitly separates it from finder_search_files, but no sibling is named explicitly.

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

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

There is no explicit when-to-use or when-not guidance, nor any reference to the obvious alternative finder_search_files. The agent must infer that this is for shallow listings and search is for recursive lookups.

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 idempotentHint=true, destructiveHint=false and readOnlyHint=false, so the safety profile is largely covered. The description does add genuine behavior beyond that: the operation is confined to 'authorized roots' and refuses to overwrite an existing destination. It omits the human-approval flow implied by the _approvalId parameter and the 'permissions: none' note, which is a meaningful gap for a mutation.

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

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

Short and front-loaded with the core action, but the middle sentence about 'Rename' is confusing noise for a tool named move_file, and the trailing '[v1.0.0; permissions: none]' bracket is metadata that does not help an agent decide or invoke.

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 and annotations covering safety/idempotency, the description need not explain return values. Still, it leaves the approval/idempotency-key workflow and the move-vs-rename-vs-copy choice unexplained, which an agent needs for correct invocation in a mutating filesystem toolset.

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

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

Schema description coverage is 100%, so the schema already documents source, destination, _idempotencyKey and _approvalId in detail; baseline is 3. The description adds little parameter-level meaning, and its 'destination absolute path' phrasing is already stated 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 (move) and resource (file) plus two meaningful constraints: 'inside authorized roots' and 'refuse overwrite'. However, the second sentence ('Rename accepts a destination absolute path') references a different sibling tool (finder_rename_file), which muddies the identity rather than sharpening the distinction from finder_copy_file/finder_rename_file.

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

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

No explicit when-to-use guidance and no routing to alternatives such as finder_copy_file (preserve original) or finder_rename_file. The only contextual cue is the misplaced 'Rename accepts...' sentence, which reads as belonging to another tool rather than as guidance for this one.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=true, so the safety profile is covered. The description adds the scoping constraint that only files under user-authorized roots can be opened and notes 'permissions: none', which is useful, but it omits the human-approval flow implied by the _approvalId parameter and any side effect of launching an external app.

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

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

A single front-loaded sentence with no wasted prose. The bracketed '[v1.0.0; permissions: none]' tag is metadata noise that slightly dilutes an otherwise tight statement.

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 explained, and the annotations carry the safety profile. The remaining gap is that the description never surfaces the approval/idempotency mechanics of a side-effecting open action, but it is adequate for correct invocation.

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 path, _approvalId and _idempotencyKey are fully documented in the schema. The description adds only the 'authorized file' notion, which overlaps the path description already in the schema; baseline 3 is appropriate.

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

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

States a specific verb (open) and resource (authorized file) plus the mechanism (default app), which implicitly separates it from finder_read_file (reads contents) and system_open_app (launches an app). It does not explicitly name those siblings, so differentiation is inferable rather than stated.

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

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

There is no when-to-use guidance, no exclusions, and no alternatives named. The word 'authorized' hints at a precondition but the description never says when to choose this over finder_read_file or system_open_app.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful behavioral facts beyond them: UTF-8 encoding only, a 1 MiB maximum, and the authorized-roots boundary with permissions: none. What it lacks is any note on error behavior for files outside roots or exceeding the size limit.

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 carrying the resource, encoding, scope, and size limit, followed by compact bracketed metadata. No wasted words; the operative constraint appears first.

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

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

For a simple, fully-annotated read tool with a 100%-covered single parameter and a declared output schema, the definition is nearly complete. Only the failure-mode behavior (missing file, out-of-root path, oversize file) is left unstated, which is a minor omission.

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

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

Schema description coverage is 100% and the single path parameter is already documented as an absolute path within authorized roots, so the schema carries the load. The description's 'within authorized roots' phrasing echoes the schema rather than adding format or edge-case detail, making the baseline 3 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 (Read) and resource (UTF-8 text file) plus scope (within authorized roots) and a size bound, so the agent knows exactly what the tool does. It does not, however, distinguish itself from siblings like finder_open_file or finder_search_files, which is why it falls short of a 5.

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

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

The description gives no when-to-use or when-not-to-use guidance and never names an alternative (e.g. finder_search_files for locating a file, finder_open_file for launching one). With over 60 sibling tools, the absence of routing guidance for a read operation is a real gap.

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 non-read-only, idempotent, non-destructive behavior, so the bar is lower, yet the description still adds real value: it discloses the authorized-roots boundary and the refuse-on-overwrite rule, which explains a non-obvious failure the annotations do not cover. It omits cross-volume/atomicity behavior and the human-approval path implied by _approvalId.

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

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

Two short sentences with the operational constraints front-loaded and no padding. The trailing '[v1.0.0; permissions: none]' metadata is low-value noise for selection purposes, keeping it out of the top score.

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 explained, and annotations plus 100% schema coverage carry most of the burden. The description adds the two things an agent most needs here, the authorized-roots boundary and the no-overwrite rule, so it is nearly complete for a simple rename 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?

Schema description coverage is 100% and all four parameters are documented in the schema, including the required _idempotencyKey and optional _approvalId. The description only restates that destination is an absolute path, which the schema already says, so baseline 3 applies.

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

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

States a specific verb (rename) and resource (file) plus a scope constraint (inside authorized roots) and a behavioral guarantee (refuse overwrite). It does not explicitly differentiate itself from the sibling finder_move_file, which is the closest alternative an agent would consider, so it falls short of a 5.

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

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

The 'inside authorized roots' clause implies a precondition and 'refuse overwrite' implies a failure mode, which gives some implicit guidance. However, it never states when to pick this over finder_move_file or finder_copy_file, nor what to do when the destination already exists, so usage must be inferred.

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 read-only, idempotent, non-destructive, non-open-world behavior, so the safety profile is covered. The description adds genuinely new behavioral facts beyond them: a 10,000-visited-entry traversal cap, the fact it avoids the private search index, and an explicit 'permissions: none' claim.

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

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

Three compact sentences with the core action front-loaded, followed by the scope exclusion and metadata tag. Little waste; the version/permissions tag is arguably extraneous but small.

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 annotations carry the safety profile. The description covers scope, traversal bound, and a permission note; the only real gap is the unstated semantics of the limit parameter.

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

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

Schema coverage is 67%: path and query are documented in-schema, while limit has an empty description. The description reinforces that the query matches filenames, but it does not clarify the limit parameter or its distinction from the 10,000-entry traversal cap. Baseline 3 fits a schema doing most of the work.

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

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

States a specific verb (search) and resource (filenames) with a scope qualifier ('recursively within authorized root'), which implicitly separates it from directory-listing siblings like finder_list_files. It does not explicitly name a sibling alternative, so it falls just short of full differentiation.

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

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

The recursion scope and 'does not access Raycast private search index' line imply when this tool applies versus other finders, but there is no explicit when-to-use/when-not guidance or named alternative (e.g. finder_list_files for non-recursive listing). Usage must be inferred.

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/idempotentHint, but the description adds genuinely useful nuance: trashing is reversible (no permanent deletion) and requires no permissions. It does not explain the human-approval flow implied by the _approvalId parameter, which is the main remaining gap.

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

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

Effectively one front-loaded sentence plus a short metadata tag. The bracketed '[v1.0.0; permissions: none]' is terse and slightly ambiguous but doesn't bury the core action.

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 annotations cover the safety profile. The reversible-deletion clarification is present; only the approval/idempotency operating context is left entirely to the 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 100%, so the schema documents path, _approvalId, and _idempotencyKey fully. The description adds no parameter-level detail (path root constraints, idempotency reuse semantics), so baseline 3 is correct.

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

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

States a specific verb and resource ('Move a file to macOS Trash') plus the mechanism used, which distinguishes it from siblings like finder_move_file or a hypothetical hard-delete. An agent can tell what it 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?

Usage is only implied: 'no permanent deletion' hints this is the safe/reversible alternative to a real delete, but no explicit when-to-use vs finder_move_file or any exclusion is given. Adequate but leaves routing 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 the write/safe/idempotent profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), and the description adds real value beyond them: the no-overwrite guarantee and UTF-8 encoding are behavior an agent must know before invoking. It omits error semantics (what happens when the file exists) and approval-related behavior, keeping it from a 5.

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

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

A single front-loaded sentence carries the core semantics, with version and permission notes bracketed at the end. It is efficient, though the bracketed metadata is marginally useful to an agent selecting a 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?

Given an output schema exists and 100% schema coverage, the description supplies the key non-schema facts (encoding, no-overwrite, permissions: none). The main gap is the failure mode when a file already exists and how the approval flow interacts with the call.

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% – path, content, _approvalId, and _idempotencyKey are all documented in the schema, including the reuse rule for the idempotency key. The description adds no parameter-level detail, so the baseline 3 applies.

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

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

"Create UTF-8 text file" gives a specific verb plus the exact resource and encoding, which separates it from siblings like finder_create_directory or finder_copy_file. It stops short of naming an alternative sibling, so it is clear but not fully differentiated.

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 only usage signal is the implicit constraint that it will not overwrite existing files, which hints at a failure case but names no alternative tool for overwriting or for reading an existing file. No explicit when-to-use or when-not-to-use guidance is provided.

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

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

Annotations already cover the safety profile (readOnly=false, destructive=false, idempotent=true, openWorld=true), so the bar is lower. The description adds meaningful context: the message is unsent, delivery is a separate high-risk action, and it discloses the automation:Mail permission 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 compact sentences with zero waste; the core action and the delivery caveat are front-loaded, and the metadata tag is deferred to the end.

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-value documentation is unnecessary, and permissions plus idempotency behavior are noted. Complete for invocation, though it says nothing about approval flow (the _approvalId param implies human approval) which a draft write could surface.

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

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

Schema description coverage is 100%, so all five parameters (including _idempotencyKey and _approvalId) are already documented in the schema. The description adds no parameter-level meaning, which is the correct baseline when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Create an unsent outgoing message in Mail') plus the return value ('return its scripting ID'). The 'unsent' qualifier and 'Delivery is a separate high-risk action' cleanly separate it from the mail_send sibling.

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 signals that this tool composes but does not deliver, routing the agent away from send semantics. It does not name the alternative (mail_send) directly or state exclusion conditions, so a small inference remains.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description still adds two things those annotations do not: the required automation:Mail permission and the scope restriction to the current inbox. It does not describe failure behavior for out-of-scope IDs, which keeps it from a 5.

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

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

One compact sentence carries the operation, key, and scope, with the permission metadata bracketed at the end. Front-loaded and waste-free, though the version/permission tag is boilerplate that could be trimmed if the runtime already surfaces it.

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

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

An output schema exists, so return values need no explanation, and this is a single-parameter read-only tool. Scope, key semantics, and auth requirement are all present; only the ID-provenance path (mail_search) and out-of-scope error handling are absent.

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

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

Schema description coverage is 0% — the id parameter is a bare integer with an empty description. The phrase "numeric Mail ID" and "limited to current inbox scope" do clarify that the integer is a Mail ID scoped to the inbox, which is real added meaning, but the description doesn't explain how to source the ID or what happens if it isn't an inbox message.

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 ("Read one inbox message") and identifies the lookup key (numeric Mail ID), which clearly separates it from mail_search, mail_send, and mail_create_draft. It stops short of naming an alternative sibling explicitly, so it lands at 4 rather than 5.

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

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

"limited to current inbox scope" implies when this tool is appropriate (inbox messages only) and implicitly excludes other mailboxes or search-driven retrieval. However, it never states how to obtain the ID or routes the agent to mail_search when the target isn't in the inbox, leaving usage 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 establish the safe read-only/idempotent profile, and the description adds genuinely new behavior: it bounds reads to the most recent 500 inbox messages and discloses the required automation:Mail permission. These are constraints an agent cannot derive from the annotations or schema.

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

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

Two tightly packed sentences plus a standard version/permission tag; the scope and the 500-message cap are front-loaded. Nothing is wasted, though the metadata bracket is boilerplate rather than substance.

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 described. For a two-parameter search tool the description covers scope, matching semantics, read bounds, and permissions; only the limit parameter's meaning is left unexplained.

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% – the 'limit' parameter has an empty description while 'query' is covered. The description clarifies that matching is a subject substring, which adds real meaning for the query, but it never explains the limit parameter or notes that it is capped at 100 while 500 messages are scanned.

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

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

States a specific verb ('Search'), resource ('inbox messages'), and matching scope ('subject substring'), which already sets it apart from mail_read. It does not explicitly name siblings, but the inbox/subject-substring scoping is concrete enough that an agent can identify it.

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

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

No when-to-use or when-not-to-use guidance, and no mention of alternatives like mail_read for opening a specific message. The scope constraints imply a scenario but the agent must infer routing itself.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, so the safety profile is covered. The description earns credit by adding the approval-workflow requirement and the permission scope ('automation:Mail'), which annotations do not convey.

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

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

Three compact clauses, front-loaded with the core action before the approval caveat and metadata. The bracketed version/permission tag is slightly noisy but does not bury the essential 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?

An output schema exists, so return values need no explanation, and the schema fully documents parameters. The description supplies the approval precondition and permission scope, leaving little an agent needs missing.

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

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

Schema description coverage is 100%, so every parameter including _approvalId and _idempotencyKey is documented in the schema itself. The description names recipient, subject and body but adds no syntax, format or constraint detail beyond what the schema already provides.

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 opens with a specific verb and resource ('Send exactly this recipient, subject and body using Mail') and the word 'exactly' pins down scope. It implicitly distinguishes itself from the sibling mail_create_draft by noting it never auto-sends a draft.

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 key precondition ('Requires separate human approval; never auto-sends a mutable draft'), which tells the agent this is only invoked after a human gate. It stops short of naming mail_create_draft as the alternative path for staging a message, so routing is clear but not fully 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 already declare it a non-destructive, idempotent, open-world write, so the safety profile is covered. The description adds useful context beyond annotations by disclosing the required permission (automation:Music) and version, but stays silent on the human-approval flow implied by _approvalId, which is meaningful for a write 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?

A single front-loaded sentence with the action set stated up front, plus a compact bracketed metadata tag. No wasted prose, though the action enumeration is redundant with the schema enum.

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, and annotations cover the safety profile. However, for a write tool that requires an idempotency key and supports a human-approval ID, the description omits any mention of the approval/retry behavior an agent needs 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 67%, and the description's enumeration of the action values merely restates the enum already defined in the schema. It adds no syntax or meaning for _approvalId or _idempotencyKey, so it does not compensate for the uncovered portions of 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 (Control) and resource (Music playback), and enumerates the four transport actions, so an agent can tell this is playback transport control rather than library browsing. It does not, however, distinguish itself from the sibling music_play_track, leaving ambiguity about which to prefer.

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 lists the fixed actions but gives no when-to-use guidance, no prerequisites, and no alternative tools. With music_status, music_search, and music_play_track as siblings, an agent must infer on its own when this tool is the right 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=false, idempotentHint=true, destructiveHint=false, and openWorldHint=true. The description adds the automation:Music permission requirement and a version tag, which is genuine value beyond the annotations, but it says nothing about the approval flow implied by _approvalId or what playback state results.

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 sentence with the action front-loaded, followed by a compact metadata bracket. Nothing is redundant, though the bracketed version tag is of limited use to an agent.

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, and annotations cover the safety profile. The permission note closes the main auth gap; the only remaining omission is behavior when the ID does not resolve to a track.

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 67%; the required 'id' parameter has an empty schema description, and the phrase 'by database ID' is the only thing giving it meaning. The other two parameters are documented in the schema itself, so the description neither compensates fully nor adds much beyond 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?

States a specific verb ('Play') and resource ('a track in the local Music library') plus the lookup key ('by database ID'), which is enough to distinguish it from music_search and music_control. It does not explicitly name those siblings, so it falls short of a 5.

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

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

The description gives no when-to-use guidance, no mention of when to prefer music_control or music_search, and no prerequisites or exclusions. An agent must infer the boundary from the name alone.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new context by naming the required permission scope (automation:Music) and pinning a version, which helps an agent anticipate authorization failures. It does not need to describe returns since an output schema exists.

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

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

Two tight sentences with the core purpose front-loaded and the scope exclusion immediately after. The bracketed version/permission tag is compact but is metadata that only partially earns its place for an agent deciding how to call the 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?

With rich annotations and an existing output schema, the description's job is narrow and it largely succeeds: purpose, scope, and required permission are all stated. The only material omission is the undocumented 'limit' parameter, which leaves a small gap for a two-parameter 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 coverage is only 50%: 'query' is documented as 'Track name' while 'limit' has an empty description in both schema and description text. The description's 'by track name' merely restates the schema's query description and says nothing about limit's range or default, so it fails to compensate for the 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 ('Search') and resource ('local Music library') and then narrows scope with 'by track name; does not search streaming catalog.' That exclusion makes the boundary unambiguous, and no sibling (music_status, music_play_track, music_control) competes as a search tool, so an agent can select this 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 phrase 'does not search streaming catalog' functions as an implicit when-not condition, which is useful routing information. However, it names no alternative tool or explicit when-to-use context, so usage must be inferred rather than read.

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

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

Annotations already declare readOnly/idempotent/non-destructive and open-world. The description adds value beyond that by disclosing the required permission ('automation:Music') and the behavioral edge case that playback may not be present, so the agent knows a null/empty result is possible rather than an error.

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

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

Two compact sentences with the core action front-loaded and the version/permission metadata bracketed at the end. No filler, every clause carries information.

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

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

An output schema exists, so return values need not be documented, and there are no parameters to explain. The description covers purpose, the absence edge case, and the permission requirement, which is sufficient for a simple 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?

The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing for the description to clarify beyond the fact that no arguments are needed.

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

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

States a specific verb and resource: 'Read Music playback state and current track'. An agent can distinguish this read-state tool from music_search, music_play_track, and music_control by their names, though the description never explicitly names a sibling or states the contrast.

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?

'when present' implies this is the tool to poll for current playback status, which is contextually implied by the music_* sibling set. However, there is no explicit statement of when to use this versus music_control (which may also read/modify state) or any exclusion guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world behavior, so the bar is lower. The description adds real context: partial-failure semantics ('HTTP failures remain visible'), a security boundary (no private/loopback probing), and a permissions note. Return contents ('DNS addresses, timings and HTTP status') partly duplicate the output schema.

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

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

Three tight sentences with the core capability front-loaded, followed by return content and then the safety constraint. The trailing '[v1.0.0; permissions: none]' tag is slightly noisy but compact and arguably useful metadata.

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 needn't be explained, and rich annotations cover the safety profile. The description still conveys scope, failure behavior, and permissions, leaving little an agent needs that is missing. Only the lack of sibling routing keeps it from 5.

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

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

Schema description coverage is 100% and each parameter is self-documented (url, http, timeoutMs including redirects and default). The description's 'optionally check its HTTP connectivity' loosely mirrors the http flag but adds no format or interaction detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource: 'Resolve a public HTTP(S) URL and optionally check its HTTP connectivity.' An agent immediately knows this is a DNS/HTTP diagnostic. It does not differentiate itself from adjacent diagnostic siblings such as bridge_diagnostics, so it falls short of a 5.

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

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

Usage is only implied (diagnostics) and no alternative tool is named for connectivity/HTTP work, e.g. web_fetch. It does provide a genuine 'when-not' in 'Never probes private or loopback networks,' which narrows the applicable input space, but there is no explicit routing to 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?

Annotations already declare the mutation/idempotency/scope profile, and the description adds real value beyond them: it discloses a concrete failure mode ("Locked notes may reject access"), notes that text is safely encoded, and surfaces the required permission scope (automation:Notes). It does not discuss what an append does to note structure or encoding edge cases, keeping it from a 5.

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

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

Two tight sentences with the action front-loaded and the failure caveat second; the trailing version/permission bracket is standard metadata. "Safely encoded" is slightly opaque, which costs a point, but there is no padding or repetition.

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

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

With an output schema present, return values need no explanation, and annotations plus a 100%-covered schema carry the safety and parameter burden. The description closes the main remaining gap by flagging the locked-note failure mode; only explicit sibling routing is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds only the "plain text" and "safely encoded" framing, which is consistent with but not richer than the schema's own "Plain text to append" description; nothing new about id, idempotency key, or approval id is contributed.

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?

"Append safely encoded plain text to an existing note" gives a specific verb (append) and resource (note), and the phrase "existing note" implicitly separates it from notes_create. It stops short of naming its siblings explicitly, so the differentiation is inferred rather than stated.

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

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

The description offers no guidance on when to use this versus notes_create or notes_get, nor any prerequisites beyond a passing mention that locked notes reject access. The agent must infer the routing decision from the tool name alone.

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

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

Annotations already declare the write/idempotent/open-world safety profile, and the description adds genuinely useful behavior: plain text is safely encoded as HTML, and the operation requires the automation:Notes permission. It omits any mention of the human-approval path that the _approvalId parameter implies, but it goes beyond 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?

A single front-loaded sentence plus a compact bracketed version/permission tag; nothing is wasted. Slightly terse given it is the only prose the agent gets.

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 annotations cover the safety profile. The description covers scope, encoding and permissions; the only gap is that it never hints at the approval workflow that gates the write.

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 title, text, _approvalId and _idempotencyKey are all documented in the schema. The description only echoes the plain-text encoding idea already present in the text field description, adding no new parameter semantics.

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 ("Create a note") and narrows the scope to "the default Notes account", which lets an agent distinguish it from notes_append or notes_get. It does not explicitly name sibling alternatives, so it falls short of a 5.

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

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

There is no explicit when-to-use or when-not-to-use guidance and no mention of the approval/idempotency prerequisites for this write. The agent must infer that creation (rather than notes_append) is the right call from the tool name alone.

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

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), so the bar is lower. The description adds genuinely non-redundant context: the required Automation permission for Notes and the fact that the body is returned as HTML rather than plain text.

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 core action in one sentence, with version and permission metadata tucked into a compact bracket. No wasted prose, though the bracketed metadata is slightly noisy relative to the semantic 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?

With an output schema present, the description needn't explain return values, and it helpfully signals the HTML format and required permission. An agent has enough to call it correctly, with only the sibling-routing guidance absent.

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

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

There is a single required 'id' parameter with 100% schema description coverage, so the schema already carries the semantics. The description adds nothing about the ID's format or origin, so this sits at the baseline 3.

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

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

The description states a specific verb and resource: 'Read note body as HTML', plus the mechanism (native Notes scripting interface). It's distinguishable from notes_create/notes_append by naming a read of the body, but it never explicitly contrasts with notes_search, so it stops short of full sibling differentiation.

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

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

There is no when-to-use guidance and no mention of when to prefer notes_get over notes_search or any other alternative. The agent must infer usage entirely from the name and the returned format.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so the safety profile is covered. The description adds genuinely new context beyond that: it operates through the public AppleScript dictionary, returns IDs and titles rather than private database contents, and requires the automation:Notes permission. It omits pagination/limit behavior, which is a minor gap given the annotations.

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

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

Three compact clauses with the purpose front-loaded and no wasted sentences. The bracketed version/permission tag is administrative but carries useful invocation context. Slight density of metadata keeps it from a 5.

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

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

An output schema exists, so return values need not be fully described, and annotations cover the safety profile. Combined with the permission requirement and title-scope note, an agent has enough to call it correctly. The undocumented limit parameter is the one remaining gap.

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

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

Schema coverage is 50%: 'query' is documented as 'Title substring' but 'limit' has an empty description. The description's phrase 'Search note titles' reinforces that query matches titles, consistent with the schema, but it says nothing about the limit parameter or the maximum of 100. It only partially compensates 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 ('Search') and resource ('note titles in Notes'), and adds a distinguishing scope constraint: it searches titles, not note contents. That cleanly separates it from notes_get, notes_create, and notes_append. It stops short of naming any sibling explicitly, so it is a clear-but-not-routing 4.

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

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

Usage is implied by the tool name and the title-scope note: use it to locate notes by title. However, there is no explicit when-to-use guidance and no pointer to notes_get for retrieving content, which is the natural next step an agent would need. Adequate but with a clear gap.

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 write, idempotent, and non-destructive behavior, so the description only needs to add context. It contributes the return contract ('return saved record') and the required permission scope, but says nothing about the human-approval path implied by the _approvalId parameter or how idempotency keys must be reused.

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

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

Two short clauses with the action front-loaded and no filler; the trailing version/permission tag is compact. It is appropriately sized, though the bracket tag is boilerplate rather than informative.

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 output schema covers return values and the annotations cover the safety profile, so those gaps are excused. What remains missing is the toggle direction of `completed`, the relationship to reminders_update_task, and any note on the approval workflow for a write 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 75%, so the schema already documents id, _approvalId, and _idempotencyKey. The phrase 'completion state' loosely maps to the bare `completed` boolean (the one undocumented parameter), but it never clarifies that setting it false reverses completion, which is the key semantic ambiguity.

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 ('Set a reminder completion state') plus the return behavior ('return saved record'), so the agent knows exactly what operation runs. It does not, however, distinguish itself from the sibling reminders_update_task, which could plausibly also set a completion field.

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

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

There is no when-to-use guidance, no indication that completed=false is how you un-complete a task, and no mention of when to prefer this over reminders_update_task or reminders_delete_task. The agent must infer the routing decision entirely from the name.

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, idempotent, open-world write. The description adds two things beyond that: the timezone dependency for due dates and the required 'reminders' permission scope. It does not mention the human-approval path implied by the _approvalId parameter, which is notable for a write tool, keeping this at a 3.

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

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

A single front-loaded sentence with zero filler; the constraint is stated immediately after the verb. The bracketed version/permission tag is somewhat metadata-like, but it carries scope information useful to the caller.

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 described, and the idempotency/approval parameter semantics live in the schema. However, for a write tool that carries an _approvalId parameter, the description never tells the agent an approval may be required or how the approval flow interacts with the idempotency key, leaving a real gap.

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

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

Schema description coverage is 88%, so the schema already documents title, notes, listId, timezone, and idempotency semantics; baseline is 3. The description does add one genuinely cross-field constraint not encoded in the schema (a due date requires a timezone), but only for a single parameter family, so it does not rise above 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?

States a specific verb ('Create') and resource ('a reminder'), so an agent can distinguish it from reminders_list_tasks and reminders_update_task by intent. It stops short of explicitly naming the sibling it is not (e.g. use reminders_update_task to modify an existing reminder), so it earns a 4 rather than a 5.

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

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

Usage is only implied by the verb 'Create' plus the prerequisite 'due dates require timezone', which tells the agent something must be supplied for dated reminders. There is no explicit when-to-use/when-not guidance against reminders_update_task or reminders_complete_task, so this is the minimum-viable tier.

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=true and openWorldHint=true. The description adds meaningful context beyond them: the operation is irreversible ('permanently') and gated on a human approval workflow, which is behavioral context the annotations do not convey.

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

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

Two short clauses with the destructive verb and the approval requirement front-loaded, plus a compact version/permissions tag. No wasted prose, though it is terse to the point of omitting guidance.

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, and annotations plus the approval note cover the safety profile. For a destructive write gated on human approval, this is nearly complete, though it omits any reference to the idempotency/approval-key mechanics that the schema documents.

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

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

Schema description coverage is 100%, so the schema already documents id, _approvalId and _idempotencyKey thoroughly. The description adds no parameter-level detail, so the baseline 3 applies.

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

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

States a specific verb+resource ('Permanently delete a reminder'), and 'permanently' distinguishes it from softer alternatives like reminders_complete_task. It does not explicitly name a sibling, but the scope 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?

Mentions that deletion requires 'human approval', which implies a precondition for calling it. However, it gives no explicit when-not guidance (e.g., use reminders_complete_task to mark done rather than delete) and no alternatives, leaving usage largely implied.

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, destructiveHint=false, and openWorldHint, so the safety profile is fully covered. The description adds a genuine behavioral detail beyond the schema – the required 'reminders' permission – which is useful for auth planning, but nothing about result shape or limits.

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

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

A single front-loaded sentence plus a bracketed version/permission tag; nothing is wasted. It is terse rather than padded, though the metadata tag is convention-driven rather than descriptive.

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

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

For a zero-parameter, read-only listing tool with an output schema present, the description need not explain return values. Auth scope is noted; the only real gap is the absence of any routing hint toward reminders_list_tasks.

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

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

The tool takes zero parameters, so there is nothing for the description to clarify beyond the schema. Baseline 4 applies for a no-argument tool.

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

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

States a specific verb and resource ('List EventKit reminder lists'), which is unambiguous on its own. It implicitly separates itself from reminders_list_tasks by naming 'lists' as the resource, but never explicitly distinguishes the two sibling tools.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as reminders_list_tasks. The agent must infer from the name alone that this is the tool to call before listing tasks.

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 destructiveHint=false, so the safety profile is covered structurally. The description adds two useful facts beyond that: results are bounded (limit-capped at 500 per schema) and the tool requires the 'reminders' permission, which helps the agent anticipate auth gating.

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 front-loaded sentence covering action, filters, and result bound, plus a compact bracketed metadata tag. Nothing is padded, though the semicolon-joined metadata is slightly harder to parse than plain prose.

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-shape explanation isn't required, and the annotations cover the read-only safety profile. The remaining gap is default behavior when filters and limit are omitted, but for a low-complexity 3-optional-param list tool the definition is largely sufficient.

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 33% (limit and completed have empty descriptions), so the description must compensate. It partially does by naming 'list' and 'completion' filtering, but says nothing about the limit parameter's default, upper bound, or what 'bounded result' means in practice when no limit is supplied.

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 ('Read reminders') and names the available filters (list, completion). It is clear what the tool returns, but it doesn't explicitly separate itself from the adjacent reminders_list_lists sibling, leaving the agent to infer the task-vs-list distinction from the name alone.

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

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

The phrase 'optionally filtering list and completion' implies the intended use case (browse reminders with optional filters), but there is no explicit when-to-use statement, no when-not, and no pointer to reminders_list_lists or the create/update/complete 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?

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the description carries a lower burden. It adds the permission scope ("permissions: reminders") and the native-ID targeting requirement, which is useful, but says nothing about whether omitted fields are preserved, whether an approval is required, or how _approvalId interacts with the write.

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

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

Two compact fragments with the action front-loaded and the version/permission metadata clearly bracketed as secondary. No wasted words.

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, and annotations plus the permission tag cover the safety and auth profile. For a reminder update tool the description supplies enough to call it correctly.

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

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

Schema description coverage is 89%, so the schema already documents nearly every field including id, due, listId, and _idempotencyKey. The description adds no field-level meaning beyond what the schema provides, so the baseline 3 applies.

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

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

"Update reminder fields by native ID" gives a specific verb (update), resource (reminder fields), and identifying key (native ID), which separates it from siblings like reminders_create_task, reminders_complete_task, and reminders_delete_task. It stops short of explicitly naming those alternatives, but the core action 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?

No when-to-use, when-not-to-use, or alternative routing is provided. An agent must infer that this is for editing existing reminders rather than completing (reminders_complete_task) or recreating them, and there is no guidance on partial-update semantics versus full replacement.

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, readOnlyHint=false, and openWorldHint=true, so the safety profile is covered. The description adds a genuinely non-redundant behavioral fact — that a human approval prompt gates execution — plus the required automation:Safari permission scope. It stops short of describing failure behavior for an invalid tab or the idempotency semantics declared in 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 short sentences: the action and its identifiers come first, then the approval gate and the version/permission metadata. Every element is relevant, though the bracketed metadata block is slightly mechanical and could be trimmed without loss.

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 annotations carry the safety profile; the critical extra fact (human approval) is stated. The remaining gap is operational: how to discover valid window/tab identifiers and what happens on a stale or out-of-range index.

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%: windowId and tabIndex have empty schema descriptions, while _approvalId and _idempotencyKey are documented in the schema. The description compensates for the gap by clarifying that tabIndex is one-based and that the pair (window ID, tab index) is the identifier, which adds real meaning beyond the bare integer minimums.

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 (close a tab) plus the exact identification scheme (window ID + one-based tab index), which cleanly separates it from siblings like safari_open_tab and safari_list_tabs. An agent can decide to use this tool without opening the schema.

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

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

Usage is implied by the purpose (this is the only close-tab tool among the siblings), and the approval requirement signals it is a deliberate, gated action. However, it never says how to obtain a valid windowId/tabIndex (e.g. via safari_list_tabs) or what to do when the tab does not exist, so no explicit when/when-not guidance is given.

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