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

With no annotations provided, the description carries the full burden. It discloses several key behaviors: appending after the last column, optional default-value filling, refusal on duplicate names, and file backup before writing. These details give the agent a clear understanding of side effects and failure conditions.

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 long, front-loaded with the primary action, and every sentence contributes unique information. There is no redundancy or filler, making it highly 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?

This is a simple tool with only two parameters and no output schema. The description covers purpose, behavioral rules, failure modes, and the relationship to sibling tools, making it fully self-contained and sufficient for correct use.

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 a baseline of 3 is appropriate. However, the description adds meaning beyond schema by explaining that default_value is written into every existing job row and that name uniqueness is enforced. This enriches the parameter semantics.

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

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

The description states 'Add a new custom column to the spreadsheet, appended after the last column' with a specific verb and resource. It distinguishes from sibling job tools by explicitly noting that job tools only handle standard columns and custom columns are managed with these column 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 about when to use this tool: for managing custom columns, as opposed to the built-in job tools which read/write standard columns. It also notes duplicate-name refusal, implicitly suggesting that a different tool (like modify_column) would be needed for existing columns, though it doesn't name the alternative explicitly.

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

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

With no annotations, the description carries the burden. It discloses several behavioral traits: required fields, default values for status and date_applied, custom column handling via extra_fields, and backup creation before writing. It does not mention return values or error behavior, but the provided context is strong.

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 concise sentences, front-loaded with the primary action and then covering defaults, custom fields, and backup behavior. Every sentence adds useful information 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?

For a mutation tool with 11 parameters, no output schema, and nested objects, the description covers the critical aspects: required fields, defaults, custom column usage, and backup safety. It does not describe return values or error handling, but the essential operational details are 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 82%, so the schema already documents most parameters. The description reinforces defaults and explains extra_fields, but does not add significant new meaning beyond what the schema descriptions already provide. 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 ('Append a new job application row') and identifies the resource ('job application row'). It also specifies required fields (Company and Position), which helps distinguish it from update/delete/list operations.

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 this is for creating new job entries and mentions extra_fields for custom columns, but it does not explicitly state when to use this tool versus alternatives like update_job or delete_job. No exclusions or alternative references are given, leaving usage context implied rather than explicit.

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

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

With no annotations provided, the description carries the full burden. It discloses key behavioral traits: creating the file and section as needed, avoiding duplicate headings, enforcing a markdown style, and backing up the file before writing. This is rich and useful for an 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 three sentences, front-loaded with the primary action. Every sentence adds critical information (behavior, style, safety) without 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?

Given the tool's simplicity (2 parameters, no output schema), the description covers all necessary aspects: what it does, file creation behavior, formatting conventions, and backup safety. It is complete for an agent to invoke 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% for both parameters, so the baseline is 3. The description adds value by specifying the expected markdown style ('**Q: ...**' / 'A: ...' pairs) and clarifying that content is appended under the company section, going beyond the schema 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 clearly states the action ('Append markdown'), the target resource ('the interview-prep file'), and the context ('under a company's section'). It distinguishes itself from sibling tools like read_interview_prep by specifying append behavior and file organization.

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 clear context on when the tool creates the file or section versus appending to existing ones, which effectively guides usage. However, it does not explicitly mention alternatives or exclusion criteria, so it falls short of a 5.

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

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

With no annotations at all, the description carries the full burden of behavioral disclosure. It explicitly states the operation is permanent, describes the column-shifting side effect, lists refusal conditions (built-in and missing columns), and mentions the backup to .bak. This is exemplary transparency for a destructive operation.

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

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

The description is three sentences, each providing distinct value: purpose and behavior, failure conditions, and safety backup. No unnecessary words or repetition, and it is 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 simple single-parameter tool with no output schema, the description comprehensively covers what the tool does, how it affects the data, when it refuses, and what safety measure is taken. It is complete without being verbose.

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 for the single 'name' parameter, which is already described as 'Header text of the column to delete.' The description adds no additional parameter-level meaning beyond 'custom column' in the purpose, 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 'permanently remove a custom column' and describes the specific behavior of shifting columns to the right left by one, using the Excel analogy for immediate understanding. This distinguishes it from sibling tools like add_column or modify_column.

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 through the Excel analogy and notes it refuses on built-in columns, but it does not explicitly state when to use this tool versus alternatives like modify_column or add_column. No direct when-not-to-use guidance beyond built-in columns is provided.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It transparently explains that a backup is made first, the file is then removed, and invalid inputs are refused. It does not mention return values on success/failure or backup failure handling, but the key behavioral traits are covered.

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

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

Two sentences front-load the primary action and then add critical safety/backup details. Every sentence earns its place with no repetition of schema 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 one-parameter deletion tool with no output schema and no annotations, the description adequately covers purpose, safety, and backup. It omits details about return values or error responses, but these are less critical for such a simple operation.

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

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

The schema has 100% coverage for the single parameter, and the schema description already states the filename is in the Resumes folder. The tool description reinforces that paths outside the folder are refused, which adds a little context, but overall it does not significantly go 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?

The description clearly states 'Delete a saved document from the Resumes folder' with a specific verb and resource. It distinguishes itself from sibling document tools (list, read, save, print) by focusing on deletion and exclusively referencing the Resumes folder.

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 context is clear: the tool is for deleting saved documents in the Resumes folder, and it adds a safety note about refusing paths outside that folder. However, it does not explicitly mention when to prefer this over other delete tools (e.g., delete_job, delete_column), though the resource type makes it obvious.

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

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

With no annotations provided, the description fully discloses important behaviors: permanent action, row shift, refusal on missing/ambiguous matches, automatic backup to .bak, and return of the deleted row for recovery. This is excellent for a mutation tool.

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

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

The description is a single, tightly packed sentence that front-loads the main action and then adds each behavioral detail without redundancy. Every clause earns its place.

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

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

For a deletion tool with no output schema and no annotations, the description covers all essential context: what is deleted, how matching works, failure behavior, backup, and return value. An agent has enough to use it correctly and handle outcomes.

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 both parameters already described (case-insensitive, position disambiguates). The description reinforces the combined match but adds no new parameter details beyond what the schema already provides, 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?

The description clearly states the action: permanently remove a job application row, with specific matching criteria (company + position) and a concrete effect (shifting rows below up). It also distinguishes from sibling tools like delete_column or delete_document by explicitly targeting job application rows.

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 is obvious when to use this tool (to delete a job application row) and it adds safety context by refusing on missing or ambiguous matches. It doesn't explicitly contrast with alternatives, but no sibling tool offers job deletion, so the usage context is 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?

With no annotations provided, the description carries full disclosure burden. It adds valuable behavioral details: Date Found defaults to today, Status defaults to 'Open', and it 'Backs the file up first'. These go beyond the schema and reveal side effects and defaulting behavior, though it does not mention return values or error 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 two sentences with no fluff. It front-loads the core action and then supplies key details in a compact, scannable manner. Every sentence earns its place.

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

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

For a simple append operation with no output schema, the description covers purpose, required vs optional inputs, defaults, and a safety behavior (backup). It does not mention return values, but that is easily inferable for an append tool and is not a critical gap. The description is complete enough for an agent to invoke 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?

Although schema coverage is 100%, the description adds meaning by providing concrete field examples (Salary, Job Link, 'Match Assessment') and explaining default behavior for Date Found and Status, which are not explicit schema properties. This enriches understanding beyond the structured 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 states 'Append a new lead to the discovery sheet' with a specific verb and resource, clearly distinguishing it from sibling update/delete/list operations. The title 'Add discovery lead' reinforces this purpose 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?

The phrase 'Append a new lead' implies usage for adding new entries, but the description does not explicitly state when to use this tool versus alternatives like discovery_update or discovery_delete. There are no exclusions or alternative tool mentions, making the guidance only implied.

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

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

With no annotations, the description carries the full burden. It explicitly states the destructive nature ('Permanently remove'), side effects ('shifting rows below it up'), safety measures ('backs up first'), refusal conditions ('missing/ambiguous matches'), and return value ('returns the deleted row'). This is thorough behavioral disclosure.

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

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

The description is two sentences, front-loaded with the action and resource, and every clause adds value. There is no redundancy or 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 2-parameter delete tool with no annotations and no output schema, the description is highly complete. It explains the matching key, side effects, safety behavior, failure conditions, and return value, which is sufficient for an AI agent to use 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% and both parameters are described, but the description adds meaning by establishing that company and position are used together as a composite match key. It also adds behavior for ambiguous/missing matches, going beyond the schema's simple field 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 uses a specific verb ('Permanently remove') with a clear resource ('discovery lead') and matching criteria ('company + position'). It clearly distinguishes from sibling tools like discovery_add, discovery_update, and delete_job.

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

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

The description clearly indicates when to use this tool—to permanently delete a discovery lead—and provides context about its behavior (e.g., refuses missing/ambiguous matches, backs up first). It does not explicitly mention alternatives, but the scope 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?

With no annotations, the description carries the burden of disclosing behavior. It explicitly notes case-insensitive matching for company and status, and that query is a substring across all columns. This adds meaningful behavioral context beyond simply saying 'list'. It does not mention return format or that it is read-only, but the verb 'List' and source file imply a safe read operation.

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

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

Two sentences, front-loaded with the action and resource, then filters. Everything is relevant and no redundancy. It strikes an ideal balance between completeness and brevity.

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 tool with three optional filters and no output schema, the description covers the source, filter behavior, and purpose. It omits return shape/pagination, but for a list operation on a spreadsheet this is minor and the description 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?

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying that all filters are optional, that company and query are substring matches (case-insensitive), and that status is an exact match. This supplements the schema's per-property descriptions with matching semantics.

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

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

The description clearly states the verb 'List' and the specific resource 'job leads from the discovery sheet (Job_Search_Discovery.xlsx)', which differentiates it from sibling tools like list_jobs that operate on other data. It also names the optional filters, making the tool's scope 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 clearly indicates the tool is for listing discovery leads from a specific file, implying use when discovery sheet data is needed rather than tracker jobs. It does not explicitly name alternatives or exclusions, but the resource specificity gives clear context for when to use this tool.

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

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

With no annotations, the description carries the full burden and discloses important behaviors: refuses missing/ambiguous matches and backs up first. It also explains the empty-string-clears-value behavior. This is solid but does not cover return values or permissions, which would push it higher.

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, front-loaded with the primary action, and every phrase adds useful information. No waste or redundancy.

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

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

With 5 parameters and no output schema, the description covers all key aspects: matching, renaming, field updates, clearing, refusal behavior, and backup. It is adequate for an update tool, though it does not describe the success response format.

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 baseline is 3, but the description adds meaning by explicitly stating that company and position are the matching keys and that new_company/new_position rename. It clarifies the fields mechanism and clearing semantics, adding value 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?

The description explicitly states the action ('Edit') and resource ('discovery lead'), and clarifies the matching criteria (company + position). It distinguishes from sibling tools like discovery_add and discovery_delete by focusing on updating an existing lead.

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

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

The description clearly indicates this tool edits discovery leads matched by company and position, providing context on when to use it. It does not explicitly mention alternatives like discovery_add or discovery_delete, but the 'Edit' phrasing and resource make the intended use obvious.

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

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

With no annotations, the description carries the full behavioral burden. It explicitly discloses the key behavior: 'Returns draft text only — it does not send anything', indicating no side effects. It also mentions what the draft references, but omits error conditions or prerequisites.

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

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

Two sentences, front-loaded with the main action, and both sentences earn their place. The second sentence adds a crucial behavioral boundary without 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 simple drafting tool with two parameters and no output schema, the description covers purpose, behavioral scope, and return value ('Returns draft text only'). It does not mention potential errors or prerequisites, but the overall context is sufficiently 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%, so baseline is 3. The description adds slight context by mentioning 'role' and 'resume version used', which map to the position parameter and application context, but it doesn't explain parameters 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?

The description uses a specific verb 'draft' and resource 'follow-up email for a given application', clearly stating what the tool does. It also distinguishes itself from sending tools by noting 'Returns draft text only — it does not send anything.'

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: use it to draft a follow-up for an application, referencing time since applying, role, and resume version. It explicitly states it does not send, providing an exclusion, though it doesn't name alternative tools like send_gmail_email or draft_gmail_reply.

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

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

With no annotations provided, the description carries the full burden and does well by disclosing that the draft is visible in the Drafts folder, not actually sent, and requires Gmail authorization (referencing GMAIL_SETUP.md). It also explains how thread_id affects recipient/subject inference, adding useful behavioral context. A minor gap is that it doesn't describe what happens after the draft is created (e.g., return value), but this isn't critical.

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

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

Three sentences, front-loaded with the most important fact (not sent), and each sentence adds distinct value. No repetition of schema content; it's tightly written 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?

For a tool with 5 parameters and no output schema, the description is adequately complete: it explains the two invocation modes, parameter relationships, and a prerequisite. The only omission is a explicit description of the return/confirmation behavior, but given the tool's simplicity and schema coverage, this is acceptable.

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 meaningful semantics: it explains that thread_id can come from search_gmail_for_job or scan_job_updates, clarifies that subject is ignored when thread_id is used, and explicitly states that 'to' is required when thread_id is omitted. Examples and precedence rules go beyond the schema 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 specifies a clear action ('Create a real Gmail draft') and a distinct behavioral outcome ('does NOT send it'), distinguishing it from the sibling send_gmail_email. It also names the concrete resource (Drafts folder) and two usage modes (reply vs new message).

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 solid usage context: when to reply within a thread (pass thread_id with examples of source tools) and when to start a new message (pass to + subject). It also notes the authorization prerequisite. However, it doesn't explicitly name send_gmail_email as the alternative when sending is actually intended, though the 'does NOT send' phrasing implies it.

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

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

No annotations are provided, so the description carries full responsibility for behavioral disclosure. It states that output is saved to a specific folder, no base64 is used, the rendering uses python-docx + LibreOffice, factual constraints (do not invent employers/dates/degrees), and the return payload (path, size, nextStep). This is exceptionally transparent.

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

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

The description is a succinct four-sentence paragraph. The first sentence front-loads the core purpose; subsequent sentences add necessary constraints and workflow details. No filler or redundancy—every sentence earns its place.

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

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

For a tool with 10 parameters and no output schema, the description covers purpose, input responsibilities, rendering process, file location, constraints, return values, and a suggested follow-up. It is fully complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% with meaningful descriptions for each parameter. The description adds extra context for key parameters (summary and key_qualifications) by explicitly labeling them as the per-posting tailoring. This enriches the schema without redundancy.

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?

Description states a specific verb+resource: 'Generate a tailored resume PDF (or docx) on the host and save it into the Resumes folder.' This clearly distinguishes it from all sibling tools (job tracking, document management, etc.) which serve different purposes.

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 that stable facts come from resume_master.json and that the user supplies only per-posting tailoring (summary, key_qualifications). It also suggests offering the nextStep to keep tailoring, saving, and tracking together. However, it does not explicitly contrast with sibling tools or state when not to use it.

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

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

With no annotations, the description carries the full burden. It discloses that closed rows (Declined/Withdrawn/Closed) are skipped, that results are sorted by most-overdue first, and that the daysUntil field is negative when overdue. These are meaningful behavioral details not available elsewhere.

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 with no filler. It front-loads the core purpose, then provides filtering, sorting, and field semantics efficiently.

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 1-parameter tool with no output schema, the description sufficiently covers purpose, filtering, sorting, and a key output field (daysUntil). It could enumerate all return fields, but the essential behavior is clear.

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% for the single 'days' parameter; the schema already explains it as a look-ahead window with default 0. The description only restates this concept ('within the next `days` days') without adding new semantic detail about the parameter.

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 'List' with a clear resource 'applications whose Next Follow-Up date is due' and defines the date condition. It distinguishes itself from siblings like list_jobs and get_stale_jobs by focusing on follow-up due dates.

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 clearly states when to use: to list applications due for follow-up on or before today or within a given days window, and that closed rows are skipped. However, it does not explicitly mention alternatives or when not to use this tool.

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

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

No annotations are provided, so the description carries the burden of behavioral disclosure. It explains the matching rule (position needed if company has multiple rows), which is a useful behavioral nuance. However, it does not disclose what happens when no match is found or when the company has multiple rows and position is omitted, leaving some ambiguity.

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 a single, front-loaded sentence that states the verb, resource, and matching criteria without any fluff. Every word contributes to understanding what the tool does.

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 getter with two parameters and no output schema, the description covers the essential matching logic and the condition on position. It does not specify the return format or error behavior, but given the low complexity and the schema descriptions, the description is sufficiently complete for most use cases.

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% (both parameters have descriptions in the schema), so the baseline is 3. The description reiterates the relationship between company and position (position needed if multiple rows), which adds slight context beyond the schema but does not provide significant new semantics.

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

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

The description uses the specific verb 'Return' and identifies the resource ('full details for a single application') plus the matching key (company, optionally position). This clearly distinguishes it from sibling tools like list_jobs (lists many) and search_jobs (searches broadly).

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

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

The description clearly implies when to use this tool: when you need full details for one specific application identified by company. It does not explicitly name alternatives or exclusion criteria, but the context is clear and the sibling tool names reinforce the distinction. No exclusions are necessary.

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

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

With no annotations, the description carries the burden of disclosing behavior. It states the operation is a read, scopes access to one file, and describes the nature of the data ('stable resume facts'). It does not explain error behavior or return characteristics for invalid paths, but for a simple read tool the provided context 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, front-loads the verb and resource, and every element adds value. It is concise without being under-specified, including examples and a usage hint without unnecessary 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?

This is a simple single-parameter read tool. The description includes the file name, path format with examples, scope limitation, and guidance for an alternative tool, making it sufficiently complete without an output schema or complex annotations.

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 covers the path parameter with one example. The description adds multiple examples ('skills', 'projects[0].description') and clarifies the dot/bracket path syntax, providing additional meaning beyond the schema description.

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 reads one field from resume_master.json using a dot/bracket path. It uses a specific verb ('Read') and resource ('resume_master.json'), and the examples distinguish it from sibling tools like update_resume_master_field and list_resume_master_structure.

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 advises using list_resume_master_structure first if unsure of the path, providing an alternative for a specific scenario. It also notes the tool is scoped to one file, but it does not explicitly contrast with the update sibling or clarify when a list/read of the entire file would be more 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?

No annotations are provided, so the description carries the burden of behavioral disclosure. It does specify the filtering logic (statuses and date threshold) and states the default of 14 days computed against today. However, it does not explicitly state that this is a read-only operation or describe side effects, permissions, or return format. The 'List' verb implies safety, but the absence of annotations makes this a moderate, not strong, disclosure.

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

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

The description is a single, compact sentence that front-loads the core functionality and includes essential details (statuses, threshold, default, baseline date). No wasted words.

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

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

Given the simple single-parameter schema and lack of output schema, the description adequately explains what the tool does and the input behavior. It does not detail return shape or ordering, but these are not critical for this simple list operation. It is complete enough for an agent to understand the tool's role.

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 only parameter, 'days', has a clear schema description covering its meaning and default. The tool description adds no new parameter semantics beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description clearly states the tool lists applications filtered by specific statuses ('Awaiting Response' or 'Applied') and by a date threshold. This is a specific verb+resource+scope description that distinguishes it from sibling tools like list_jobs or get_job.

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 clear context on when to use the tool: when needing to surface applications stuck in certain statuses older than a configurable number of days. It does not explicitly name alternatives or exclusions, but the criteria are well-defined enough for an agent to select 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?

With no annotations provided, the description must convey behavioral traits. It does so by specifying the sort order ('Newest first'), the filtering behavior ('case-insensitive substring'), and the output fields. It clearly indicates a read-only listing operation. Minor gaps remain about folder scope or error handling, but it is well above the baseline.

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, front-loads the core action and resource, and every phrase adds value: the folder location, the output fields, the filter behavior, and the sort order. No unnecessary 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?

For a simple list tool with one optional parameter and no output schema, the description is quite complete: it states the returned fields and ordering. It does not mention potential edge cases (e.g., empty folder, subfolder recursion), but these are not critical for core usage. The low complexity means this level of detail is sufficient.

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

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

The schema already fully documents the single parameter 'filter' with a matching description. The tool description repeats the case-insensitive substring semantics but adds no additional meaning beyond the schema, so the baseline score 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 clearly states the action ('List'), the resource (saved resumes/cover letters in the Resumes folder), and the returned attributes (name, size, modified date). This distinctly differentiates it from sibling document tools like read_document, save_document, or delete_document.

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: use this tool to see available resumes/cover letters with an optional substring filter. However, it does not explicitly state when to prefer this over alternatives like read_document or save_document, nor does it mention any exclusions.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It discloses specific matching semantics: case-insensitive exact match for status, case-insensitive substring for company, and inclusive date range. This is valuable behavioral detail beyond a simple 'list'. It does not mention return format, ordering, or pagination, but the read-only nature of 'list' is clear.

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 the main purpose front-loaded, and the filter details follow logically. Every clause adds value, and there is no redundant or vague language. 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?

Given the tool's simplicity (4 optional parameters, no required params, no output schema), the description covers the essential behaviors and filter semantics thoroughly. It does not mention ordering or pagination, but these are often implied for a list operation. The lack of explicit return-format information is a minor gap, but overall it is close to complete for this tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra semantics beyond the schema: it explains that status is case-insensitive exact match, company is case-insensitive substring, and the date range is inclusive. This clarifies how the parameters behave, raising the score to 4.

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' and the resource 'tracked job applications', with optional filters. It explicitly distinguishes this from getting a single job (get_job) and from search_jobs, which likely has different search behavior. The scope 'all tracked job applications' is precise and 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 clearly implies when to use this tool: when you need to list job applications with optional filters. It provides a strong context of use but does not explicitly mention alternatives or when not to use it. However, the purpose is clear enough that an agent can infer appropriate usage without explicit exclusions.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It transparently explains that the tool returns only structural metadata (keys, array lengths, scalar types) and not full field values, and that 'path' scopes the listing. This sets accurate expectations about output scope, though it doesn't explicitly mention that the operation is read-only or describe error cases.

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 exactly two sentences, front-loaded with the primary purpose and followed by the parameter note. Every word earns its place; there is 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 introspection tool with one optional parameter and no output schema, the description adequately covers purpose, parameter behavior, and relationships to sibling tools. It doesn't specify the exact output format, but that is not critical given the tool's nature and the explicit 'shape' framing.

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% for the single optional 'path' parameter, so the description doesn't need to add much. The description repeats the schema's meaning ('scopes the listing to a sub-section') without adding new syntax or format details. This matches the baseline of 3 when the schema handles 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 shows the structural shape of resume_master.json (keys, array lengths, scalar types) and explicitly distinguishes it from sibling field-access tools by explaining its role in path selection. The verb 'Show' is specific and the resource is named unmistakably.

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 says the tool exists 'to help pick a path for get_resume_master_field / update_resume_master_field', giving direct context for when to use it. It also notes the optional 'path' scoping, which further clarifies usage. While it doesn't list exclusions, the guidance is clear and actionable.

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

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

With no annotations provided, the description carries the full burden. It discloses that fill_value writes to every existing row, empty string clears, built-in/missing columns are refused, and a file backup is made first. This is strong behavioral detail for a mutating tool, though it does not mention return values or error formats.

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, front-loaded, and consists of four short sentences, each providing essential operational, constraint, or safety information. There is no filler or redundant repetition of the title.

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 three-parameter mutation tool with no annotations or output schema, the description covers the action, parameter effects, preconditions, refusal cases, and backup behavior. It is sufficiently complete for an agent to select and invoke the tool correctly, even though it does not describe the success response shape.

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 describes all three parameters (100% coverage), so the baseline is 3. The description adds value by specifying the cross-parameter constraint that at least one of new_name or fill_value must be provided, which is not expressed in the schema. Most other parameter meaning is already present in the schema.

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

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

The description opens with a specific verb and resource ('Modify a custom column') and clearly breaks the action into rename and fill operations. It also distinguishes itself from sibling tools like add_column and delete_column by specifying it operates on existing custom columns.

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 preconditions: at least one of new_name or fill_value is required, and it refuses on built-in/missing columns. This provides clear context for when the tool should or should not be used, though it does not explicitly name sibling alternatives.

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

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

With no annotations, the description carries the full behavioral disclosure burden. It covers conversion of .docx to PDF, caching next to the docx, default printer usage, and the important distinction that confirmation only means the job was sent, not physically printed. This is rich, specific behavioral information.

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

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

Three sentences, each earning its place. Front-loaded with the core action, then key details on file handling and printing behavior. No redundant or vague wording.

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 simplicity (2 parameters, no output schema), the description covers essential aspects: file names, format conversion, printer selection, and confirmation semantics. It lacks details about error handling or return format, but these are less critical for a straightforward print action.

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 has 100% coverage, so parameters are already documented. The description goes beyond by explaining the Resumes folder shortcut, full path support, PDF vs .docx handling, and the default behavior of the printer_name parameter. This adds meaningful practical context.

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 specific action: 'Silently print a saved document to a printer.' It identifies the resource (saved document) and distinguishes from sibling tools like save_document, read_document, and delete_document by focusing on the print operation.

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

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

The description gives clear context for usage: it mentions saved documents, file names in the Resumes folder or full paths, and default printer behavior. While it doesn't explicitly state when not to use it or name alternatives, the context is unambiguous enough for an agent to choose this tool for printing tasks.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals key side effects: copying fields, overridable defaults, notes derived from salary/match unless overridden, optional deletion of the lead, and backup of both files. It does not mention error handling or return format, but the major behaviors are transparent.

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

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

The description is concise and well-structured: four short sentences, each adding a distinct piece of information (core purpose, notes default, optional deletion, backup). No filler or redundancy, and the most important action is 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 cross-sheet promotion tool with 7 parameters and no output schema, the description explains the main workflow, defaults, optional behavior, and backup. It omits return value and error handling, but the schema covers parameter details, making the description reasonably complete for the agent to invoke the tool correctly.

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

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

Schema coverage is 100%, so parameters are already documented. The description adds value by clarifying default behaviors for status, date_applied, notes, and remove_from_discovery, and explains how notes derive from salary/match if not supplied. This supplements the schema with practical semantics.

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

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

The description clearly states the tool's purpose: 'Turn a discovery lead into a tracked application' and enumerates specific actions (copies Company, Position, Job Link, Location; sets Status and Date Applied). This distinguishes it from sibling tools like add_job or discovery_add, which operate on single sheets.

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 conveys a clear use case (promoting a discovery lead to a tracker) and mentions optional removal from the discovery sheet, which implies workflow context. However, it does not explicitly say when to use this tool instead of alternatives like add_job or discovery_update, so it lacks explicit exclusions.

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

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

With no annotations provided, the description carries the full behavioral burden. It explicitly states 'Read-only' and specifies the file formats (.pdf/.docx) and location (Resumes folder). It does not detail error handling or return format, but for a simple read tool this is adequate and non-misleading.

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, front-loaded with the main action and purpose, followed by an example and a clear instruction. Every sentence contributes value without 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?

The tool is simple (1 parameter, no output schema, no nested objects). The description includes purpose, scope, file types, location, and behavioral safety ('Read-only'). It is complete enough for an agent to select and invoke correctly, though it omits potential error cases, which are not critical for a read operation.

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

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

The input schema already covers the filename parameter fully (100% coverage) with an example. The description adds extra meaning by emphasizing 'Give a file name in the Resumes folder,' reinforcing the location constraint and the expected input format.

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 specifies a unique verb and resource: "Extract and return the plain text of a saved resume / cover letter (.pdf or .docx) from the Resumes folder." This distinguishes it from siblings like read_text_file (generic) and list_documents, and includes an example use case.

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 (to read and analyze a resume/cover letter in conversation) and gives a concrete example. It does not explicitly exclude alternatives, but the context is clear and the instruction 'Give a file name in the Resumes folder' provides direct usage 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?

With no annotations provided, the description carries the disclosure burden. It discloses read-only nature ('Read-only'), explains behavior with thread_id ('reads the most recent message in that thread'), and clarifies the precedence when both parameters are given. While it doesn't discuss authentication or side effects, the read-only declaration and behavioral details are valuable for this simple tool.

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

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

Two sentences, front-loaded with the primary purpose, then providing usage context and parameter guidance. Every sentence provides functional value; no filler or redundant 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?

This is a simple 2-parameter read tool with no output schema. The description covers what it does, when to use it, how parameters interact, and its read-only nature. For the given complexity, it is complete and leaves no obvious gaps for an agent to correctly select and invoke the tool.

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

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

Schema coverage is 100%, so the parameters are already documented. The description adds meaningful relationship semantics: it explains that message_id comes from a search/scan result, that thread_id reads the most recent message, and that thread_id is ignored if message_id is given. This goes beyond the schema's standalone 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 opens with a specific verb+resource: 'Read the full body of ONE specific Gmail message.' It clearly distinguishes from sibling tools by stating that search_gmail_for_job and scan_job_updates only return snippets, while this tool provides the full content.

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: 'use this when you need the actual content (e.g. an interview link or instructions).' It also names the alternatives (search_gmail_for_job, scan_job_updates) and explains their limitation, providing clear context for selecting this tool. Additionally, it provides parameter usage guidance (message_id vs thread_id).

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

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

With no annotations provided, the description carries the transparency burden. It discloses key behaviors: returns text, handles missing file or missing company section with a friendly message rather than an error. This is adequate for a simple read operation.

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

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

Two sentences, front-loaded with the primary action, and every phrase adds value (file name, return format, optional filter, error handling). No wasted words.

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

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

For a tool with one optional parameter and no output schema, the description is complete. It covers the file source, behavior with and without the filter, and error/friendly-message handling. No additional context is needed.

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 a clear property description. The main description repeats the optional company filter but adds no new meaning 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?

The description clearly states the tool reads a specific file (Interview_Prep_QA.md) and returns it as text, with an optional company filter. This specific verb+resource+scope distinguishes it from generic read_document or read_text_file 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 for when to use: to retrieve interview prep content, optionally filtered by company. No explicit exclusions or alternatives are named, but the specificity of the file and behavior makes the usage 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?

With no annotations, the description carries the full burden. It discloses read-only behavior, strict scoping to the Job Tracking tree, and refusal of escaping paths. This is strong transparency, though it doesn't mention error handling or encoding, which are minor for a read tool.

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

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

The description is three sentences, front-loaded with the primary purpose, and each sentence adds value: scope, usage examples, and a pointer to an alternative. 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?

For a simple single-parameter read tool, the description covers purpose, scope, safety, and alternatives. It lacks mention of return format or error behavior, but the operation is self-explanatory. The absence of an output schema raises the bar slightly, yet the description remains adequate.

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 repeats the schema's parameter meaning but adds example values and explicit resolution under the Job Tracking root. This is useful but not a significant addition over structured schema.

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

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

The description clearly states the tool reads plain-text files within the Job Tracking folder tree, listing specific file extensions and example files. It explicitly distinguishes itself from read_document for PDFs/docx, making the purpose 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?

It provides concrete guidance on when to use this tool (for text files in Job Tracking) and explicitly names an alternative (read_document for PDFs/docx in Resumes). It also clarifies input format (filename or relative path) and scoping constraints.

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

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

No annotations exist, but the description compensates fully. It discloses folder creation, copy behavior (instant, cannot corrupt), base64 inefficiency, overwrite refusal with backup, and the return value (path and size). This is comprehensive behavioral disclosure.

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

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

The description is concise yet well-structured: purpose in the first sentence, then PREFERRED/FALLBACK formatting, then overwrite behavior and return value. Every sentence contributes no waste.

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 file-saving tool with 4 well-documented params and no output schema, the description fully covers behavior, parameter selection, safety considerations, and expected return. 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?

Schema coverage is 100%, but the description adds critical depth: why source_path is preferred (instant, no corruption), why content_base64 is limited (token-by-token generation, response limit), and the mutual exclusivity of the two parameters. This goes beyond the schema's 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 clearly states 'Save a generated document (docx or PDF) into the Resumes folder' with a specific verb, resource, and destination. This distinguishes it from sibling tools like list_documents, delete_document, and read_document.

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 provides PREFERRED (source_path) and FALLBACK (content_base64) usage paths, including size limits and performance tradeoffs. It also instructs 'Give exactly one of the two', giving clear guidance on parameter selection.

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

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

With no annotations, the description carries full burden and it excels: it explicitly says 'Read-only', states it 'never updates the tracker itself', and explains that it only produces a `suggestedCall`. This fully discloses the non-mutating, advisory nature of the tool.

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

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

The description is two sentences long, front-loaded with the main action, and every clause adds value. It efficiently communicates scope, method, side effects, and follow-up action without 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?

The tool has no output schema and the description gives a hint about return values via `suggestedCall`, which implies a suggestion object. It covers the core workflow and side effects well, though a detailed explanation of the return structure could improve completeness.

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?

All three parameters already have descriptions in the schema (100% coverage), so the description adds little new param-level meaning. It only re-emphasizes the 'one company' option, while days_back and max_per_company are not mentioned beyond 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?

The description clearly states the tool's function: cross-referencing open applications against Gmail and flagging keyword-based signals. It uses specific verbs like 'cross-reference' and 'searches', and distinguishes itself from siblings by emphasizing it only suggests status changes rather than updating the tracker.

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 clear context for when to use the tool: for each open job or optionally one company, scanning recent email for signals. It also gives post-usage guidance (review emails and call update_job_status if the suggestion looks right), though it doesn't explicitly compare to sibling tools like search_gmail_for_job.

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

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

No annotations provided, but the description discloses key behavioral traits: it is read-only ('Does not modify anything') and requires prior Gmail authorization. This is significant for safety. It does not detail pagination/rate limits, but given the scope, 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?

Two sentences, front-loaded with the verb and resource, no redundant information. Every clause adds value (scope, examples, safety, prerequisite).

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

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

For a 4-parameter search tool with no output schema, the description covers purpose, safety, and prerequisites but omits what the function returns (e.g., list of message metadata). The examples hint at matches, but not the return structure.

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 fully describes parameters like company, position, query, max_results. The description adds no extra parameter details beyond what is in 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?

The description clearly states it is a 'Read-only search of the authorized Gmail account for messages related to a company (and optionally position/keywords)' and lists example content (recruiter replies, interview invites, rejections). It distinguishes itself from siblings like read_gmail_message (which reads a specific message) and send_gmail_email (which writes) by explicitly noting read-only/no modification.

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 for when to use: searching for job-related emails in Gmail. States prerequisite 'Requires Gmail to be authorized first'. Does not explicitly name alternatives or exclusions, but clearly implies this is the search tool versus other Gmail action tools.

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

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

With no annotations provided, the description carries the burden of disclosure. It goes beyond a vague 'search' by specifying case-insensitivity, substring matching, and the exact columns considered, which is meaningful behavioral context. It omits return format or pagination, but core matching behavior is transparent.

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

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

The description is a single, front-loaded sentence with no filler. It precisely conveys the tool's behavior in minimal 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?

For a simple one-parameter search tool with no output schema, the description is adequately complete. It covers the search scope and matching behavior, though it could optionally mention what the return payload looks like. Overall, the tool is simple enough that this description suffices.

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 fully describes the single parameter with 100% coverage, so the baseline is 3. The description adds semantic value by explaining how the query is used (case-insensitive substring across Company, Position, Notes), which helps the agent understand the query's effect beyond the schema's generic 'Keyword or phrase to search for.'

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 performs a case-insensitive substring search across specific columns (Company, Position, Notes). This is a specific verb+resource+scope that distinguishes it from sibling tools like list_jobs or get_job.

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 use case: when you need to find jobs by a keyword across three textual fields. It does not explicitly mention alternatives or exclusions, but the context is clear enough for an agent to decide when to invoke this tool.

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

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

With no annotations provided, the description carries the full burden and delivers richly: it discloses irreversibility ('cannot be undone'), the absence of a draft step, the confirmation prerequisite, the refusal when confirm is missing, and the Gmail authorization requirement. This is exemplary behavioral disclosure.

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

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

The description is only three packed sentences, front-loaded with the irreversible action and immediately followed by the critical safety rule. Every clause earns its place, covering confirmation, moded behavior, and authorization without 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?

Given six parameters, no annotations, and no output schema, the description fully specifies preconditions, the confirmation gate, both usage modes, parameter dependencies, and auth requirements. It leaves no ambiguity about how or when to invoke the 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?

Although schema coverage is 100%, the description adds crucial semantics beyond the schema: confirm must be true or the call is refused, to/subject are only required when thread_id is omitted, and subject is ignored in thread replies. These conditional interrelations are not evident from the property descriptions alone.

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 ('SENDS a real email immediately') and identifies the resource ('authorized Gmail account'), making the tool's purpose unmistakable. It also differentiates from sibling tools like draft_gmail_reply by emphasizing there is no draft step and no undo.

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

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

It gives an explicit when-to-use gate: 'Only call this after showing the user the exact to/subject/body and getting explicit confirmation' and states the hard requirement 'must include confirm: true or it is refused.' It also explains the two distinct modes (thread_id vs to + subject), giving clear situational 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It richly covers partial updates ('Only the fields you supply are changed'), clearing fields ('pass an empty string to clear a field'), renaming via 'new_company / new_position', custom columns via 'extra_fields', refusal on 'missing or ambiguous matches', date validation, and file backup. This goes well beyond basic what-it-does and gives the agent a strong sense of side effects and guardrails.

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 concise sentences with no filler. The first sentence front-loads the core purpose, followed by efficient details on partial updates, clearing, renaming, and extra_fields, then a final sentence covers failure modes and side effects. Every phrase earns its place, making it easily scannable and informative.

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

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

Given the complexity of 13 parameters and no annotations or output schema, the description covers essential behavior: matching criteria, partial update semantics, clearing, renaming, custom fields, refusal conditions, validation, and backup. It does not mention return values or confirmation behavior, but since there is no output schema, this is not a strict requirement. It also does not reference sibling tools like 'update_job_status', which would have improved completeness, but the description is still substantive enough for an agent to use the tool safely and effectively.

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 covers 69% of parameters, so the baseline is 3. The description adds meaningful semantics beyond the schema: it clarifies the partial-update behavior, the empty-string clearing mechanism, the purpose of 'new_company'/'new_position' for renaming, and that 'extra_fields' sets custom columns. These details help an agent understand how parameters interact, which is not evident from the schema alone. The description does not compensate for the remaining 31% of undocumented parameters, but it adds enough value to warrant a 4.

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 the specific verb 'Edit' and clearly states the resource: 'existing application, matched by company + position'. It conveys the tool's broad scope ('any field(s)'), which is consistent with its title. However, it does not explicitly differentiate from the sibling tool 'update_job_status', which is a more specialized alternative for status-only updates.

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 the tool ('existing application', matched by company + position) and provides operational details like 'Only the fields you supply are changed' and 'pass an empty string to clear a field'. However, it does not explicitly say when to use this tool instead of alternatives such as 'update_job_status' or 'add_job', nor does it list exclusion criteria. The intended use is inferred rather than explicitly contrasted with sibling tools.

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

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

With no annotations provided, the description carries the transparency burden. It discloses important behaviors: 'Validates the row exists and backs the file up before writing.' This goes beyond a bare 'update' and reassures the user about safety, though it doesn't detail error handling or return values.

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 concise sentences, no redundancy. The first sentence front-loads the purpose, and the second adds key safety details. Every word earns its place.

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

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

For a simple 4-parameter update tool with no annotations or output schema, the description covers the essentials: what is updated, matching criteria, validation, and backup. Missing return-value/error behavior is a minor gap, but the description is sufficient for typical usage.

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 baseline is 3. The description adds semantic value by grouping parameters into roles: 'status (and optionally the notes)' and 'matched by company + position.' This clarifies how parameters relate, which is extra beyond the schema's per-field 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 clearly states the tool's action: 'Update the Status (and optionally the Notes) of an existing application.' It specifies the matching criteria (company + position), which distinguishes it from generic update_job or other mutations. This is a precise verb+resource+scope statement.

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 clear context for when to use the tool: it updates an existing application identified by company and position. However, it does not explicitly mention alternatives or exclusion criteria (e.g., 'use update_job for other fields'), so it stops short of full 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It goes beyond a simple mutation statement by revealing that it only edits existing fields, backs up the file first, and reports old → new values. It also scopes the operation to the single file, which is valuable context. This level of detail surpasses typical tool descriptions.

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 (three sentences) and front-loaded with the core purpose in the first sentence. Each subsequent sentence adds meaningful detail: the existing-field constraint, backup and reporting behavior, and file scope. There is no fluff or redundancy, making it highly 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 straightforward two-parameter update operation, the description covers the essential aspects: what it does, its constraints, the backup mechanism, and the reporting of old/new values. Since no output schema is provided, describing the 'reports old → new' behavior is a good substitute for return format. The description is sufficiently complete for an agent to use this tool correctly.

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

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

The input schema already provides 100% coverage for both parameters, including concrete examples for 'path' and a type list for 'value'. The description adds some context with 'dot/bracket path' and use-case examples, but these are largely re-statements of schema information. The baseline of 3 is appropriate when the schema handles most of the explanatory 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 the verb 'Update', the specific resource 'resume_master.json', and the scope 'one existing field' with dot/bracket path. It distinguishes itself from sibling tools like 'get_resume_master_field' and 'list_resume_master_structure' by focusing on mutation of existing fields. Examples (corrected date, added skill, new project) further clarify the intended use.

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 notes that it 'will not create new keys', providing a clear constraint on when not to use it and directing schema additions to manual hand-editing. It also scopes usage to 'resume_master.json only', which prevents accidental use on other files. However, it does not explicitly name alternative sibling tools for different scenarios (e.g., add vs. update), leaving some inference to the user.

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