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

Despite annotations covering readOnlyHint=false, destructiveHint=true, and openWorldHint=true, the description adds substantial context beyond them: the two-phase approval flow, the preview mechanism, request expiry (15 min), deduplication of identical pending requests, rate limiting (>20/hour per tool), audit logging, and the fact that the second call executes the originally approved payload. This is exceptionally rich behavioral disclosure that an agent could not infer from annotations alone.

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

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

The description is long but front-loads the core purpose and the critical two-phase workflow immediately. Every sentence provides actionable information (approval, expiry, dedup, rate limit, audit, return value, prerequisite). It is dense but not padded — a minor deduction only because the schema already repeats some request_id details.

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

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

This is a high-complexity mutation tool with no output schema, so the description must carry the full burden. It covers the approval workflow, execution semantics, return value ({id, ...}), prerequisite (connected calendar), rate limits, expiry, audit logging, and even points to find_free_slots. Nothing an agent needs in order to call it correctly appears to be 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 schema already documents all six parameters thoroughly, including request_id. The description reinforces the two-phase behavior around request_id but does not add syntax, format, or constraint details beyond what the schema provides. Baseline 3 is appropriate when the schema does the parameter-level heavy lifting.

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

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

States a specific verb+resource ('Create a calendar event on the connected calendar') and is clearly distinguished from siblings like find_free_slots (referenced) or delete_event (named sibling implies write vs delete distinction). An agent can immediately tell this is the creation tool, not a listing or free-slot query.

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 says to use find_free_slots first, and explains the required two-phase human-approval workflow in detail. It also gives a concrete reason for the approval requirement (events generate invitations), which helps the agent understand when and why this tool behaves differently from a simple write. This is unusually thorough 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?

The description is transparent about return values, error cases, execution immediacy, audit logging, and reversibility. However, it contradicts the idempotentHint=true annotation by stating that a duplicate name yields an error object; an idempotent tool should return the same result on repeated identical calls. This is an annotation contradiction.

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

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

Four sentences, each carrying distinct information: purpose, return/error, execution/audit, and sibling distinction. No filler; front-loaded with the core action.

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

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

For a two-parameter tool with no output schema, the description covers return shape, error behavior, execution context, and the relevant sibling. The only notable gap is the idempotency inconsistency, which prevents a perfect score.

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 name and account_id. The description adds no parameter-specific meaning beyond the schema, so baseline 3 applies.

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

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

States a specific verb ('Create'), resource ('mailbox folder'), and provider scope, and explicitly distinguishes from delete_folder. The purpose is immediately clear and not confusable with siblings.

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

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

Provides clear context: executed immediately, no approval, harmless/reversible, and explicitly names delete_folder as the different approved tool for removal. It does not enumerate when to prefer list_folders, but the schema covers that, so this is 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?

Description goes far beyond annotations by detailing the human-approval gate, the fact that the first call executes nothing, the approved-arguments-not-second-call rule, expiration, deduplication, rate limiting, audit logging, the waiting room behavior, and the external requirement of Zoom being connected. This gives the agent a clear model of side effects and safety even though destructiveHint is true.

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 dense but front-loaded, and every sentence carries essential information for a complex, human-approved, two-phase tool. Rather than padding, it covers invocation flow, pending-request behavior, rate limits, audit, privacy, output shape, and prerequisite in a compact block.

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

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

For a tool with no output schema, the description explicitly states the return shape ({id, join_url, password}), the main statuses (approval_required, awaiting_approval, rate_limited), and the prerequisite. Combined with the thorough input schema, an agent has everything needed to call and interpret the tool correctly.

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

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

The input schema already covers all parameters with 100% description coverage, but the tool description adds crucial semantics for request_id: it must be omitted on the first call, the approved payload wins over the second call's arguments, and deduplication/expiry behavior. This is meaningful value beyond the schema, though the other parameter details are left to the schema.

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

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

The opening sentence states a specific verb and resource ('Create a Zoom meeting on the user's connected Zoom account') and the key return value ('return its join link'). This unambiguously distinguishes it from sibling tools like create_event or send_mail, especially with the later note to share the join_url via send_mail/reply_mail.

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

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

The description clearly explains the two-phase invocation workflow (first call without request_id, second call with approved request_id), the prerequisite that Zoom must be connected, and the follow-up action of sharing the join_url via send_mail/reply_mail. It does not explicitly state 'use create_event for calendar events' or list when-not-to-use scenarios, but the context is strong enough for an agent to select and invoke it 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?

Far exceeds what annotations convey: two-phase human approval, out-of-band approval channels behind biometrics, request expiry (15 min), deduplication, rate limit (20/hour with status=rate_limited), audit logging, and the consequential effect that deleting an organizer's event cancels it for all attendees. This is rich, decision-relevant behavioral context beyond the destructive/openWorld hints.

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

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

Dense but well front-loaded, moving from purpose to the critical two-phase constraint immediately. Some overlap with the schema's request_id description and the parenthetical channel list is verbose, but every sentence carries operational weight.

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

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

For a destructive, non-idempotent tool with no output schema, the description covers the approval workflow, failure/limit states, audience cancellation impact, the preview content, and the {success} return value. Nothing essential to 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 description coverage is 100%, so both parameters are already documented in the schema. The description reinforces request_id semantics (omit on first call, execute on second) but adds little beyond the schema text. 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?

Specific verb+resource ('Delete a calendar event') with scope ('on the connected calendar'). Clearly distinguished from siblings like list_events and create_event, and it names the provider constraint (Microsoft or Google).

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 operational context: requires a connected calendar, two-phase flow, and how each phase is invoked. Lacks explicit when-to-use-vs-alternatives routing (e.g., vs delete_message), but the invocation context is very clear.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description goes far beyond: it discloses the two-phase approval, preview behavior, expiration, deduplication, rate limiting, audit logging, and the critical caveat that the second call uses approved arguments, not the ones passed. No contradiction with annotations.

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

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

Every sentence earns its place: the destructive warning is front-loaded, the two-phase flow is explained in a compact sequence, and operational constraints (expiry, dedup, rate limit, audit) are listed without redundancy. It is dense but not 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 destructive, two-phase tool with no output schema, this description covers everything an agent needs: the approval workflow, the arguments' significance, safety warnings, rate limits, and the expected return shape. Nothing critical is missing.

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

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

Schema covers 100% of parameters with detailed descriptions, so baseline is 3. The description adds meaningful context about the request_id lifecycle (first vs. second call, approval semantics) and the folder_id format (Graph vs. IMAP) that reinforces but doesn't contradict the schema. It enriches but doesn't fully compensate for the schema's completeness, so a 4 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 ('Delete a mailbox folder') and immediately clarifies scope ('including the messages it contains'). It clearly distinguishes from siblings like delete_message (single message) and move_message (moves messages out), so an agent can tell them apart without inspecting schemas.

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 instructs when to use the tool ('move them out first if they matter') and when not to ('the agent cannot approve'). The two-phase flow with request_id is described in detail, including what happens on repeated calls, which eliminates ambiguity about the approval workflow.

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

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

Goes far beyond the annotations (destructiveHint=true, idempotentHint=false): it discloses the two-phase human-approval flow, that the second call executes the *approved* arguments rather than the ones re-passed, request expiry (15 min), deduplication of identical pending requests, a 20/hour rate limit with status=rate_limited, audit logging, and the exact destruction semantics (moved to Deleted Items, expunged on IMAP, trash never emptied). This is exactly the behavioral context a destructive tool needs.

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?

Long but dense and front-loaded: the destructive two-phase protocol leads, followed by operational limits, then execution semantics, then the sibling alternative. Every sentence carries distinct information with no repetition of the annotations.

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, but the description names the return value ({success}) and the status codes an agent will encounter (approval_required, rate_limited, awaiting_approval). For a destructive, approval-gated tool this is complete enough to call and to handle responses correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it explains that request_id is omitted on the first call, what the first call returns, that approval happens out of band, and that the agent cannot self-approve. The schema already documents folder/account_id/message_id, so this is a modest but genuine increment.

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 one message') and immediately differentiates itself from the closest sibling by naming move_message as the reversible alternative. An agent can tell exactly what this does and what it does not do 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?

Explicitly routes the agent: use this to delete, but 'For reversible tidying prefer move_message, which is approved the same way but destroys nothing.' It also spells out the two-call protocol and what happens if approval is withheld, leaving nothing to inference.

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

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

Annotations declare destructiveHint=true and idempotentHint=false, and the description adds value beyond that: the trash-vs-permanent distinction, the fact that approved arguments (not the second call's arguments) execute, expiry (default 15 min), dedup of identical pending requests, and a 20 req/hour rate limit returning status=rate_limited. It also names auth requirements (connected Google account) and audit logging. No annotation contradiction.

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

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

Front-loaded with the purpose and the two-phase model, which is good. However it is long and mixes several distinct concepts (approval channels, expiry, dedup, rate limits, trash semantics, audit log, return shape) into dense prose without structure. Dense but each clause carries information; the cost is readability, not 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 destructive, human-in-the-loop mutation with no output schema, the description covers execution semantics, safety, recovery path, rate limits, expiry, and auth. An agent has everything needed to call it correctly in both phases and to explain the outcome to a user.

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 carries parameter detail. The description reinforces the critical semantic for request_id (execute the approved payload, not the second call's arguments) and notes file_id must come from drive_list_files. This adds real behavioral meaning over the schema for the request_id life-cycle.

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 ('Move a Google Drive file to the trash') and disambiguates from siblings like delete_message or delete_folder. The clarification that the file lands in trash (recoverable), not permanent erasure, sharpens the purpose beyond what the name implies.

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 two-phase protocol is spelled out explicitly: first call with no request_id does not execute, gets a request_id; human approval is required out-of-band before a second call executes. It even names what happens if the agent tries to shortcut approval (returns awaiting_approval). The agent knows exactly when to call and how to proceed.

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

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

Annotations already cover readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is declarative. The description repeats 'Read-only' (redundant with annotations) but adds the useful context that a connected Google account is required. No pagination, rate limit, or ordering behavior is disclosed beyond what schema describes.

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

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

Front-loaded with the core action and resource, then the response shape, then two short constraints. The inline response-shape notation is unusual but compact. Slightly awkward mixing of prose and shape notation, but no wasted sentences.

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 listing tool with full schema coverage and clear annotations, the description is nearly complete: it names the resource, includes the response shape, and mentions the auth prerequisite. It only lacks explicit discrimination from sibling listing/read tools, which is minor given the distinct verb and resource.

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 limit, query, and folder_id fully. The description does not add syntax or format hints beyond what is in the schema. Baseline 3 is appropriate.

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

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

States a specific verb (List) and resource (files on the user's Google Drive), and distinguishes itself from siblings like drive_read_file, drive_upload_file, drive_delete_file by making clear this is a listing operation. The inline shape of the response further concretizes what 'files' means.

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

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

The description implies usage ('List files on the user's Google Drive', with query/folder_id filtering described in the schema), but it never says when to use this vs drive_read_file or list_folders. No explicit when/when-not guidance is present.

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

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

Annotations already declare a safe, idempotent read, but the description adds real behavior beyond them: Docs/Sheets/Slides are converted to Office format before reading, the file is fetched to a temporary path and deleted immediately, and a connected Google account is required. These conversion, transient-storage, and auth details are exactly the context an agent cannot infer from structured fields.

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

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

Three short sentences, front-loaded with what is returned, then the conversion behavior, then the temp-file lifecycle. No filler and 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?

With no output schema, the description usefully states the return shape and covers auth and side effects, which is enough to call it correctly. Minor gaps remain: behavior on unsupported/non-exportable file types and error cases are unaddressed.

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?

Only one parameter, and schema description coverage is 100% ('File id from drive_list_files'). The description adds nothing about file_id itself, so the baseline of 3 applies; the schema does the heavy lifting.

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

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

States a specific verb (Extract the text) and resource (a Drive file) and even sketches the return shape {filename, kind, text}. This clearly distinguishes it from drive_list_files, drive_upload_file, and drive_delete_file, so an agent can pick 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?

The description implies the read use case and notes the prerequisite ('Requires a connected Google account'), and the 'read like any attachment' framing loosely parallels read_attachment. However, it never explicitly says when to use this versus drive_list_files or read_attachment, nor any when-not conditions.

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

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

Far exceeds the annotations. It discloses the two-phase approval workflow, out-of-band human approval channels behind biometric auth, request expiry (default 15 min), deduplication of identical pending requests, the 20-requests/hour rate cap, audit logging of every phase, and the rationale for approval (files can be shared onward and leave the machine). It also explains that execution uses the approved arguments, not the ones passed the second time — a critical nuance an agent cannot infer from annotations.

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

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

The core action and the two-phase model are front-loaded, and nearly every sentence carries a distinct operational fact (expiry, dedup, rate limit, audit, preview contents, return value). It is dense and fairly long, but the density is justified rather than padding.

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

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

For a write tool with no output schema, the description supplies everything needed: the approval lifecycle, the return value ({id, name, link, ...}), security constraints, and the prerequisite of a connected Google account. Nothing required to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by clarifying that the second call's argument values are ignored in favor of the previously approved payload, which is a semantic subtlety the property description only partly conveys. It also confirms the preview shows local path, resulting name, and destination folder.

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 first sentence states a specific verb and resource: 'Upload a local file to the user's Google Drive.' This cleanly distinguishes it from the drive_* siblings (drive_read_file, drive_list_files, drive_delete_file). An agent immediately knows what this tool does.

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

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

The description gives explicit procedural guidance: call once without request_id to get a preview, obtain out-of-band human approval, then call again with the same request_id to execute. It also states when requests expire and when they are refused (rate_limited), which is strong when-to-use/when-not context. It does not name any alternative tool, but no sibling overlaps this upload use case, so the omission is minor.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar for extra disclosure is met with the connected-calendar prerequisite and the explicit statement that it never books. It also discloses that time zone, weekends, working hours, minimum notice and inter-event gaps are handled internally, which is genuine non-obvious behavior.

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

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

Front-loads the return shape in the first sentence and packs routing, precondition and safety notes into a compact block. Slightly dense but every sentence carries a distinct fact; nothing is padding.

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

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

With no output schema, the description compensates by describing the return structure ({count, slots:[{start,end,label}], nota}) and the meaning of `label`. Combined with the auth prerequisite and the booking-side routing, an agent has everything needed for a 7-param, all-optional tool.

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

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

Schema description coverage is 100%, so the schema already documents all seven parameters, and the description adds no per-parameter syntax or format detail. Its mention that working hours, weekends, notice and gaps are 'already handled' loosely maps to work_start/work_end, skip_weekends and min_notice_hours but adds no new 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 and resource — computing free meeting slots from the calendar — and explicitly names the sibling it replaces (list_events) and the sibling that books (create_event). An agent can select it without opening any schema.

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

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

Gives an explicit routing rule ('use this instead of deriving availability from list_events') plus the write-path alternative ('use create_event for that, which needs human approval'). It also states the precondition of a connected Microsoft or Google calendar.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds 'Read-only, local' (local is extra), explains that fields may be empty strings, describes the {} return for no account, and clarifies the file_paths semantics referencing list_knowledge_files. This goes beyond the annotations without contradicting them.

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

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

Two tightly written paragraphs: the first defines purpose and context in one sentence, the second details return structure and edge cases. No filler or redundancy; every sentence adds value.

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

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

With no output schema, the description carries the burden of return format, and it does so comprehensively: field names, types (strings, file_paths), empty-string behavior, {} for no account, and reference to list_knowledge_files. Nothing an agent needs to call it correctly is missing.

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

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

The schema description for account_id already fully explains the parameter ('integer id from list_accounts', omit/null = active account) with 100% coverage. The tool description adds no further parameter detail, 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 uses a specific verb ('Return') and resource ('user's self-description for an account'), then enumerates the exact fields (who_am_i, what_i_do, tone, key_info, file_paths) and their purpose ('context for drafting replies in their voice'). This clearly distinguishes it from sibling tools like list_accounts or list_knowledge_files, even though it doesn't name 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?

The description states when to use it ('context for drafting replies in their voice') and indirectly points to an alternative ('see list_knowledge_files' for file paths). It doesn't explicitly say when not to use it, but the context is clear enough for an agent to choose it appropriately.

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?

Beyond the annotations (readOnly, idempotent), the description adds critical behavioral details: 'without credentials', 'Read-only, local, no network call', and 'Returns an empty list if nothing is configured'. These are not redundant with annotations and fully inform the agent about side effects and data source.

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

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

The description is compact and front-loaded with the core purpose, followed by return structure and usage notes. Every sentence adds value, and there is no extraneous 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 zero-parameter tool with an output schema, the description explains the return fields and their meanings, clarifies the default account behavior, and covers how accounts are managed. An agent can call this tool correctly without needing further details.

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

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

There are no parameters, so the schema trivially covers everything. The description doesn't need to elaborate on parameters, and the baseline of 4 is appropriate given zero parameters.

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

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

The description clearly states the verb (List), the resource (email accounts), and the scope (configured in GigaMail). It also distinguishes itself from siblings by specifying it deals with account configuration, not messages or events.

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

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

It explicitly instructs how to use the output ('Use `id` as account_id in the other tools') and clarifies that accounts are added only via CLI, so there is no alternative tool for this purpose. This gives clear when-to-use context.

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

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

Annotations already declare readOnly/idempotent/destructive=false, so safety is covered; the description goes beyond them by disclosing that output shape is identical across Microsoft Graph and Google Calendar, and that it returns [] or an error on IMAP-only setups. No rate limits, pagination, or ordering behavior is mentioned, keeping it out of the top band.

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

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

Front-loaded with the core verb and range, then progressively adds provider, error, and alternative detail. Every sentence earns its place, though the provider-shape remark is slightly verbose for a list tool.

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

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

An output schema exists, so return values need not be re-explained; the description still contributes the provider-agnostic guarantee and the empty/error case. Combined with annotations and a fully documented 2-param schema, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds the anchor semantics the schema lacks — both parameters are relative to 'today' and combine into a single closed interval. It does not add format or edge-case guidance (e.g., large values), so it modestly exceeds baseline.

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

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

States a specific verb+resource (calendar events) and immediately bounds it with a concrete window formula, [today - days_back, today + days_ahead]. The provider note and the find_free_slots pointer make it clearly distinguishable from sibling list 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?

Explicitly routes the agent: 'To propose meeting times prefer find_free_slots, which already applies working hours and margins' — a named alternative with a selecting condition. It also flags the no-calendar-connected failure case. It stops short of stating when-not to use this tool (e.g., vs. list_accounts for setup discovery), so it is not a full 5.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the read-only nature is covered. The description adds value by revealing that it queries the provider and by explaining the Graph vs IMAP identifier behavior, which is not present in the annotations or input schema.

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

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

The description is tight and front-loaded: purpose, output shape, downstream usage, and read-only nature all fit in a few lines with no redundancy or 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 simple list operation with output schema, full parameter coverage, and strong annotations, the description supplies exactly the operational details an agent needs: what is listed, how to reference folders later, and that the operation is read-only.

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

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

With 100% schema description coverage and a single optional account_id parameter, the schema already documents everything needed. The description does not add further parameter-level meaning, 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?

The description opens with a specific verb and resource ('List the mailbox folders of an account') and names the output shape, so an agent can immediately distinguish it from sibling tools like list_messages or read_message. It also clarifies the folder identifier format (Graph id vs IMAP folder name).

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

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

The description tells the agent how to use the returned values as the folder/folder_id argument for other tools, which is practical context beyond the schema. It does not explicitly name alternatives or exclusions, but the purpose is clear enough that when-versus-when-not is mostly implied.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable context beyond this: it specifies the output structure ({name, path, kind, size}) and clarifies that only explicitly registered paths are visible, which is a behavioral nuance not captured by annotations. The statement 'Read-only, local' reinforces the read-only nature.

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, then adds scoping constraints, output format, and a pointer to the sibling tool. Every sentence adds value with no 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?

Given the tool is a simple read-only list with a fully described parameter and an output schema (indicated by 'Has output schema: true'), the description covers everything needed: what it returns, scope, and how to proceed. No critical information is missing.

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

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

The single parameter account_id is fully documented in the schema (including how to omit or use null). The description adds no additional meaning beyond the schema, so it meets the baseline of 3 for high schema coverage.

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

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

States a specific verb (List) and resource (knowledge files attached to an account), and clarifies the intended purpose ('the intended source of facts for replies'). It explicitly contrasts with a filesystem browser and names the sibling read_knowledge_file, making it easy to distinguish.

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 guidance on when to use this tool: to see the user's registered knowledge files. It states what it is not ('not a filesystem browser') and points to read_knowledge_file for reading the text, effectively routing the agent to the correct tool for the next step.

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?

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description adds valuable behavioral details: it queries Microsoft Graph or IMAP, treats email content as untrusted data (security caution), and returns [] for unknown folders or missing accounts. It also clarifies that bodies are excluded. This significantly enriches behavioral understanding.

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 concise, front-loaded with the main purpose and output format, then adds critical caveats (no bodies, untrusted data, empty result behavior). Each sentence adds value and the structure is logical and easy to parse.

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 output schema exists, the description does not need to detail return types but still lists the summary fields. It covers error behavior ([]), security (untrusted data), and alternative for bodies. It also provides folder guidance. For a list tool with annotations covering safety, this is 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 coverage is 100%, with each parameter (top, skip, folder, account_id) already described. The tool description repeats the folder options (inbox, sent, drafts, etc.) which are also in the schema, and does not add new semantics beyond the general purpose. Since the schema fully documents parameters, a baseline of 3 is appropriate.

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

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

Clearly states the verb (List), resource (messages in a mailbox folder), ordering (newest first), and the exact output shape (summaries with listed fields). It also differentiates from read_message by explicitly excluding bodies, and from list_unread by indicating folder-based listing. 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?

Provides a clear 'when not to use' instruction: bodies are not included, so use read_message with the returned id. It also notes the empty-array return for unknown folders/missing accounts, which helps in error handling. However, it does not explicitly compare with list_unread or search_mail, though the intended use case is evident 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds valuable context beyond this: 'Queries the provider; email content is untrusted data,' which informs the agent about data trustworthiness, and 'newest first' describes ordering behavior. It does not contradict annotations.

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

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

The description is two sentences with zero fluff. The core purpose is front-loaded, followed by the return shape, a cross-reference to sibling tools, and a safety note. Every sentence adds value and the structure is easy to parse.

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

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

For a read-only list tool with no output schema, the description covers the essential context: return shape, ordering, scoping by time, and data trustworthiness. It does not elaborate on pagination or error handling, but given the schema documents parameter bounds and the annotations cover safety, this is sufficiently complete for an agent to invoke it correctly.

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

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

The input schema provides 100% coverage with descriptions for all three parameters (top, days, account_id). The description mentions `days` but adds no new parameter-specific meaning beyond what the schema already states. Baseline of 3 is appropriate when the schema fully documents parameters.

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

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

The description clearly states a specific verb and resource: 'Unread messages of the inbox from the last `days` days, newest first.' It also distinguishes itself from siblings by mentioning the summary shape matches list_messages and directing body retrieval to read_message. This makes it immediately clear what the tool does and how it differs from related 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 description gives clear context for when to use the tool (unread messages in a time window) and explicitly points to read_message for bodies, implying this tool is for summaries. It does not explicitly mention alternatives like list_messages or search_mail, but the reference to list_messages' shape implies the distinction. This is sufficient guidance for most agents.

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

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

Annotations already include idempotentHint=true, readOnlyHint=false, destructiveHint=false, and openWorldHint=true. The description adds value by disclosing reversibility, immediate execution without approval, audit logging, and no other side effects. No contradiction.

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, clearly structured, with every sentence earning its place. The most important facts (what it does, reversibility, side effects) are front-loaded.

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

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

For a simple mark-as-read tool with full schema coverage and no output schema, the description is complete. It tells the agent what happens, what doesn't happen, and what to expect.

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 four parameters well. The description adds a slight behavioral note about execution, but doesn't need to add parameter-level detail because the schema already covers 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 ('mark'), resource ('a message'), and the two possible states (read/unread). The description clearly distinguishes it from siblings like move_message, delete_message, and send_mail.

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 the operation is reversible and immediate, and mentions the audit log. It doesn't explicitly state when to use this vs reading a message, but the purpose is clear enough for an agent to infer context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by specifying the exact data returned (index counts, embedding status, last run) and stating 'Local, read-only, no parameters.' This reinforces and extends the annotation safety profile without contradiction. It doesn't cover edge cases like latency or errors, but for a zero-parameter health check, this is adequate.

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

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

The description is two sentences: the first front-loads the purpose and returned metrics, the second gives usage context and constraints. Every word earns its place; no fluff or repetition. It is efficiently structured for quick agent parsing.

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

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

For a zero-parameter, read-only health check, the description is complete. It explains what the tool returns, how to use it, and its relationship to sibling tools. There is no output schema, but the description sufficiently covers the return content. Nothing an agent needs to decide whether to call it 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?

There are zero parameters and the schema is empty, so the baseline is 4. The description explicitly notes 'no parameters,' which is redundant but harmless. Since there is nothing to explain about parameter semantics, the score reflects that the tool needs no further parameter documentation.

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

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

The description clearly states the tool's purpose: reporting the health of GigaMail's local mail index, listing specific metrics (indexed threads, messages, senders, embedding status, last run). It distinguishes itself from search_mail and sender_history by explicitly framing itself as a health check for those tools, making its role unambiguous.

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

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

The description gives a specific use case: 'Use it to know whether search_mail's local_index and sender_history can return anything.' This is clear context for when to call the tool. It doesn't explicitly list alternative tools or when not to use it, but the reference to search_mail and sender_history implies the decision point. Slightly more explicit exclusions would earn a 5, but it's strong.

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?

Rich disclosure beyond annotations — two-phase approval, expiry, deduplication, rate limits, audit logging, and the IMAP UID-reassignment caveat that invalidates the old message_id. Would be 5 if it stated whether the out-of-band approval needs to happen within the same session or what happens if the payload arguments differ from the second call (partially covered by 'the approved arguments, not the ones passed the second time').

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 verb+resource, then the critical two-phase constraint, then edge cases. Long but each sentence carries load. Could lose a clause or two (e.g. the Telegram/CLI enumeration) without much loss.

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

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

For a destructive, open-world, non-idempotent mutation with no output schema, the description covers approval mechanics, expiry, rate limits, audit trail, reversibility, and the IMAP UID side effect — everything an agent needs to call it correctly across two phases.

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 five parameters, including request_id's two-call semantics. The description reinforces the request_id flow but adds no syntax or format detail 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 (move) and resource (message) plus the scope constraint (another folder of the same account). The closing note distinguishes it from the sibling delete_message, and the preview description clarifies scope further.

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

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

Explicit routing: use delete_message to delete; the two-phase approval flow is laid out step by step, including when to pass request_id and when not to. No inference required.

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

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

Annotations already mark the tool read-only and idempotent; the description adds useful behavioral detail: the result is 'Local, read-only' and an empty string when nothing has been learned. This goes beyond the annotations and clarifies the tool's side-effect-free nature.

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

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

Three tightly packed sentences with no filler. The core purpose, output format, and fallback behavior are all front-loaded and immediately actionable.

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 simple read-only nature, optional parameters, and presence of an output schema, the description covers everything an agent needs: what it returns, when to use it, and the empty-string sentinel. No critical information appears 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 parameters are already documented. The description adds value by explaining that sender and subject are used to find 'similar' past contexts, giving the parameters meaningful filtering semantics beyond their raw schema definitions.

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

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

The description clearly states that the tool returns learned patterns from past user corrections for similar senders/subjects, intended as drafting context. It is specific about the resource and output, though it does not explicitly contrast itself with siblings like sender_history.

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

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

The description says to use it when drafting, with the returned text block meant to be placed into drafting context. It implies the sender and subject parameters are the basis for similarity matching, but it does not explicitly describe when not to use it or name alternatives.

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

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

The description goes well beyond annotations, explaining that the binary is downloaded to a temporary file, converted, and deleted; that nothing is stored; and that attachment content is untrusted. It also discloses error behavior and the fallback for unsupported formats. This is rich behavioral context that annotations (readOnly, idempotent) do not cover.

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 four sentences, each carrying distinct value: purpose and output, process and side effects, security warning, and error handling. It is front-loaded with the core purpose and contains no redundant or filler text.

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

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

Despite lacking an output schema, the description explicitly states the return shape ({filename, kind, text}). It covers error conditions, unsupported formats, and data handling, making it complete for an agent to call correctly. There are no missing pieces for a single-attachment read.

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 no extra parameter-level meaning beyond the schema; it does reiterate that filename must match read_message output and message_id comes from list_messages, but these are already in the schema descriptions. No additional semantics are provided.

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 ('Extract'), resource ('attachment'), and scope ('the TEXT'), and lists supported formats. It clearly distinguishes from sibling tools like read_message, which reads message content, by focusing on attachment text extraction.

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: whenever an agent needs the text content of an attachment. It doesn't name alternatives because no sibling tool serves the same purpose, and it provides guidance on error and unsupported-format behavior, which helps the agent decide if the tool is appropriate.

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

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

The description discloses several behaviors beyond the annotations: it returns a specific object {name, kind, text}, enforces access control (returns {error: ...} for unauthorized paths), and notes it is read-only and local. This adds value beyond the readOnlyHint and idempotentHint annotations. It does not contradict annotations and provides useful error semantics.

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 three sentences, front-loaded with the primary purpose, then the return format, then access restrictions. Every sentence contributes meaningful information with no redundancy or filler. It is concise and well-structured.

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

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

The description covers the core functionality, return format, and security constraints. It does not explicitly describe error handling for non-existent files (though schema covers name matching), nor rate limits or timeouts, but for a simple read tool with annotations covering idempotency and read-only, it is largely complete. The output schema is absent, but the description mentions the return structure. Minor gaps remain, so 4 is justified.

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 (name and account_id) are already thoroughly documented in the input schema. The tool description adds no extra parameter information; it only mentions access limitations in general. With complete schema coverage, the baseline of 3 is appropriate.

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

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

The description states a specific verb ('Return'), a resource ('extracted TEXT of one registered knowledge file'), and the file types it covers. It also clarifies that it returns the text content, not metadata, distinguishing it from list_knowledge_files. The purpose is unambiguous and well-scoped.

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 does not explicitly mention when to use this tool versus alternatives like list_knowledge_files. It implies that access is limited to registered files but does not state that list_knowledge_files should be used first to obtain valid names, nor does it mention any exclusions or when-not-to-use conditions. Usage guidance is minimal.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds critical behavioral context beyond those: the body is flagged as untrusted data with a security directive, attachment binaries are never returned (only metadata), and errors are raised for missing or mismatched ids. This meaningfully informs the agent about side effects and data handling.

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 dense but every sentence earns its place: it lists the return payload, states the attachment limitation, issues a security warning, and specifies error behavior. It is well-structured with the return format first, followed by exclusions and caveats, without wasted words.

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

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

With no output schema, the description fully explains what the tool returns, including nested objects (body content and type, attachment metadata) and the plain-text excerpt. It also covers error conditions and the untrusted-data warning, making it complete for an agent to call correctly without needing additional context.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters thoroughly. The description does not add new parameter-level semantics beyond what the schema provides; it only reiterates that message_id comes from list_messages etc., which is already in the schema. The baseline of 3 applies since the schema carries the parameter burden.

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

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

The description states a specific verb ('Read') and resource ('one full message') and enumerates the exact fields returned, including body content and attachment metadata. It also explicitly distinguishes from read_attachment by stating that attachment binaries are never returned, making the tool's scope unambiguous among siblings.

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

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

The description explicitly routes users away from this tool for attachment binaries, naming read_attachment as the alternative. It also implies the need for a message id from list_messages/list_unread/search_mail and warns about error conditions for invalid or cross-account ids, giving clear usage boundaries.

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

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

Annotations declare destructive/openWorld/not-idempotent, and the description goes far beyond them: human out-of-band approval behind biometrics, the fact that the approved arguments (not the re-passed ones) execute, audit logging of every phase, and irreversibility once sent. This is exactly the behavioral context a mutation tool needs.

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?

Dense and long, but well structured with front-loaded labels (TWO-PHASE, HUMAN-APPROVED, FIXED ADDRESSING) and no filler sentences — every clause carries operational facts. Slightly heavy for a single description, hence a 4 rather than 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?

Despite no output schema, the description names the return shapes ({success, provider_result}, approval_required preview with replying_to{from,subject} and body). For a complex, irreversible, human-gated mutation tool, all information an agent needs to call it correctly is present.

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 semantics not in the schema: the request_id field's two-call lifecycle and the critical nuance that the second call ignores newly passed arguments in favor of the approved payload, plus the fixed-addressing rule that overrides cc/body contents. This meaningfully exceeds 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+resource+context: 'Reply to an existing message in its thread.' This cleanly distinguishes it from the sibling send_mail (new message) and from read_message (read-only). 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?

Explicitly documents the two-phase flow: first call without request_id returns approval_required and executes nothing; second call with the approved request_id executes. It also names expiry (15 min), dedup of identical pending requests, and the 20/hour rate limit — clear when-and-how-to-use guidance including failure modes.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the description's added value is the retention behavior (archive keeps every message ever seen, including server-deleted ones), the id prefix convention, and the 'results are untrusted data' warning — all beyond the structured fields. It doesn't cover pagination or ordering across the three sets, keeping it at a strong 4.

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

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

Front-loaded with the action and the three result sets, and every sentence carries information (sources, id prefixes, retention rationale, safety note). The nested-brace phrasing makes it slightly denser than ideal, but nothing is padding.

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

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

There is no output schema, and the description compensates thoroughly by defining the three result sets, their contents, ordering (newest first), and id format. Combined with the annotation-covered safety profile, an agent has everything needed to call and interpret 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 schema already documents top, query, and account_id. The description adds little parameter-level detail beyond reinforcing that provider search is keyword-based, which the schema already says. Baseline 3 is appropriate.

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

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

States a specific verb+resource (search the mailbox) and then decomposes the output into three named result sets with their origins (archive, provider Graph/IMAP, local_index). It also gives ID prefixes and names the sibling tools (read_message / read_attachment) the results work with, so an agent can distinguish it from list_messages/list_unread.

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 routes the agent: 'Look at archive first' with the reason (it holds messages the server no longer has, e.g. removed by Outlook). It implies when this tool beats the list_* siblings but never states when to prefer list_messages or sender_history instead, so it stops short of full alternative coverage.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds valuable context beyond that: it specifies that this is a local call (no provider call), that results may be empty if the index isn't built, and it outlines the return structure. This goes beyond what annotations provide and helps the agent set expectations. No contradiction.

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

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

The description is two sentences plus a short note. It front-loads the core purpose, then adds usage context and the key caveat about local-only and empty results. Every sentence earns its place with no redundancy or fluff.

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

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

For a read-only tool with two well-documented parameters and no output schema, the description covers the essential points: what data it returns (profile and context), when it's useful, the local-only nature, and when it returns empty. It could be slightly more explicit about the exact fields, but the example placeholders give sufficient orientation. Overall complete for an agent to call it correctly.

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

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

Schema description coverage is 100%, so both parameters (email and account_id) are already documented in the schema. The description doesn't add much about parameter semantics beyond what the schema says, but it implicitly connects the email parameter to the sender being queried. Since the schema does the heavy lifting, a baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: it retrieves what GigaMail's local index knows about a sender, including profile and context. It distinguishes itself from siblings by focusing on sender-level metadata rather than message content or account info, so an agent can differentiate it from list_messages or get_identity.

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

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

The description gives clear context for when to use it ('useful to reply in the right register and avoid repeating yourself') and notes that it is local-only and empty when the index hasn't been built. It doesn't explicitly name alternatives or state when not to use it, but the local-only and empty conditions effectively guide usage. Lacks explicit exclusions, but the guidance is strong.

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

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

Discloses a great deal beyond the annotations: two-phase human approval via Windows Hello/Touch ID, out-of-band console/CLI/Telegram approval, argument binding to the approved payload, expiry, deduplication, a 20/hour cap returning status=rate_limited, audit logging, preview contents, and that the action is irreversible once sent. All of this is consistent with destructiveHint=true and idempotentHint=false, so nothing contradicts the annotations.

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

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

Front-loads the core action and the critical TWO-PHASE, HUMAN-APPROVED constraint, which is what an agent most needs to know first. It is dense with operational detail (rate limit, dedup, audit log) that is justified for a destructive send, though a couple of clauses could be trimmed.

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

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

With no output schema, the description carries the full burden of explaining returns and does so: first-phase status=approval_required with preview, and the execution result shape {success, provider_result {requested, accepted, ...}} with the SMTP vs Graph difference. Nothing needed to call 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 coverage is 100%, so the schema already documents every parameter including request_id, attachments, to, and body. The description reinforces a few nuances (recipient addresses shown as raw addresses with may_expand, signature auto-appended) but mostly restates 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 a new email from the user's account'). The word 'new' implicitly distinguishes it from the sibling reply_mail, and the two-phase framing sharpens what kind of send this is without requiring 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 context for how and when to invoke it: first call without request_id, second call with it after human approval, plus rate/expiry behavior. It does not explicitly route the agent to reply_mail as the alternative for replying, so it stops short of 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.