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

With no annotations, the description carries the full burden. It discloses scope and output behavior (0% tolerance, 100% validation, remediation suggestions implying no auto-fix), but never states that the operation is read-only, whether it has side effects, or any cost/runtime characteristics.

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

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

Three sentences, front-loaded with the core purpose and scope. Mostly efficient, though 'with 0% tolerance' and 'Validates 100% of source data' restate the same strictness idea.

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

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

For a two-optional-parameter audit tool with no output schema and no annotations, the description explains what categories of results it returns (missing, orphaned, duplicates, file paths, remediation). Only the mutation/side-effect question remains open.

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 both optional parameters (sources with enum values, max_items with its 0-for-unlimited semantics). The description adds no parameter meaning beyond that, which is the correct baseline here.

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 (audit) and resource (search index) and enumerates the findings it produces: missing items, orphaned entries, duplicates. It is clearly distinct from index-building siblings, though it never explicitly contrasts itself with rebuild_index.

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

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

There is no explicit when-to-use guidance and no named alternative. The natural relationship to the sibling rebuild_index (audit detects issues, rebuild fixes them) is left 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?

With no annotations, the description carries the full behavioral burden. It usefully discloses the required time format, recurrence capability, alert behavior, and that the new event id is returned, but says nothing about permissions, side effects, or how the confirm/dry_run preview behavior (documented only in the schema) interacts with creation.

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

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

Four sentences, front-loaded with the core purpose, then format, then capabilities, then return value. Efficient and well-ordered, with no filler.

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

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

For a 16-parameter create tool with no annotations and no output schema, the description covers the essentials: purpose, time format, recurrence, alerts, and the return value. The comprehensive schema supplies the rest, so the remaining gaps are minor.

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 16 parameters thoroughly, establishing a baseline of 3. The description reinforces the recurrence RRULE syntax and time format but adds little beyond what the schema fields already state.

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 calendar event"), which cleanly separates it from the mutation siblings calendar_edit and calendar_remove. It doesn't explicitly name those alternatives, but the create semantics are 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 never says when to use this tool versus calendar_edit, calendar_recurring, or calendar_remove, and offers no preconditions or exclusions. Usage must be inferred 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?

No annotations are provided, so the description carries the full burden. It usefully discloses that natural-language dates are accepted, but says nothing about return format, which calendars are covered, permissions, or error behavior on an unparseable date.

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 purpose front-loaded and a concrete format hint second; no filler or redundancy.

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

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

For a single-parameter read tool with no output schema, the definition covers what the agent must know to invoke it correctly. Only the output/scope details (returned fields, calendar coverage) are absent, which is minor here.

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 single 'date' parameter is already fully documented with examples. The description's sentence about NL dates overlaps with the schema and adds no syntactic detail beyond it, 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 ('Get all events') scoped to 'a specific date', which naturally distinguishes it from siblings like calendar_week and calendar_upcoming. It stops short of naming those siblings explicitly, so differentiation is implied 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 scope ('on a specific date') implies when to use it versus calendar_week, but there is no explicit when-to-use guidance or named alternative. An agent can infer the routing, but nothing tells it to prefer calendar_search or calendar_free_time in other situations.

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?

With no annotations, the description carries the full behavioral burden; it usefully discloses that setting alerts_minutes_before replaces existing alerts (a destructive side effect) and that updates are partial. It still omits permission requirements and the fact that deletes/multi-recipient sends only preview without confirm, leaving meaningful mutation behavior undocumented.

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 terse sentences, front-loaded with the core operation and each carrying distinct information (operation, patch semantics, alert side effect). No filler.

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

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

For a 17-parameter mutation tool with no annotations and no output schema, the schema does heavy lifting on parameter detail, and the description covers the essential update/replacement contract. It nonetheless leaves the confirm/dry_run behavior and required permissions for the agent to infer from 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 all 17 parameters are already documented in the schema, making baseline 3 appropriate. The description adds one useful nuance (alerts_minutes_before replacement semantics) but nothing else beyond the schema.

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

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

States a specific verb and resource ('Update an existing event by id'), which cleanly distinguishes it from the sibling write tools calendar_add and calendar_remove. An agent can identify the operation 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?

'Pass only the fields to change' gives the patch/partial-update contract, which is genuine usage guidance. However, it gives no when-to-use vs alternatives (e.g. calendar_add vs calendar_edit) and does not explain the dry_run/confirm preview workflow that governs whether a call actually mutates state.

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?

No annotations exist, so the description carries the burden. 'Find free time slots' and 'analyzes calendar' implicitly signal a non-mutating read operation, which is meaningful, but it never states read-only behavior, permission requirements, or how working-hour defaults affect results beyond what the schema says.

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

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

Two short sentences, front-loaded with the core action and scope. The second sentence is close to a restatement of the first but adds the 'available time windows' framing, keeping waste minimal.

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

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

For a 4-parameter read tool with no output schema and no annotations, the description covers the purpose but omits how results are shaped or constrained (e.g., whether defaults 9-17 bound the output, granularity of slots). Just enough to call it, not enough to predict its behavior.

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

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

Schema description coverage is 100%, so the schema already documents date, start_hour, end_hour, and calendar_name; baseline is 3. The description adds no extra meaning about how the working-hours range scopes the returned slots or how calendar_name filters analysis.

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

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

States a specific verb (find) and resource (free time slots) with a scope constraint (a specific date), and 'Analyzes calendar to find available time windows' clarifies the mechanism. It does not, however, distinguish itself from siblings like calendar_date or calendar_upcoming, so an agent must infer the boundary.

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 (use this when you want availability rather than a list of events), but there is no explicit when-to-use/when-not framing and no named alternative among the many calendar siblings. 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?

No annotations are provided, so the description carries the burden. It is a zero-parameter read-only lister, and the description does disclose that the response includes writability information, which is the key behavioral detail. It does not state read-only nature or whether any calendar types (shared, subscribed) are omitted, leaving modest gaps.

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 first and the payoff last; every clause earns its place.

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

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

For a zero-param, no-annotation tool with no output schema, the description supplies both the action and the shape of the useful return field (writability). It is sufficient to select and call the tool; only edge cases about what calendars are excluded are 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 no parameters, so the baseline of 4 applies. There is nothing for the description to clarify beyond the return content it already mentions.

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 ('List the calendars in Calendar.app') and adds what the result contains ('with their writability'), so it is clearly a discovery tool. It does not explicitly name a sibling it is distinct from, but its purpose is unambiguous against calendar_upcoming/calendar_week/calendar_add.

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 'so events land on the intended calendar instead of the default' gives a concrete motivating context: call this before choosing a calendar for an event. No explicit exclusions or alternatives are named, so it stops short of a 5.

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

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

No annotations are present, so the description carries the full behavioral burden, yet it discloses almost nothing beyond what the name implies. It does not state whether this is read-only, whether the list is sorted or paginated, what time window 'upcoming' spans, or how occurrences are represented. The parenthetical definition is the only real addition.

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 no filler, front-loaded with the core purpose and followed by a brief scope note. Every clause earns its place.

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

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

For a tool with no annotations, no output schema, and several similarly named calendar siblings, the description is too thin. It fails to explain the return shape, sort order, how recurrence instances are counted against the limit, or how it differs from calendar_upcoming, leaving real gaps an agent would want closed.

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

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

Schema description coverage is 100% for the single limit parameter, so the schema already documents default (30) and meaning. The description adds nothing about the parameter, so baseline 3 applies.

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

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

States a specific verb and resource ('List recurring events') with a clarifying parenthetical defining the resource. It does not, however, explicitly differentiate itself from the closely named siblings calendar_upcoming and calendar_week, which also deal with upcoming occurrences.

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. 'Shows upcoming occurrences' hints at a time-scoped view, but the description never says when to choose this over calendar_upcoming or calendar_week, nor whether it is a filtered variant. An agent must infer the selection 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?

With no annotations, the description carries the full burden and does disclose the key behavior: this is destructive and gated behind confirm=true, otherwise it degrades to a report-only preview. It omits permissions/auth requirements and the irreversibility/effect on recurring events, which would round it out.

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

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

Two sentences, zero waste, with the destructive nature and confirm gate front-loaded immediately after the purpose statement. Nothing redundant.

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

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

For a mutation tool with no annotations and no output schema, the description covers the essential safety behavior (confirm gate, preview fallback) and the schema fully documents parameters. Auth/permission expectations and side effects (recurrence handling, notification of attendees) are the notable remaining gaps.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters including confirm, dry_run, and eventkit_id. The description only restates event_id ('by id') and confirm, adding no syntax or meaning 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 and resource ('Delete a calendar event by id'), which naturally separates it from calendar_edit, calendar_add, and calendar_search. It does not explicitly name a sibling to differentiate against, but the destructive verb 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?

Gives an explicit call-time rule: confirm=true is required, and without it the call only previews. That tells the agent how to invoke it safely, though it does not point to alternatives (e.g., calendar_edit) for modifying rather than removing an event.

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?

No annotations are provided, so the description carries the full burden, yet it says nothing about side effects (this mutates the user's RSVP status), permission requirements, or that confirm/dry_run control previewing versus execution. The schema mentions preview semantics, but the description itself adds no behavioral context for a mutation tool.

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

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

A single front-loaded sentence with no waste and the action options listed inline. It is efficient, though slightly under-specified rather than elegantly concise.

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 rich schema (5 params, 100% coverage, enum) and absence of an output schema reduce the burden, but with no annotations the description should at least note that this changes state and how preview works. It is minimally adequate but leaves a mutation-behavior 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 baseline is 3. The description only restates the response enum values that the schema already documents, adding no new meaning beyond what the structured fields provide.

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 (respond) and resource (calendar invitation) and enumerates the three response actions, so the agent can identify it as the RSVP tool distinct from calendar_edit or calendar_remove. It stops short of explicitly naming a sibling it is not, but the purpose 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 phrase 'Respond to a calendar invitation' implies the usage context, but no when-to-use vs alternatives guidance is given and no exclusions or prerequisites (e.g., needing an event_id from calendar_search) are stated. 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?

With no annotations, the description carries the full burden. It usefully discloses the semantic/embedding mechanism, which is genuine behavioral context beyond the schema, but says nothing about permissions, read-only nature, performance characteristics, or result semantics for a tool that returns AI-ranked matches.

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

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

Three short, front-loaded sentences with the core purpose first and capability notes after. Minor redundancy between 'semantic search... using AI embeddings' and 'finds events by meaning', but nothing is bloated.

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 7-parameter search tool with no output schema and no annotations, the description is minimally adequate. It omits how results are returned or ranked, whether the search spans all calendars by default, and any coverage of the date-window parameters that meaningfully shape results.

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 including examples, defaults, and enum values. The description's mention of calendar name and all-day filtering merely restates a subset of what the schema provides, adding no syntax or behavioral detail.

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 combination ('Semantic search for calendar events') and clarifies the mechanism ('using AI embeddings', 'finds events by meaning'). This distinguishes it from keyword/date siblings like calendar_date and calendar_upcoming, though it never names those alternatives 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 description implies when to use it ('by meaning' rather than by date), but never states explicit conditions, exclusions, or which sibling to prefer for date-based lookups (calendar_date, calendar_upcoming, calendar_week). Usage is inferable rather than 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?

No annotations exist, so the description carries the burden. It does disclose behavior beyond the schema: events are aggregated across ALL calendars and ordered as the 'next' upcoming ones. However it says nothing about permissions, timezone handling, whether recurring/all-day events are included, or pagination, which are meaningful gaps for an unannotated 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?

Two tight sentences with zero filler, and the core scoping fact ('across all calendars') is front-loaded before the sibling comparison. Every clause earns its place.

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

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

For a one-parameter, read-only list tool with no output schema, the description covers what it returns and how it differs from alternatives. It omits ordering/timezone specifics, but the schema carries the only parameter and no return structure needs explaining.

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

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

Schema description coverage is 100%: the single 'limit' parameter already documents itself with its default of 10. The description only echoes this as 'N' without adding format or constraint detail, 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 and resource ('Get next N upcoming events') plus a clear scope ('across all calendars'), and explicitly differentiates from a sibling by calling itself 'simpler than calendar_search'. An agent can distinguish this from search and the other calendar tools without opening a schema.

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

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

Names the alternative (calendar_search) and gives a condition for preferring this tool ('quick schedule overview'). It stops short of stating explicit exclusions or prerequisites, so it is clear context without full when-not guidance.

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

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

No annotations are provided, so the description carries the full burden, and it discloses only that results are grouped by day. It does not state whether all calendars are included, how the week boundary/timezone is defined, or that the operation is read-only and side-effect free.

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

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

Two short sentences, front-loaded with the core action and followed by the output shape; nothing is wasted. It is near-minimal, though it leaves room for a brief routing hint at no real length cost.

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 one-optional-parameter read tool with a fully documented schema and no output schema, the description plus schema covers what an agent needs to invoke it. Remaining gaps (calendar selection, week-boundary definition) are minor for this complexity level.

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

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

Schema coverage is 100% and the single parameter's offset semantics are fully documented in the schema ('0 = this week, 1 = next week'). The description's 'current week or a future week' corroborates that negative offsets are not intended but adds no syntax or format detail beyond that.

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

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

States a specific verb and resource ('Get all events') with a clear scope ('current week or a future week'), which lets an agent separate it from date-range siblings like calendar_date and calendar_search. It does not explicitly name the sibling it competes with, 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 phrase 'current week or a future week' implicitly tells the agent this is the week-granularity view rather than a date-range or upcoming-N-events view, but no alternative tool is named and no exclusions are given. Usage is inferable rather than stated.

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

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

With no annotations, the description carries the full behavioral burden and delivers almost nothing: it does not mention duplicate handling, what happens on partial failure, auth/permission needs, or how the dry_run/confirm semantics in the schema apply to a create. Saying only that it returns the new contact id leaves the mutation profile undisclosed.

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, operation front-loaded before the return value, with zero filler. Nothing in the text is redundant with itself.

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

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

A 10-parameter mutation tool with no annotations and no output schema needs more than a single-line statement. Nothing explains that zero parameters are required or what minimum identity (name/email/phone) makes a useful contact, and the write semantics are 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 every parameter is documented in the schema itself (including the max-10 email/phone limits and the confirm/dry_run behavior). The description adds no parameter meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Create a contact in Contacts.app'), which cleanly separates it from the sibling contacts_edit and contacts_remove. It does not explicitly name those alternatives, so it falls short of a 5, 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?

No when-to-use guidance, no prerequisites, and no pointer to alternatives such as contacts_edit for updating an existing contact. The agent must infer that this is the creation path from the verb 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?

With no annotations, the description carries the full behavioral burden. It does disclose genuinely useful traits absent from the schema: that emails/phones are additive by default, that an empty list plus replace removes them, and that confirm=true is required for that removal. However it omits permissions, reversibility of other field changes, and partial-update behavior for unmentioned fields.

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

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

Two tight sentences with the core action ('Update a contact by id') front-loaded before the caveats. Every clause earns its place, though the confirm/preview interaction could be surfaced slightly more cleanly.

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

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

For a 13-parameter mutation tool with no annotations and no output schema, the description is on the thin side. It covers the tricky delete/preview path but says nothing about partial-update behavior for unmentioned fields, permissions, or failure modes that an agent would need before calling it.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter semantics the schema lacks: the add-vs-replace interaction between emails/phones and their replace_* flags, plus the empty-list-removal rule requiring confirm. That is real meaning beyond the individual parameter descriptions.

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

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

States a specific verb (Update) and resource (a contact by id), which cleanly separates it from the sibling mutation tools contacts_add and contacts_remove. It doesn't explicitly name those siblings, but the edit/add/remove triad makes the intent 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 never says when to prefer this over contacts_add or contacts_lookup, nor does it state prerequisites beyond the implicit 'need an id'. It describes mutation semantics (add vs replace) rather than offering any usage routing 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?

No annotations are provided, so the description carries the full burden. It does disclose the return contents ('full contact details including all emails and phone numbers'), which is useful, but says nothing about behavior when the identifier is not found, when a name matches multiple contacts, or any permission requirements.

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

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

Two short sentences with zero filler; the action and accepted inputs are front-loaded and the return behavior follows immediately. Every clause earns its place.

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

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

For a one-parameter lookup with no output schema, the description does helpfully state the return shape, compensating for the missing output schema. However it omits not-found behavior and ambiguity handling for name matches, which are the main risks for an agent calling this tool.

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

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

Schema description coverage is 100% for the single identifier parameter, and the description merely restates the same three accepted forms (email, phone number, name). Baseline 3 is correct when the schema already fully documents the parameter and the description adds no format or precedence detail.

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 (look up) and resource (a contact) plus the three accepted key types. It is clear what the tool does, but it never distinguishes itself from the overlapping siblings contacts_search and person_search, so an agent must guess which lookup path to take.

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 'a specific contact' faintly implies singular, exact retrieval versus a search, but there is no explicit when-to-use guidance, no exclusions, and no routing to contacts_search or person_search despite strong sibling overlap. Nothing tells the agent when this should be preferred over the alternatives.

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

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

With no annotations provided, the description carries the full behavioral burden and does well on the critical point: it flags the operation as destructive and explains the confirm-gate that converts a real delete into a read-only preview. It omits whether deletion is permanent/reversible and what permissions are needed, so it is strong but not complete.

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 destructive nature and the gate condition front-loaded; there is no filler and every clause carries actionable information.

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

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

For a single-parameter-required mutation tool with no output schema and no annotations, the description covers the essential risk (destructive) and the safety mechanism (confirm gate / preview). It leaves minor gaps around permanence of the delete and what the preview output contains.

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

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

Schema description coverage is 100% and all three parameters (contact_id, confirm, dry_run) are already documented in the schema. The description restates the confirm semantics rather than adding syntax, formats, or interactions the schema lacks, so the baseline 3 applies.

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

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

The description gives a specific verb ("Delete") plus resource ("a contact") and identifies the key ("by id"), which cleanly separates it from siblings like contacts_edit, contacts_add, or calendar_remove. An agent can select it without opening the schema.

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

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

It states the operating condition explicitly: confirm=true is required to actually delete, otherwise the call previews. That is clear when-to-use context. It does not name an alternative tool (e.g., contacts_edit when the goal is modification rather than removal), so it falls short of full routing guidance.

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

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

No annotations are provided, so the description carries the full burden. It implies a read-only search and notes that results include all contact details, which is useful, but it omits permissions, pagination behavior tied to limit, and any other operational traits.

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, then the return behavior. Efficient with no filler, though it is not rich enough to merit a 5.

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

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

For a simple two-parameter tool with no output schema, the description is adequate: it covers what can be searched and that full details are returned. It does not address paging/limit semantics or sibling disambiguation, leaving minor gaps.

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

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

Schema description coverage is 100%, so both parameters (query and limit) are already fully documented in the schema. The description only restates the searchable fields, adding essentially nothing beyond 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 (Search) and resource (contacts) plus the searchable fields (name, email, phone, organization), so the core function is unmistakable. However, it does not distinguish itself from siblings like contacts_lookup or person_search, which likely overlap in intent.

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 mention of when not to use it, and no reference to the closely related contacts_lookup or person_search siblings. The agent must infer the selection criteria with no help from the description.

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

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

No annotations are provided, so the description carries the full behavioral burden. It says 'Move', implying mutation, but never states whether the email is recoverable from Archive, whether the original folder is recorded, or that the schema's confirm/dry_run flags gate a preview-vs-commit flow. That preview behavior is material and only discoverable by reading parameter docs.

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

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

A single front-loaded sentence with no filler. It is efficient, though its brevity contributes to the gaps elsewhere rather than compensating for them.

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 annotations and no output schema, the terse description is the only source of behavioral framing, and it omits the preview/confirm mechanics, result reporting, and error behavior. Notably, the confirm parameter's schema text mentions deletes and multi-recipient sends, which reads as generic boilerplate unrelated to archiving and is not reconciled in the description.

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 four parameters are already documented in the schema, including the file_path alternative to message_id. The description adds nothing about parameter usage, which is acceptable at this coverage level but earns no bonus.

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

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

States a specific verb and resource ('Move an email to its account's Archive mailbox'), which is clearly distinguishable from mass operations. It does not explicitly distinguish itself from the closest sibling, mail_trash, leaving the agent to infer that Archive is a non-destructive relocation rather than a delete.

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 exclusion of alternatives, and no mention of prerequisites such as first resolving a message_id via mail_search or mail_read. The agent must infer the entire selection context from sibling names 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?

With no annotations, the description carries the full behavioral burden. It notes natural-language date support, but that same capability is already spelled out in the schema's date description, so it adds little; nothing is said about return format, ordering, volume, or which mailboxes are scanned.

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

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

Two sentences, front-loaded with the core action, with the usage cue last. Slightly redundant since 'emails from a specific date' is effectively restated in the usage sentence, but nothing is wasted.

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

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

For a read-only retrieval tool with no output schema and no annotations, the description is adequate for selection but silent on result structure, sorting, and pagination limits. It is minimally complete rather than thorough.

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

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

Schema description coverage is 100%, so both parameters are already documented, including the natural-language examples repeated in the description. Baseline 3 is appropriate since the description adds no syntax or semantics 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 ('Get') plus resource ('emails') and the scoping condition ('from a specific date'), making the purpose unambiguous. It does not explicitly name the many sibling list/search tools (mail_search, mail_recent, mail_find) it overlaps with, so differentiation requires inference.

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?

'Use this when the user asks for emails on a specific date' gives an implied usage context, which is more than nothing. However it names no alternatives and gives no exclusion guidance against mail_search or mail_recent for overlapping date-related queries.

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?

With no annotations, the description carries the disclosure burden. It usefully clarifies that drafts are never delivered and that recipient confirmation is unnecessary, but says nothing about where the draft is stored, whether it persists across sessions, or what permissions are needed for a mutating operation.

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 save-without-send behavior and no filler. Every sentence earns its place.

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

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

For an 8-parameter mutating tool with no annotations and no output schema, the description is thin: it covers the send/no-send distinction but omits return behavior, draft location, and how confirm/dry_run interact with this operation. The rich schema compensates partially, leaving a clear gap.

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

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

Schema description coverage is 100%, so all eight parameters including enum and the confirm/dry_run semantics are documented in the schema itself. The description adds no parameter-level detail beyond that, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Save an email to Drafts') plus the key contrast ('without sending it'), which cleanly separates it from the mail_send sibling without requiring either schema to be opened.

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 (compose-but-don't-send, no recipient confirmation needed) but the description never names mail_send as the alternative or states when a caller should draft versus send. The guidance is inferable rather than explicit.

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

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

With no annotations, the description carries the full burden and does so well: it discloses that it never waits on indexing, that results are one row per copy with a named field list, and that Trash is excluded unless include_trash or mailboxes asks for it. It stops short of permission/safety context, but for a read 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?

Front-loads the scope distinction, then packs return shape, constraints, defaults, and workflow into a few dense sentences with no filler. Slightly bracket-heavy, but every clause earns its place.

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

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

For a 13-parameter read tool with no output schema and no annotations, the description supplies the return format, default exclusions, and the minimum-filter requirement, which is most of what an agent needs. It omits any mention of pagination/truncation defaults beyond what the schema covers, keeping it just short of full.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a cross-parameter constraint the schema cannot express ('needs at least one of ...') and explains the dedup semantics of message_ids ('finds every copy'). That pushes it above the schema-only 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 precise verb+resource (exact email lookup) and immediately differentiates itself from the semantic-index sibling by scope ('Mail's own database ... not the semantic index'). An agent can tell this apart from mail_search without opening either schema.

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

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

Gives explicit preconditions ('Needs at least one of subject_prefix, subject_contains, from, to, message_ids') and a follow-up workflow ('Pair with mail_trash message_ids to clear what it finds'). It implies the semantic alternative but never names mail_search directly, so routing is left slightly 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?

With no annotations, the description carries the full burden and delivers: the note is pasted above the original in a visible Mail window, AppleScript content is not set, sends are verified in Sent/Outbox before success, and it distinguishes timeout vs TCC failures including error codes -1743/-10004 and hang-recovery matching. This is genuinely rich behavioral disclosure.

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?

Purpose is front-loaded in the first sentence, followed by confirm and verification behavior. The trailing sentences on TCC codes and hang recovery are dense but each carries actionable retry guidance, so little is wasted even if the density is high.

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 7-parameter mutation tool with no annotations and no output schema, the description covers send verification, timeout semantics, retry rules, and the optional note behavior. It is largely self-sufficient, with only minor gaps such as what the success/preview response actually contains.

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

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

Schema coverage is 100%, so every parameter is already documented in the schema, and the description mostly restates these (note mechanism, confirm requirement). It adds little parameter-level meaning beyond what the structured fields provide, 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+resource ('Forward an existing email to new recipients') and implicitly separates itself from mail_reply by noting it shares the same System Events prepend mechanism. An agent can identify this as the forward action rather than reply or send.

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

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

Gives concrete operating conditions: multi-recipient sends require confirm=true, a preview-only path exists, and clients must Sent-check before retrying a timed-out send. It stops short of an explicit 'use this instead of mail_reply/mail_send when X' routing statement, so it is clear context without full alternatives mapping.

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?

No annotations are provided, so the description carries the full behavioral burden, and it discloses nothing: not whether the change is reversible, what permissions are needed, whether it affects only the local index or the server, or that the call can preview rather than apply. The confirm/dry_run preview semantics exist only in the schema, not in the description.

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 with zero filler, appropriately sized for a narrowly scoped state-toggle tool. Nothing in it is redundant.

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

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

For a 5-parameter mutation tool with no annotations and no output schema, the description is too thin. It never explains the target-identification choice between message_id and file_path, nor the preview/confirm behavior, both of which an agent needs to call it correctly without opening 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% and every parameter (status, confirm, dry_run, file_path, message_id) is documented in the schema itself, so the baseline of 3 applies. The description adds no meaning beyond the schema – it does not explain the status default or the message_id/file_path alternative.

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 ('Mark') and resource ('an email') plus the effect dimension ('as read or unread'), so the operation is unambiguous. It does not, however, distinguish itself from siblings like mail_archive or mail_trash, which also mutate message state.

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 use this versus mail_archive, mail_trash, or mail_read, and no mention of prerequisites or when marking is preferred over leaving a message unread. The single sentence is pure purpose, leaving selection 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?

No annotations are provided, so the description carries the behavioral burden. 'Read' implies a non-mutating operation, so the safety profile is inferable, but the description says nothing about error behavior for invalid/stale paths, authentication, or whether attachments and HTML are included in 'full content.'

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

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

Two short sentences with zero filler; the purpose is front-loaded and the prerequisite follows immediately. Every sentence earns its place.

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

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

For a single-parameter, read-only tool with no annotations or output schema, the description covers what it does and where the argument comes from. It could be slightly richer about what 'full content' includes (body, attachments, headers), but nothing essential for correct invocation is missing.

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

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

Schema coverage is 100% and the single parameter is self-describing, so the baseline would be 3. The description adds real value by naming mail_recent as an additional valid source for file_path, while the schema mentions only mail_search.

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 full email content,' which is clearly distinct from search/list operations. It names the tools that produce its input (mail_search, mail_recent), giving implicit differentiation, but does not contrast against the closely-related siblings mail_thread or messages_conversation that also surface message bodies.

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

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

Gives a clear chaining instruction — use the file_path from mail_search or mail_recent results — so the agent knows the prerequisite and the workflow position. There is no explicit 'do not use this for X' statement and no guidance on when to prefer mail_thread instead.

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?

No annotations are provided, so the description carries the full burden. It does not state that this is a safe read-only operation, the sort order beyond 'most recent', whether results are capped only by the limit, or anything about pagination. It is adequate for a simple list tool but adds no behavioral context beyond the purpose.

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

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

Two short sentences, zero waste, with the core purpose front-loaded before the routing triggers. Every clause earns its place.

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

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

For a read-only, zero-required-param list tool with full schema coverage and no output schema, the description covers what an agent needs to select and invoke it. It only omits minor operational detail such as ordering guarantees, which is a small gap.

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

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

Schema description coverage is 100%, with each of the four parameters (limit, days_back, unread_only, include_junk) documented including defaults and the Mail.app read-status nuance. The description adds nothing beyond the schema, 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 and resource ('Get most recent emails') and immediately draws the boundary against semantic-search siblings such as mail_search and smart_search. An agent can distinguish it from mail_search without opening either schema.

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

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

Explicitly enumerates the user utterances that should route here ('recent emails', 'latest emails', 'what emails did I get', 'unread emails') and names the alternative modality (semantic search) it is not. This is exactly the when-to-use signal an agent needs.

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?

No annotations are provided, so the description carries the full burden and it does so richly: paste-above-quote mechanics, reply_all fan-out requiring confirm, real-send verification in Sent/Outbox, the timeout-vs-TCC distinction, error codes -1743/-10004, and hang recovery via In-Reply-To. This is unusually deep behavioral disclosure.

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?

Purpose is front-loaded and every sentence carries behavioral content, though the parenthetical paste mechanics (System Events focus, Command-Up vs Cmd-A, Mail 16 detail) are deeply implementation-specific and verge on over-specification for a tool-selection context.

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 annotations and no output schema, the description must carry behavior and result semantics, and it does - explaining that success is verified in Sent/Outbox and how timeouts should be handled. Remaining detail (draft vs send distinctions) is left to the fully-covered 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 coverage is 100%, so the baseline is 3. The description goes beyond the schema by stating the coupling that reply_all=true requires confirm=true and that body is pasted rather than set via AppleScript, adding meaning the schema alone doesn't convey.

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 ('Reply to an existing email'), clearly distinct from mail_send, mail_draft, and mail_forward by the reply semantic. It does not explicitly name those siblings, so differentiation is inferred from the verb 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?

Usage is implied by 'reply to an existing email' and by the confirm/reply_all coupling, but the description never states when to pick this over mail_send or mail_draft, nor any precondition for a valid reply (e.g. must have a resolvable Message-ID). Adequate but with clear gaps.

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?

With no annotations, the description carries the full burden, and it does disclose a meaningful behavioral trait: ranking is semantic-embedding based rather than keyword based, which explains result relevance. It omits other behaviors such as default limits, pagination, return format, and any permission or rate constraints, so gaps remain.

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

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

Three short front-loaded sentences with the core purpose stated first. Efficient overall, though the final sentence enumerating filters overlaps with structured schema fields and mildly duplicates information.

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

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

For an 11-parameter, no-annotation, no-output-schema tool, the description covers purpose and filter scope but says nothing about what results look like, default/vs-max limits, or how relevance scores are returned. Adequate but leaves real gaps an agent would want filled.

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 is already documented in the schema and the baseline is 3. The description's list of filter categories (sender, recipient, attachments, mailbox, sent/received, flagged) largely restates what the schema already provides and adds no syntax or semantic detail beyond it.

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

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

States a specific verb (search) and resource (emails) plus the distinguishing mechanism (semantic AI embeddings, 'by meaning, not just keywords'). This implicitly separates it from keyword-based siblings, but it never names the near-duplicate tools it competes with (mail_find, smart_search, messages_search), so an agent must still infer which one to pick.

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 explains what the tool does but gives no when-to-use or when-not-to-use guidance, and never references the alternative search tools in the sibling list. There is no stated condition that would route an agent here rather than to mail_find or smart_search.

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?

With no annotations, the description carries the full behavioral burden and does so thoroughly. It discloses success verification criteria (Sent or Outbox, not merely AppleScript return), multi-recipient confirm requirements, dry_run and unconfirmed non-delivery semantics, timeout vs. TCC error codes (-1743/-10004), hang recovery matching rules, and the need for a Sent-check before retry.

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

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

The description is front-loaded with the core purpose and contains no filler. It packs many distinct operational rules into a dense paragraph, which slightly reduces scannability, but every sentence adds necessary information for correct invocation.

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

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

Given the complexity of sending mail, the absence of annotations, and the lack of an output schema, the description is complete for an agent to call the tool correctly. It covers success, failure, required flags, timeout recovery, and retry prerequisites, so little critical context 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 meaning beyond the schema by specifying that multi-recipient means more than one recipient in total (to + cc + bcc) and that dry_run and unconfirmed multi-recipient calls are non-deliveries returned as MCP isError. These are useful semantic extensions for confirm and dry_run.

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

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

States a specific verb and resource: 'Send an email through Mail.app.' The operational constraints are immediate and unambiguous. It does not explicitly differentiate itself from sibling send tools such as messages_send, mail_draft, or mail_reply, 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?

Provides clear rules for confirm=true on multi-recipient sends and describes dry_run and unconfirmed calls as non-deliveries. It also warns about retrying timed-out sends. However, it never says when to choose mail_send over sibling tools like mail_draft, messages_send, or mail_reply, so usage guidance for tool selection 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?

No annotations are provided, so the description carries the full behavioral burden. It implies a read/aggregation but doesn't disclose return shape (senders plus counts?), whether Junk is excluded by default, or any ordering semantics beyond 'most frequent'. Only the ranking behavior is hinted at.

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 primary action and followed by a single clarifying purpose line. No filler or redundancy; every sentence earns its place.

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

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

Parameters are fully covered by the schema, but with no output schema the description omits what the result looks like (e.g., sender + frequency, ordering). For a ranking tool this leaves a modest gap an agent must infer.

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 (limit, days_back, include_junk) are already fully documented in the schema. The description adds no parameter-level detail beyond what the schema provides, making the baseline 3 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: 'List most frequent email senders', which is a distinct aggregation over the mail corpus rather than a message-level sibling like mail_search or mail_recent. The purpose is clear without needing the schema, though it does not explicitly call out how it differs from related mail 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?

The phrase 'Helps identify who you communicate with most' implies the use case (relationship/frequency analysis) but gives no explicit when-to-use versus alternatives and no exclusions or prerequisites. Usage is implied rather than stated.

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

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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses that thread grouping works by subject-line matching, which can cause false groupings or omissions. Beyond that, it says nothing about ordering, permissions, or whether bodies/attachments are included, so it is only moderately transparent.

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 short sentences, front-loaded with the purpose and then the mechanism. It is efficient and wastes little space. A slight overstatement—'all emails' when a default limit of 30 exists—keeps it from a perfect 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?

For a simple two-parameter retrieval tool with no output schema, the description covers the core action and a key behavior. It still omits likely relevant context such as result ordering, failure modes when no thread is found, and the relationship to sibling search tools, so it is only minimally 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 fully documents both file_path and limit. The description adds no parameter-level 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?

The description states a clear verb and resource: 'Get all emails in a conversation thread.' It also adds a mechanism ('matching subject lines'), making the scope concrete. However, it does not differentiate from siblings like messages_conversation or mail_search, so 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?

There is no explicit when-to-use guidance, no conditions for choosing this tool over alternatives, and no exclusions. The implied use case is retrievable from the name and first sentence, but the description does not help an agent route between this and similar thread/search tools.

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

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

With no annotations, the description carries the full burden and does so well: it flags the operation as destructive, explains the confirm/preview gate, discloses that EVERY copy across folders (INBOX, Sent, Archive) is moved, notes each Message-ID is re-checked before moving, and documents the ~35s bulk cap with a 'remaining' signal plus the re-run remedy. This is exactly the behavioral context an agent needs for a destructive bulk 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?

Front-loaded with purpose and the destructive gate, then the mode semantics and limits. Dense and mostly waste-free, though the streaming clauses make it slightly run-on and some folder examples (INBOX, Sent, Archive) are illustrative rather than essential.

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

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

No output schema, and the description compensates by describing the preview report, the 'remaining' field on bulk timeouts, and the per-copy identity re-check. It does not address recovery/undo or permission requirements, but for a move-to-Trash tool with a preview gate the coverage is close to 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 100%, so the baseline is 3, but the description adds real semantics beyond the schema: it groups message_id/file_path as 'one message' vs message_ids as 'many', states the 500-item bulk limit and the mail_find source, and notes copies span multiple folders. This meaningfully enriches the parameter contract.

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?

Opens with a specific verb+resource ('Move email to Trash') and immediately scopes the operation as destructive. An agent can distinguish this from siblings like mail_archive and mail_mark without inspecting schemas, and the single-vs-bulk modes are stated up front.

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?

Clearly states the confirm=true prerequisite, that omitting it yields a preview, and when to use the bulk message_ids path vs a single message_id/file_path. It also points to mail_find as the source for IDs. It stops short of naming a sibling alternative (e.g. mail_archive) for non-destructive moves, so it earns a 4 rather than a 5.

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

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

With no annotations, the description carries the burden and does disclose the sort order (most recent) and the returned fields (message count, last message date). However, it says nothing about auth requirements, pagination beyond the limit, or behavior on an empty mailbox, so it only partially fills the gap left by missing 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 tight sentences that front-load the core purpose and append the return-value detail. No filler or redundancy.

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

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

For a simple single-parameter read tool with no output schema, the description covers the operation, ordering, and returned fields adequately. Minor gaps around pagination behavior and prerequisites keep it just short of fully 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% and the single limit parameter is fully documented in the schema, so no description compensation is needed. The description adds no extra meaning about the parameter, making the baseline 3 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 (List) and scoped resource (contacts you've messaged, sorted by most recent), which clearly distinguishes it from contacts_search, contacts_lookup, and messages_recent. It does not explicitly name any sibling, but the messaging-scoped contact list 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?

There is no when-to-use or when-not-to-use guidance and no alternatives named. The purpose implies a use case (finding people you've corresponded with), but an agent gets no routing help versus contacts_search or person_search.

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?

With no annotations, the description carries the full burden; it usefully discloses ordering ('chronological order') and completeness ('full'), which are real behavioral facts. However it omits pagination behavior, whether the limit truncates the 'full' history, permission/auth requirements, and what happens for an unknown contact.

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, front-loaded sentences with no filler; the scope (specific contact) leads and the ordering detail follows. Slightly generic but every sentence carries information.

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

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

For a two-parameter read tool with no output schema and no annotations, the description covers the core purpose but leaves the limit/truncation relationship and error behavior unaddressed, so an agent cannot fully predict the result set size.

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 both contact and limit, making 3 the baseline. The description adds nothing about parameter meaning, and its claim of 'full conversation history' sits awkwardly against a default limit of 50 messages.

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

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

States a specific verb (Get) and resource (full conversation history) scoped to a specific contact. It is clearly distinct from broadcast siblings like messages_recent or messages_search, but never names an alternative to route the agent 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 'with a specific contact' implicitly signals this is the per-thread lookup versus a general search, but the description never states when to prefer it over messages_search or messages_recent, nor any prerequisites.

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

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

No annotations are provided, so the description carries the full behavioral burden. It correctly frames this as a plain recency retrieval with no semantic ranking, but it does not disclose result ordering guarantees beyond "most recent", pagination behavior, or whether defaults are applied server-side. Adequate but with clear gaps for a zero-annotation 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?

Two compact sentences with the core purpose front-loaded and the routing cues immediately after. There is no filler and every clause earns its place.

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

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

For a two-parameter, no-output-schema read tool with fully documented parameters, the description covers what an agent needs in order to call it correctly. It could be slightly more complete by pointing to the sibling to use when filtering by contact or thread is needed, which is the only 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 100%, so the two parameters (limit, days_back) and their defaults are already fully documented in the schema. The description adds the recency framing but no additional syntax or format detail 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 and resource ("Get most recent messages") and explicitly scopes it against the semantic-search alternative ("without semantic search"), which distinguishes it from siblings like messages_search and smart_search. An agent can tell what this does and how it differs from the search tools without opening any schema.

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

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

It gives concrete trigger conditions with quoted user phrasings ("recent messages", "latest texts", "what messages did I get"), which is strong when-to-use guidance. It stops short of naming the sibling to use instead for filtered/lookup cases, so it is clear context but not a full use-this-not-that rule.

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?

No annotations are provided, so the description carries the full burden. It does disclose the key behavioral trait that this is embedding-based semantic matching rather than literal keyword matching, but it omits return format, pagination/precedence, and any auth or scope constraints for an 8-parameter read 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?

Three short sentences, front-loaded with purpose and followed by scope. 'Finds messages by meaning' is mildly redundant with 'semantic search,' but otherwise the text is tight and earns its space.

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 search tool with no output schema and no annotations, the description covers purpose and filter scope adequately, and the schema supplies full parameter detail. It would be stronger if it hinted at result shape or how many results to expect, but nothing essential is missing 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 eight parameters are already documented in the schema. The description only restates the filter categories (contact, group chats, group name, attachments) without adding syntax, defaults, or interaction rules beyond the schema, so the baseline 3 applies.

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

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

The description states a specific verb and method ('Semantic search for iMessages/SMS using AI embeddings') plus the resource it operates on, which distinguishes meaning-based search from keyword search. It does not explicitly name siblings like messages_recent or messages_conversation, so an agent must infer the boundary, but the resource and mechanism are otherwise 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?

Filtering capability ('by contact, group chats, specific group name, and attachments') implies when the tool is useful, but there is no explicit when-to-use versus messages_recent, messages_conversation, or smart_search, and no exclusions or prerequisites. Usage is left to inference.

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

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

With no annotations, the description carries the full burden. It usefully discloses the confirm gating (preview without it), that chat_id is verified against the Messages database, and that multi-recipient sends need confirmation — but it omits permissions/account requirements, irreversibility of sending, and any return behavior. Partial coverage for an irreversible mutating action.

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

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

Three tight sentences, front-loaded with the core action, then the addressing options, then the confirm caveat. No filler, every sentence earns its place.

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

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

No output schema exists, but the description plus fully-documented schema cover addressing, confirmation, service selection and dry-run adequately for a send tool. Missing only peripheral details such as required permissions and confirmation of what a successful send returns.

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

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

Schema coverage is 100%, so the schema already documents all seven parameters including the E.164 and chat GUID formats. The description reinforces the addressing formats with examples but adds little 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?

States a specific verb and resource (send an iMessage or SMS) and names the delivery medium, which cleanly separates it from sibling senders like mail_send. An agent can identify the operation without opening the schema.

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

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

Gives clear routing guidance for the two addressing modes ('to' vs 'chat_id') and states the condition that requires confirm=true for group/multi-recipient sends. It does not name alternatives or say when not to use it, but the context is sufficient to invoke correctly.

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?

With no annotations the description carries the full burden, and it does disclose real behavior: it auto-resolves a name to all emails and phone numbers via Contacts and fans out across three sources. It omits other behavioral facts such as result ordering, deduplication across sources, permission needs, or pagination behavior beyond the limit param.

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

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

Two sentences with zero filler, and the defining scope ('ALL communication ... across Mail, Messages, and Calendar') is front-loaded in the first clause. Every sentence earns its place.

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

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

For a 2-param search tool with no output schema and no annotations, the description covers what it does and the non-obvious contact-resolution mechanism. It is slightly thin on return-value shape and result ordering, but nothing essential to invoking it correctly is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema and the baseline is 3. The description reinforces the name-to-contacts resolution semantics but adds no syntax, format, or matching-rule detail beyond what the schema already states.

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 (ALL communication with a specific person) plus the scope (Mail, Messages, and Calendar). By declaring cross-source, person-centric aggregation it implicitly and cleanly distinguishes itself from the single-source siblings like mail_search, messages_search, and calendar_search.

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 cross-source scope implies when this is preferable to the per-source search tools, and the mention of automatic contact resolution hints at the setup it handles for you. However, it never explicitly names an alternative (e.g. smart_search or contacts_search) or states when NOT to use it, so guidance stays implied rather than explicit.

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

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

With no annotations, the description carries the full burden and does disclose the important destructive trait: it "clears the existing index and re-indexes all content from scratch." It does not cover permissions, expected duration, or whether search is unavailable during the rebuild, so it falls short of full behavioral disclosure.

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 purpose and destructive effect are front-loaded, and the sentences are mostly free of waste. The final sentence recapping the sources is largely redundant with the schema enum, keeping it from a 5.

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

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

For a single-parameter tool with no output schema, the description covers purpose, trigger conditions, and the destructive nature of the operation. It leaves open operational details such as required permissions or availability during the rebuild, but nothing that would prevent a correct 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 coverage is 100%, so the enum values and default are already documented in the schema. The description repeats the accepted sources ("emails, messages, calendar, or all sources at once") but adds no syntax or behavioral detail beyond the schema, making 3 the correct baseline.

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

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

The description gives a specific verb+resource ("Rebuild the search index") and scopes it to "one or more data sources." It is clear what the tool does, but it does not differentiate itself from the closest sibling, audit_index, which an agent might confuse it with.

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

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

It states an explicit trigger condition: "Use this if search results are stale, missing, or if the index is corrupted." That is clear context for when to reach for it, though it names no alternative tool or when-not-to-use case.

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?

With no annotations, the description carries the full burden. It usefully discloses that source selection is automatic and that results are grouped by time when multiple sources match, which is real behavioral context. However it says nothing about permissions, how sources are chosen, ordering, or rate limits.

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

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

Four short sentences, front-loaded with purpose, then mechanism, then routing guidance. No filler or repetition, though "Intelligent" is slightly marketing-flavored 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?

No output schema exists, yet the description covers what comes back (results grouped by time across matched sources) and when to reach for it. Adequate for a read-only search tool; missing only edge behavior such as empty results or source-selection failure.

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 query, limit and synthesize with examples, giving a baseline of 3. The description's time-grouping note loosely reinforces synthesize but adds no syntax or format detail beyond it.

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

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

States a specific verb (search) and resource set (Mail, Messages, Calendar) with the notable differentiator that it auto-selects sources. Distinguishes itself from the many single-source siblings like mail_search/messages_search/calendar_search by scope, though it never names them.

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

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

"Use this for complex queries that might span multiple data sources" gives an explicit when-to-use condition that implicitly excludes simple single-source lookups. It stops short of naming the alternative single-source tools for the non-matching case.

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