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

The description is exceptionally transparent, detailing complex operational behaviors such as the two-phase nature, return status (approval_required), expiration (15 min), deduplication, rate limits (20/hr), and specific requirements for human approval (CLI/Telegram/Touch ID). This far exceeds the coverage of the provided 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?

Although very long, the structure is highly effective. The description uses deliberate pacing to separate the operational phases (Phase 1 vs Phase 2), ensuring that the necessary complexity is front-loaded and logically organized.

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 high complexity of a two-phase, asynchronous, rate-limited, human-approved workflow, this description is perfectly complete. It identifies dependencies (connected calendar, find_free_slots) and covers all failure and operational modes.

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?

While the schema covers the types, the description is vital for `request_id` to define its operational function. It clearly explains that the parameter must be omitted on the first call and used only for subsequent execution, adding critical meaning beyond the basic schema definition.

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 purpose is immediately clear: to create a calendar event. It effectively distinguishes itself from sibling tools like list_events or delete_event by introducing a unique, complex, and asynchronous two-phase workflow.

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

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

The description provides extensive usage guidelines. It explicitly states the dependency on calling find_free_slots first, and critically, details the conditional usage of the request_id (use it for phase 2 only).

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?

Goes far beyond the annotations (readOnlyHint=false, destructiveHint=true, openWorldHint=true, idempotentHint=false): it discloses out-of-band human approval behind Windows Hello / Touch ID, 15-minute expiry, deduplication of identical pending requests, a 20-requests/hour refusal with status=rate_limited, and full audit logging. Critically, it warns that the executed payload is the approved arguments, not the ones passed the second time — a non-obvious behavior no annotation conveys.

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 the two-phase mechanic before the secondary branches; every sentence carries operational weight, including the rate-limit and expiry details. It is dense — one long block covering approval, dedup, throttling, return shape and two fallbacks — which costs a bit of scannability.

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 mutating, externally-visible, human-gated tool with no output schema, it supplies exactly what is missing: return payloads per branch ({id, join_url, password} vs {join_url, fixed_link: true}), failure statuses (approval_required, awaiting_approval, rate_limited), and the instruction to ask the user for a personal link when neither prerequisite exists.

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 nevertheless adds real meaning to request_id — that omitting it yields a preview, that the agent cannot self-approve, and that resubmitting without approval only returns awaiting_approval. It also clarifies the practical consequence of approval (meeting created with waiting room on, no participants invited), which the schema does not.

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

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

States a specific verb and resource ('Create a Zoom meeting on the user's connected Zoom account') plus the side effect that matters (returns the join link). The Zoom-specific framing cleanly separates it from calendar siblings like create_event, and the fallback branches (personal fixed link, no link at all) are named explicitly.

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

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

Gives explicit when-to-use routing: call once without request_id to get an approval preview, call again with the returned request_id to execute, and hand the join_url to send_mail/reply_mail 'which need their own approval.' It also states the when-not path — if a fixed personal link exists, nothing is created and no approval is needed.

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 readOnly/idempotent annotations, it discloses that bodyPreview is deliberately empty because the provider's preview may leak text, that email content is untrusted data, and that an unknown folder or missing account yields [] rather than an error. These are exactly the behavioral details annotations cannot carry.

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

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

Front-loaded with purpose, then return fields, then the exclusion and its rationale, then operational caveats — a logical order with little waste. The parenthetical about bodyPreview is slightly convoluted but justifies itself by explaining a non-obvious empty field.

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 four-parameter read tool with an output schema, the description still covers the returned summary fields, the empty-body caveat, the empty-list failure mode, and the untrusted-content warning. There is no material gap an agent would need to close before calling it.

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

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

Schema description coverage is 100%, so top, skip, folder and account_id are already fully documented in the schema. The description only reinforces the 'newest first' ordering tied to top/skip and adds no new format or edge-case detail for the 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?

States a specific verb and resource ('List messages in a mailbox folder'), plus the ordering ('newest first') and the exact shape of each summary ({id, subject, from, receivedDateTime, isRead, hasAttachments}). It also explicitly excludes bodies/previews, which separates it from read_message and search_mail without needing either schema.

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

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

Gives an explicit follow-up path: use read_message with the returned id when bodies are needed, which defines the boundary of this tool's purpose. It does not, however, contrast itself with search_mail or list_unread, which an agent may confuse for a comparable listing operation.

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?

Well beyond the annotations (which only cover read-only/idempotent/no-destruction), it discloses the temp-file download-convert-delete lifecycle, that nothing is persisted or passed to the agent but text, a prompt-injection warning that attachment content is untrusted, and the divergent outcomes for missing files, unsupported formats, and executables. These are exactly the behavioral traits an agent needs before calling.

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?

Five tight sentences, each carrying distinct information: capability first, then return shape, then side-effect model, then safety caveat, then edge-case outcomes. No filler and the most important facts (text-only extraction, temp-file deletion) 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?

No output schema exists, yet the description declares the return object shape {filename, kind, text} and explains how errors and unsupported/executable cases surface in `text`. Combined with the temp-file lifecycle and untrusted-data note, an agent has everything required to call it correctly and interpret results.

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

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

Schema description coverage is 100%, with all four parameters (including folder, account_id, message_id, filename) fully documented in the schema itself. The description adds only the notion of 'one attachment' and sides with the schema's guidance implicitly; it contributes no new format or constraint details, so baseline 3 applies.

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

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

States a specific verb and resource — 'Extract the TEXT of one attachment' — and enumerates the supported formats (pdf, docx, xlsx, txt, csv). An agent can immediately distinguish this from read_message (body text) and drive_read_file (cloud drive files) without opening a schema.

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

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

The description gives clear operating context: it targets a single attachment, errors when the attachment is missing, and short-circuits executables. It does not explicitly name an alternative or state when to prefer read_message/drive_read_file instead, so it falls short of full when/when-not guidance, but the applicable scenario is unambiguous.

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?

Beyond the readOnly/idempotent annotations, it discloses important behavior: body is the reader-visible text only, hidden content is flagged via `hidden_text`, links are listed and untrusted, executables are flagged with a `warning`, and the body is untrusted data not to be obeyed. These are non-obvious traits an agent could not 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?

Front-loaded with the return shape, then the security caveats, which is the right order. It is long and slightly repetitive in its trust warnings, but nearly every sentence carries operational value.

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

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

There is no output schema, and the description compensates by describing the full return shape including conditional fields (hidden_text, warning) and the absence of attachment binaries. Nothing essential for calling or interpreting the result 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 folder/account_id/message_id semantics are already documented in the schema. The description adds only a marginal note that an id belonging to another account errors out; 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?

Opens with a specific verb and resource ("Read one full message") and then enumerates the returned fields, so an agent knows exactly what it gets versus siblings like read_attachment. It also distinguishes itself from read_attachment by stating attachment binaries are never returned here.

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 attachment text to read_attachment and states the failure conditions (id does not exist or belongs to another account). It does not discuss when to use this versus list_messages or search_mail, but the read-one-by-id use case is unambiguous.

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 readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=true, so the safety profile is covered and the bar is lower. The description still adds real behavior: the draft lives on the server in Drafts until sent or deleted, nothing is sent so it runs without approval, the action is audit-logged, and a partial-failure mode exists (in_mailbox=false with the reason in error). It does not state whether re-saving overwrites an existing draft_id, which matters for a tool whose annotations mark it non-idempotent.

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

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

Front-loaded with purpose, then usage, then caveats, then return shape – a sensible order with little waste. It runs slightly long and the awkward line breaks bury the audit-log note mid-sentence, but every clause carries information an agent would otherwise have to guess.

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 by spelling out the return object {success, draft_id, in_mailbox, folder, error} and interpreting the one ambiguous field. Combined with the IMAP/POP caveat and the no-attachments limitation, nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning the schema does not: drafts carry no attachments at all (so no attachment parameter is offered), and reply drafts address the original sender rather than Reply-To or any address written in the body.

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 plus the crucial distinction: 'Save an email as a draft instead of sending it', and immediately locates it on the provider's server in the Drafts folder. An agent can tell this apart from send_mail/reply_mail 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 when-to-use condition ('the user wants to read, change and send the mail themselves... or asks for a draft') and names alternatives for the cases it does not cover ('Attachments are not saved with drafts... use send_mail / reply_mail'). It also flags a platform edge case: on IMAP accounts a POP-configured mail app will not show the draft.

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/closed-world, and the description adds real context beyond them: the local index is refreshed on file change, only registered files are searched, results are ordered best-first, and an empty array is returned on no match. That is exactly the behavioral context an agent 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?

Front-loads the core action and return shape, then adds the routing hint and the empty-result contract. No sentence is filler; the density is appropriate for a retrieval tool.

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

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

With an output schema present, the description needn't explain return values, and it still sketches them. Annotations cover safety, the description covers scope, refresh behavior, and the empty case — nothing an agent needs is missing.

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

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

Schema description coverage is 100%, so query, limit, and account_id semantics (including "matched by content, not by file name") are already fully documented in the schema. The description's "most relevant passages, best first" only echoes the limit parameter, so baseline 3 applies.

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

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

States a specific verb and resource ("Search INSIDE the account's knowledge files"), names the content types searched, and shows the exact return shape [{name, path, excerpt, score}]. It is clearly distinguishable from siblings like read_knowledge_file and search_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?

Explicitly names when to use it ("for prices, conditions and codes before reading a whole file") and names the alternative (read_knowledge_file) plus the condition that selects it. It also scopes usage to files the user registered.

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 and non-destructive, but the description adds substantial behavior: archive retains every message ever seen including server-deleted ones, provider previews are withheld, local_index rows have no mail text, archive ids begin with 'arch-' and work with read_message/read_attachment. It also flags results as untrusted data, which is a real safety signal not present in annotations.

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

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

Purpose is front-loaded and every clause carries information, including the persistence caveat and the id prefix detail. The nested brace notation for the result sets is dense and slightly harder to parse than a bulleted list would be, which keeps it from a 5.

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

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

There is no output schema, so the description bears the burden of explaining return shape and does so precisely — three named sets, what each contains, ordering, preview availability, and how archive ids interoperate with read_message and read_attachment. Nothing an agent needs to interpret results 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 `top`, `query` and `account_id` are already documented in the input schema, and the description does not elaborate on any of them (no syntax, no per-source semantics for `top`, no account-scoping behavior). The description's value here is limited to ordering ('newest first') and the fact that limits are per source, which is marginal 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 and resource ('Search the mailbox') and immediately enumerates the three result sets (archive, provider, local_index), which no sibling tool produces. An agent can distinguish it from list_messages, list_unread and sender_history 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 clear operational guidance: 'Look at `archive` first' because it retains messages the server has dropped, and it explains which result sets carry usable previews. It stops short of explicitly naming alternatives (list_messages, list_unread, sender_history) or stating when not to use this search, so it is context-rich but not fully routing.

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

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

Annotations already declare 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.