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

Goes far beyond annotations by detailing the two-phase approval mechanism, request expiration, deduplication, rate limiting, audit logging, the reason approval is required (invitations), and the fact that the second call uses approved arguments rather than passed ones. No contradiction with annotations.

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

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

The description is dense but well-structured: it opens with the core action and approval requirement, then systematically covers expiry, dedup, rate limits, audit, preview, return, and prerequisites. Every sentence carries necessary information, though it is lengthy.

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

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

For a tool with a complex two-phase approval and security-sensitive behavior, the description covers all critical aspects: the flow, security, rate limits, return format, and account requirement. No output schema exists, but the return value is described. An agent has enough to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds context about the request_id flow (approval, preview, and execution) which is also covered in the schema, but it reinforces the behavior without adding new semantics for other 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 ('Create'), resource ('calendar event'), and scope ('on the active Microsoft account'). It clearly distinguishes from siblings like delete_event, list_events, and find_free_slots by naming the action and resource 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?

Explicitly advises 'Find times with find_free_slots first', giving a clear precondition. It also describes the required two-phase approval flow, but does not name alternative creation tools or explicitly state when not to use this tool beyond that.

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?

The description goes far beyond the annotations by disclosing the two-phase approval mechanism, the need for human out-of-band approval, the rate limit (20 requests/hour), request expiry, deduplication, audit logging, and the cancellation behavior for attendees. It also clarifies that the second call uses the approved arguments, not the ones passed. This is rich behavioral disclosure with no contradictions.

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 appropriately detailed for a complex two-phase approval tool. It is front-loaded with the core purpose and then systematically covers the approval flow, limits, and behaviors. Every sentence contributes meaningful information without redundancy, making it efficient 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?

Given the tool's complexity, the description covers all necessary aspects: purpose, two-phase approval, human requirements, rate limits, deduplication, expiry, audit, cancellation impact, return value, and account prerequisite. There is no output schema, but the description states it returns {success}. Nothing an agent needs to correctly invoke this tool 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 input schema already provides comprehensive descriptions for both parameters (event_id and request_id), including the two-phase flow. The description adds some nuance (e.g., 'the approved arguments, not the ones passed the second time') but largely reiterates the schema. With 100% schema coverage, the description adds little beyond the baseline.

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

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

The description states a specific verb (delete), a clear resource (calendar event), and a scoping context (active Microsoft account). It also details the two-phase approval flow, which distinguishes this tool from any sibling deletion tools. The purpose is unambiguous and immediately actionable.

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 on when to use the tool (deleting calendar events) and includes important operational constraints like the two-phase approval requirement, rate limits, and deduplication. However, it does not explicitly contrast with alternatives (e.g., delete_message or delete_folder), leaving the agent to infer that it is only for events. This is a minor gap, hence 4 rather than 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 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?

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds substantial context: two-phase approval with preview, audit logging, request expiry, deduplication, rate limits, the exact execution behavior (moved to Deleted Items / expunged), and that GigaMail never empties the trash. This goes far beyond the structured hints and gives an agent full visibility into side effects.

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 key constraint (two-phase, human-approved) is front-loaded immediately after the one-line purpose. Subsequent sentences cover expiry, deduplication, rate limiting, audit log, preview content, execution semantics, trash behavior, return value, and the alternative tool — all without fluff. It is dense but efficient.

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 tool with no output schema, the description fully covers what the agent needs: the approval flow, all possible statuses, parameter semantics, return value, and post-execution effects. It even clarifies edge cases like deduplication and rate limiting. There are no missing pieces an agent would need 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 enriches each parameter: it explains the message_id format per account type, the account_id default behavior, and the request_id two-phase lifecycle (omit → approval_required, then pass to execute). This adds meaning beyond the schema's own descriptions, so a 4 is warranted.

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 'Delete one message.' — a specific verb and resource — and immediately distinguishes itself from move_message by recommending it for reversible tidying. This clearly separates the tool from siblings like delete_folder and move_message, so an agent can pick it correctly without ambiguity.

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 states when to use the tool (permanent deletion) and when to prefer the alternative ('For reversible tidying prefer move_message'). It also outlines the mandatory two-phase human-approval flow, telling the agent exactly what the first and second calls do and that the agent cannot approve. No inference 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?

Annotations already declare readOnlyHint and destructiveHint, and the description reinforces this ('Read-only: it never books anything') while adding new context: it requires a Microsoft account, and it handles time zone, weekends, working hours, minimum notice, and gaps automatically. This goes beyond what annotations convey, providing critical operational details.

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 well-structured: it starts with the core purpose, then the output shape, then usage guidance, then prerequisites, and finally a clear read-only note. Every sentence adds value, with no filler. The 'nota' field is mentioned but not defined, which is a minor omission, but overall the structure is excellent.

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 output format, the pre-handled logic (time zone, weekends, etc.), the Microsoft account requirement, and the read-only nature. It lacks a definition of 'nota' and does not explicitly state that parameters like work_start/work_end override the defaults, but these are minor gaps given the schema's thorough parameter descriptions. Overall, the description is comprehensive enough for an agent to use 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%, and the schema already documents all 7 parameters with descriptions. The tool description does not add any parameter-specific semantics beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool computes free meeting slots from the calendar, with a specific output structure. It explicitly contrasts with list_events ('use this instead of deriving availability from list_events'), making it easy for an agent to distinguish this tool from its siblings.

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

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

The description provides direct usage guidance: it recommends using this tool over list_events for availability, and mentions that booking requires create_event which needs human approval. This explicit when-to-use and when-not-to-use guidance is exemplary.

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 readOnlyHint, idempotentHint, and destructiveHint. The description adds value by explicitly stating 'Read-only', defining the return format, and disclosing the error/empty behavior for IMAP-only accounts. This goes beyond the structured metadata and covers auth and edge-case 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?

The description is three sentences, each earning its place: the core behavior, the constraint/error condition, and the alternative routing. It is front-loaded with the essential purpose and keeps the alternative note at the end.

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

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

Given the output schema exists (covering return fields), the description provides all necessary calling context: the exact date window, the account requirement, the read-only nature, and the recommended alternative. Nothing an agent needs 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% and both parameters are documented, so the baseline is 3. The description adds interpretive meaning by defining the date-range boundaries ('[today - days_back, today + days_ahead]'), which clarifies how the parameters combine beyond their individual descriptions.

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

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

The description states a specific verb ('list') and resource ('calendar events'), defines the exact date-range scope, and gives example fields. It also distinguishes itself from find_free_slots, making it unambiguous for an agent to select the correct tool.

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 states when to use this tool (for listing events) and when not to (prefer find_free_slots for proposing meeting times), and it mentions the prerequisite (Microsoft Graph calendar) and the fallback behavior for IMAP-only setups. This is clear, actionable guidance.

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

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

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

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

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

The description is tight and front-loaded: purpose, output shape, downstream usage, and read-only nature all fit in a few lines with no redundancy or filler.

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

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

For a simple list operation with output schema, full parameter coverage, and strong annotations, the description supplies exactly the operational details an agent needs: what is listed, how to reference folders later, and that the operation is read-only.

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

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

With 100% schema description coverage and a single optional account_id parameter, the schema already documents everything needed. The description does not add further parameter-level meaning, so the baseline 3 is appropriate.

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

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

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

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

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

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

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

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

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

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

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

The description is front-loaded with the core purpose, then adds scoping constraints, output format, and a pointer to the sibling tool. Every sentence adds value with no redundancy.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description is concise, front-loaded with the main purpose and output format, then adds critical caveats (no bodies, untrusted data, empty result behavior). Each sentence adds value and the structure is logical and easy to parse.

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

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

Given the output schema exists, the description does not need to detail return types but still lists the summary fields. It covers error behavior ([]), security (untrusted data), and alternative for bodies. It also provides folder guidance. For a list tool with annotations covering safety, this is fully complete.

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

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

Schema coverage is 100%, with each parameter (top, skip, folder, account_id) already described. The tool description repeats the folder options (inbox, sent, drafts, etc.) which are also in the schema, and does not add new semantics beyond the general purpose. Since the schema fully documents parameters, a baseline of 3 is appropriate.

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

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

Clearly states the verb (List), resource (messages in a mailbox folder), ordering (newest first), and the exact output shape (summaries with listed fields). It also differentiates from read_message by explicitly excluding bodies, and from list_unread by indicating folder-based listing. The purpose is unambiguous.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description clearly states a specific verb and resource: 'Unread messages of the inbox from the last `days` days, newest first.' It also distinguishes itself from siblings by mentioning the summary shape matches list_messages and directing body retrieval to read_message. This makes it immediately clear what the tool does and how it differs from related tools.

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

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

The description gives clear context for when to use the tool (unread messages in a time window) and explicitly points to read_message for bodies, implying this tool is for summaries. It does not explicitly mention alternatives like list_messages or search_mail, but the reference to list_messages' shape implies the distinction. This is sufficient guidance for most agents.

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

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

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

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

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

Two sentences, clearly structured, with every sentence earning its place. The most important facts (what it does, reversibility, side effects) are front-loaded.

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

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

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

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

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

Schema description coverage is 100%, so the schema already documents all four parameters well. The description adds a slight behavioral note about execution, but doesn't need to add parameter-level detail because the schema already covers it.

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

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

States a specific verb ('mark'), resource ('a message'), and the two possible states (read/unread). The description clearly distinguishes it from siblings like move_message, delete_message, and send_mail.

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

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

The description explains the operation is reversible and immediate, and mentions the audit log. It doesn't explicitly state when to use this vs reading a message, but the purpose is clear enough for an agent to infer context.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Annotations already indicate readOnlyHint=false, destructiveHint=false, openWorldHint=true, and idempotentHint=true. The description adds crucial context beyond those: it returns {success}, is reversible, executed immediately, audited, and notably explains that on IMAP the message gets a new UID making the old message_id invalid. This goes well beyond what annotations convey.

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

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

The description is concise: two sentences plus a note. The core purpose is front-loaded, followed by return value and behavioral traits, then the IMAP caveat and the delete alternative. It earns each sentence; only slight redundancy in the note about 'move it back' could be trimmed, but overall it is 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?

For a tool with four parameters (two required) and no output schema, the description provides all necessary context: what it does, return shape, side effects (audited, immediate), the IMAP UID caveat that affects message_id usage, and a pointer to delete_message. An agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description does not add substantial new meaning beyond the schema; it mentions the folder_id format and source_folder being IMAP-only, but those are already in the schema. Thus a baseline 3 is appropriate.

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

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

The description clearly states the action ('Move a message to another folder of the same account') with a specific verb and resource, and distinguishes it from the sibling delete_message by mentioning that deletion requires approval. This unambiguously differentiates the tool.

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

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

The description explicitly tells when to use this tool versus alternatives: it contrasts with delete_message, notes that the operation is immediate without approval, and implies reversibility ('move it back'). It also warns about the IMAP UID change, which guides usage for IMAP accounts. No ambiguity remains.

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

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

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

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

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

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

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

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

Given the simple read-only nature, optional parameters, and presence of an output schema, the description covers everything an agent needs: what it returns, when to use it, and the empty-string sentinel. No critical information appears missing.

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

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

Schema description coverage is 100%, so parameters are already documented. The description adds value by explaining that sender and subject are used to find 'similar' past contexts, giving the parameters meaningful filtering semantics beyond their raw schema definitions.

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

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

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

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

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

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

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

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

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

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

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

The description is four sentences, each carrying distinct value: purpose and output, process and side effects, security warning, and error handling. It is front-loaded with the core purpose and contains no redundant or filler text.

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

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

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

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds no extra parameter-level meaning beyond the schema; it does reiterate that filename must match read_message output and message_id comes from list_messages, but these are already in the schema descriptions. No additional semantics are provided.

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

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

The description states a specific verb ('Extract'), resource ('attachment'), and scope ('the TEXT'), and lists supported formats. It clearly distinguishes from sibling tools like read_message, which reads message content, by focusing on attachment text extraction.

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

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

The description implies when to use it: whenever an agent needs the text content of an attachment. It doesn't name alternatives because no sibling tool serves the same purpose, and it provides guidance on error and unsupported-format behavior, which helps the agent decide if the tool is appropriate.

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

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

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

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

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

The description is three sentences, front-loaded with the primary purpose, then the return format, then access restrictions. Every sentence contributes meaningful information with no redundancy or filler. It is concise and well-structured.

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

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

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

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

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

Schema description coverage is 100%, so both parameters (name and account_id) are already thoroughly documented in the input schema. The tool description adds no extra parameter information; it only mentions access limitations in general. With complete schema coverage, the baseline of 3 is appropriate.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description discloses far more than the annotations: irreversible sending, human approval requirement, preview contents, request expiration, deduplication, rate limiting, audit logging, and fixed addressing behavior. This fully complements the destructiveHint=true and readOnlyHint=false annotations with no contradictions.

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

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

The description is long but every sentence conveys an operational requirement or constraint. The most critical information (two-phase, human-approved) appears first, and the use of explicit labels like 'FIXED ADDRESSING' and 'Irreversible once sent' front-loads the highest-risk facts.

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, externally-approved operation with no output schema, the description covers all necessary context: exactly what the first call returns, what the second call requires, status values, rate limits, dedup behavior, audit trail, preview contents, and result shape. No important behavioral gap remains.

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?

Although schema coverage is already 100%, the description adds substantial meaning beyond the schema: request_id's two-phase lifecycle, body being only the content with subject/threading auto-set, message_id being account-specific and format-dependent, and cc being additive without changing the fixed recipient. This materially helps an agent choose correct argument values.

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 ('Reply to an existing message in its thread'), which clearly distinguishes the tool from send_mail. It further differentiates the tool by stating the reply targets the original From address and by describing the two-phase approval 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 explicitly defines the two-phase calling protocol: omit request_id on the first call, then call again with the approved request_id. It also explains when the tool does not execute, what happens if approval is missing, and refers to send_mail's attachment rule, giving the agent a clear decision path.

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 readOnly, idempotent, and non-destructive hints. The description adds meaningful behavioral context: results are untrusted data and local_index may be empty if the index isn't built. These go beyond annotations and aid the agent.

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

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

The description is dense but efficient, front-loading the core purpose and then detailing the response structure and edge case. All sentences carry information, though the first sentence is long. It's appropriately sized for the complexity.

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 explains the response structure (provider and local_index) and the empty-index scenario. It also flags untrusted data. It doesn't explicitly mention that 'top' limits results per source, but the schema covers that. Reasonably complete for a search tool.

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

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

The input schema has 100% coverage with descriptions for all three parameters. The tool description does not add parameter-specific guidance beyond what the schema already 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 (Search) and resource (mailbox), and describes the dual result structure (provider + local_index). It doesn't explicitly name a sibling it is not, but the purpose is clear and distinct from listing tools like list_messages. Not a 5 because it doesn't reference any alternative.

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 two search sources and notes when local_index is empty, but it never states when to use this tool versus siblings like list_messages or list_unread. The usage is implied rather than explicitly guided.

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?

Annotations already declare destructiveHint: true and readOnlyHint: false, and the description reinforces and extends this by stating 'Irreversible once sent.' It discloses the two-phase approval behavior, that the first call executes nothing, that requests expire and are deduplicated, that rate limiting applies, and that all phases are audited. It also explains provider-specific behavior (SMTP per-recipient vs Graph HTTP 202). This goes well beyond the annotations and provides deep behavioral context.

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 lengthy but every sentence conveys critical operational information. It opens with the core purpose and the two-phase approval, then layers details on expiration, dedup, rate limits, audit, preview, and return format. It is well-structured and front-loaded, though a bit dense; no sentence is wasted.

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

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

Given the tool's complexity (two-phase, human approval, irreversibility, provider variance), the description covers all necessary aspects: the flow, constraints, return statuses (approval_required, awaiting_approval, rate_limited), the preview contents, and the provider-specific response differences. There is no output schema, so the description compensates by explaining the return structure. An agent can correctly invoke and interpret the tool based on this text alone.

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 already covers 100% of parameters with detailed descriptions (e.g., request_id explains the two-phase flow, to explains may_expand, attachments restrict to registered files). The tool description adds context on how parameters interact (e.g., 'the approved arguments, not the ones passed the second time') and the preview contents. This adds meaningful value beyond the schema, though the schema already carries much of the load.

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 'Send a new email from the user's account' — a specific verb and resource. It distinguishes the tool from siblings by detailing the two-phase approval flow, which is unique to this tool among the listed siblings. It also clarifies that it is for new emails, separating it from reply_mail.

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

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

The description provides explicit guidance on when to call each phase (first call without request_id, second with it), and states that the agent cannot approve, so it should not expect completion without human approval. It also mentions dedup, rate limits, and expiration. However, it does not explicitly compare to alternatives like reply_mail or delete_message, so it stops short of full when-not-to-use guidance.

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