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

No annotations are present, so the description must disclose behavioral traits. It mentions 'modify' but fails to disclose that the 'delete' action permanently destroys resources. It also inaccurately emphasizes read-only 'view' operations without warning about side effects, leaving the agent unprepared for destructive consequences.

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

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

A single, front-loaded sentence that efficiently conveys the tool's scope. It avoids redundancy and is easy to parse, though it could briefly mention side effects without bloating.

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

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

For a tool with a destructive delete action and no annotations, the description is underspecified. It omits any warning about irreversible changes, return formats, or required permissions. The sibling tools are clearly different, but the description doesn't cover the high-risk nature of the delete 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?

Schema coverage is 100% with basic property descriptions. The description adds context by naming specific resource types (EC2, RDS, S3) that align with the resource_type enum, and mentions outputs like status/IP addresses. However, it doesn't explain what each action (list, status, delete) does or how resource_id relates to them, offering only marginal added value.

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 identifies the resource domain (cloud infrastructure: EC2, RDS, S3) and the general actions (query or modify). It distinguishes from sibling tools focused on repos, deployment, or CI by emphasizing infrastructure management, though it doesn't enumerate the specific actions (list/status/delete) which are left to the schema.

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

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

The description implies usage for cloud infrastructure management but provides no explicit guidance on when to choose this tool over alternatives, nor any exclusions or prerequisites. It doesn't mention that it's the go-to for EC2/RDS/S3, which limits selection confidence.

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

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

No annotations are present, so the description carries the burden. It discloses that the tool returns repo details including CI status and deploy keys, implying a read-only operation. However, it does not mention authentication, rate limits, or whether the search is exhaustive. This is acceptable for a simple query tool but not rich.

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

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

The description is two short sentences, front-loaded with the action and resource, then adds return-value specifics. Every word contributes value.

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

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

For a simple two-parameter query tool with no output schema, the description conveys the core operation and key return fields. It could be slightly more explicit about output structure, but the context is sufficient for an agent to decide selection.

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 provides 100% coverage for both parameters ('query' and 'language'), so the description's mention of indexing by name or language adds little beyond the schema. No additional semantic detail such as formatting or matching rules is provided.

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

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

The description uses the specific verb 'Search' and clearly identifies the resource (code repositories) and the two search dimensions (name, programming language). It also distinguishes itself by mentioning returned fields (CI status, deploy keys), setting it apart from sibling tools like eng.run_ci_pipeline or eng.read_source_file.

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?

While no explicit exclusions or alternative tool mentions are provided, the purpose is so specific that the usage context is clear. The description implies when to use: when needing repository discovery and metadata retrieval, as opposed to pipeline execution (eng.run_ci_pipeline) or file reading (eng.read_source_file).

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. The verb 'read' implies a non-mutating operation, but the description does not mention error handling, required permissions, or whether it can read files from any repo. It is adequate but not rich in detail.

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 contains no extraneous information. 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 read tool with fully documented parameters and no output schema, the description is mostly complete. It does not describe the return format or error conditions, but the core purpose and parameters are sufficiently covered.

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

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

Schema description coverage is 100%, with clear descriptions for both 'path' and 'repo'. The tool description adds minimal extra meaning beyond restating the source file context, so it meets the baseline without further compensation.

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 source code file from a repository, using a specific verb and resource. This differentiates it from sibling tools like eng.query_repos (which likely lists repos) and other eng tools focused on deployments or CI.

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 clear usage context: 'useful for code review, debugging, and understanding implementation details.' However, it does not mention any alternatives or when not to use this tool, so it lacks explicit exclusion criteria.

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 must carry the full transparency burden. It mentions 'Execute' but does not disclose side effects (e.g., build artifacts), whether the call is blocking, required permissions, or what the response contains. This is insufficient for an execution 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, front-loaded sentence that states the primary action and optional override without any filler. Every phrase 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?

The tool has no output schema and no annotations, yet the description fails to mention return values, error handling, or operational prerequisites. An agent invoking this tool would not know how to interpret results or anticipate failures, making the description incomplete for real-world 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%, with both parameters described in the schema. The description reinforces the purpose of 'config_override' but adds no deeper detail about format or behavior beyond the schema. 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 action ('Execute') and resource ('CI/CD pipeline for a repository'), and mentions an optional configuration override. This distinguishes it from sibling tools like 'eng.trigger_deployment', which focuses on deployments rather than CI.

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 use: running a CI/CD pipeline. It does not explicitly exclude alternatives or provide when-not-to-use guidance, but the primary use case is unambiguous. Absence of contrast with siblings is a minor gap.

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 of behavioral disclosure. 'Deploy' implies a significant mutating action, but the description does not mention impact, rollback, approval requirements, or any side effects on production. This is a high-stakes operation, yet the description offers no safety or consequence context.

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

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

The description is two sentences, front-loaded with the primary action, and contains no redundant words. Every sentence contributes clear value: the first states what the tool does, the second clarifies the version input.

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 deployment tool with no output schema and no annotations, the description is too thin. It omits critical context such as whether the deployment is synchronous, what the response looks like, how to check status, or any prerequisites (e.g., permissions, CI status). The schema covers parameters, but the description does not complete the broader operational picture.

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

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

The input schema provides complete descriptions for all three parameters (100% coverage), so the baseline is 3. The description's mention of 'version to deploy (tag, branch, or commit SHA)' adds no new information beyond the schema's existing parameter description, which already states the same options.

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 deploys a repository to staging or production, which is a specific action with a clear resource and scope. It distinguishes from siblings like eng.run_ci_pipeline (which runs CI) and eng.manage_infrastructure by focusing on deployment.

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 (when you need to deploy to an environment) but provides no explicit guidance on when not to use it or how it relates to alternatives like eng.run_ci_pipeline. Usage is implied from the action described, not explicitly stated.

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

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

With no annotations, the description carries the full burden for behavioral disclosure. It does not state whether the operation is read-only, has side effects, or what the 'structured data' output format is (e.g., CSV vs JSON). The term 'Export' implies a read but is not explicit.

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?

Single sentence plus a list, front-loaded with the verb and resource. No redundant or filler content; 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 two-parameter tool, the description supplies the critical report type enumeration, but lacks details on output format or any constraints on date_range. Since there is no output schema, these omissions leave some ambiguity, though the tool is still minimally usable.

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 descriptions cover both parameters (100%), so baseline is 3. The tool description adds value by enumerating valid report types (invoices, expenses, payment_methods, payroll), which the schema does not provide via enums, improving parameter understanding.

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 clearly states 'Export financial reports as structured data' with specific verb and resource. It also lists available report types, distinguishing it from siblings like fin.query_invoices (individual queries) and hr.run_payroll_report (HR-specific).

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

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

No guidance on when to use this tool vs alternatives such as fin.query_invoices or hr.run_payroll_report. The description only defines the action without context on selection criteria or exclusions.

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

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

No annotations are provided, so the description carries the full burden. It says 'Process a payment' but does not disclose consequences, reversibility, required permissions, or side effects. For a financial mutation, this is a significant gap.

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

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

The description is a single, front-loaded sentence with no redundant words. It efficiently states the action and supported methods.

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 mutational and financially sensitive tool with no output schema or annotations. The description omits crucial context such as return values, error handling, and side effects, leaving the agent underinformed for a high-stakes 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?

Schema description coverage is 100%, so parameters are already documented. The description repeats the payment methods enum but adds no additional meaning beyond what the schema provides.

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 processes a payment for a specific invoice and lists supported methods (credit card, ACH, wire). However, it does not differentiate from the sibling tool fin.wire_transfer, which could also be used for wire payments.

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

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

No explicit guidance on when to use this tool versus alternatives like fin.wire_transfer or fin.query_invoices. It does not mention prerequisites (e.g., invoice must exist) or scenarios where another tool 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. It indicates a search/filter operation, implying non-mutating behavior, and mentions return content (payment methods, bank transfer info). However, it does not explicitly confirm read-only safety, pagination, or other limits, 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 concise and front-loaded: it starts with the verb and resource, then lists filter criteria and return details. Two sentences, no filler, every word adds value.

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

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

The tool is simple (3 optional params, no output schema). The description covers purpose, filters, and return content, which is quite complete for a query tool. Lack of output schema is offset by mentioning return details, though it omits combinability or default behaviors—not critical here.

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

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

Schema description coverage is 100%—all three parameters have clear descriptions. The description merely echoes schema (status, customer, min_amount) without adding extra format, units, or combination logic. 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 uses a specific verb ('Search and filter') and identifies the resource ('customer invoices') with clear filtering criteria (status, customer name, minimum amount). It clearly distinguishes itself from sibling tools like process_payment or wire_transfer by indicating a read/query 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 implies this is for querying invoices and returning details, but it does not explicitly state when to use this tool over alternatives or provide exclusions. There's no explicit mention of 'use this instead of X' or 'not for payments'.

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 must disclose side effects, permissions, or consequences. It only says 'submit' or 'list' without explaining what happens on submit, whether data is persisted, or what is returned.

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 short and front-loaded, but the two sentences are somewhat redundant. It earns a 4 rather than 5 due to minor repetition.

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 lacks an output schema and annotations, so the description should explain return values, action-specific parameter requirements, and error behavior. It does none of this, making it incomplete for effective 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?

All parameters are already described in the input schema (100% coverage), so the description adds little beyond restating the action enum. 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 submits or lists expense reports, using specific verbs and a distinct resource. It is distinguishable from sibling tools like fin.query_invoices, though it doesn't explicitly contrast them.

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

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

It implies usage by naming the two supported operations ('submitting new expenses' or 'viewing existing reports'), but does not provide explicit when-to-use or when-not-to-use guidance relative to 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 must carry the behavioral disclosure burden. It only restates the purpose and parameter requirements, and fails to mention significant characteristics like reversibility, authorization levels, or confirmation steps, which are crucial for a wire transfer.

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 concise sentence that immediately states the action and requirements. It is well-structured and front-loaded with no unnecessary 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 tool with no annotations and no output schema, the description is too sparse. It does not explain what happens after initiation, any potential side effects, failure modes, or required authorizations, leaving significant gaps for an agent to operate safely.

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

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

Schema description coverage is 100%, so parameters are fully documented in the schema. The description adds no additional semantics beyond echoing the required parameters, providing no extra value.

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 ('Initiate a bank wire transfer'), the target resource ('external account'), and required inputs. It distinguishes itself from sibling tools like fin.process_payment by specifying the wire transfer mechanism and external account scope.

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 offers no guidance on when to use this tool versus alternatives such as fin.process_payment or internal transfers. It lacks any context about prerequisites, appropriateness, or exclusions.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not mention side effects (e.g., whether the letter is sent, stored, or requires approval) or output format. For a generation tool, this lack of impact disclosure is a significant gap.

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

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

A single, well-structured sentence that immediately states the tool's action and core inputs. Every word earns its place, with no redundancy or filler.

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

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

The tool is simple, but with no output schema and no annotations, the description should explain what the return value or side effect is. It does not clarify whether the offer letter is generated as a file, a draft, or an email. This leaves the agent guessing about the tool's end result, making it minimally complete.

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

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

Schema description coverage is 100% with meaningful descriptions for all three parameters. The description adds only a slight rephrasing ('specified compensation and start date') without introducing new semantic details 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 uses a specific verb ('Generate') and resource ('formal offer letter'), clearly distinguishing it from sibling tools like hr.review_candidate or hr.update_employee. It also specifies key inputs (compensation and start date), making the tool's function 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?

While it does not explicitly state when-not to use or name alternatives, the tool's purpose is singular and self-evident: generating an offer letter. The context is clear enough for an agent to infer when it applies, though explicit guidance about when to prefer other HR tools is absent.

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 must disclose behavioral traits. It clearly indicates a read operation ('Retrieve'), but it does not specify response format, whether the resume is embedded or a link, or any potential limitations (e.g., candidate may not have a resume). This is the minimum viable disclosure for a simple retrieve 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 two compact sentences, front-loaded with the core action and resource. Every word adds value—'Retrieve a job candidate's profile including their resume for review'—and it avoids redundancy or filler. Excellent structure.

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 read tool with no output schema or annotations, the description is fairly complete. It tells what will be retrieved (profile + resume) and the purpose (evaluation). It does not describe the return structure, but that may not be necessary given the tool's simplicity. A minor gap is not mentioning any prerequisites (e.g., candidate exists), but overall it 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 covers the single parameter candidate_id with a description ('Candidate ID to review'), providing 100% coverage. The tool description adds that the profile includes a resume, which gives context for what the ID is used for, but it does not add significant semantic detail beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's function with a specific verb ('Retrieve') and resource ('a job candidate's profile including their resume'). It also adds the purpose ('for review' / 'evaluate candidates for open positions'), which distinguishes it from sibling tools like hr.search_employees (employees, not candidates) and hr.generate_offer_letter (post-selection action).

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: 'Use this to evaluate candidates for open positions.' It implies the tool is for candidate evaluation, but it does not explicitly mention alternatives or when not to use it. Given the sibling tools are in different domains (payroll, IT, etc.), the usage context is unambiguous enough.

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 disclosure burden. It reveals the report's content (compensation, tax withholdings, bank account details) and implies a read-only/computation operation. However, it does not mention access restrictions, side effects, or output format, which would be useful for a tool handling sensitive payroll data.

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

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

The description is two sentences: the first states the purpose, the second briefly outlines the output contents. It is front-loaded, concise, and every sentence adds information 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?

For a simple two-parameter tool with no output schema, the description covers the main purpose and output contents. However, it does not clarify behavior when optional parameters are omitted (e.g., period default) and does not mention the 'department' filter, leaving minor gaps. Overall, it is reasonably complete for its simplicity.

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

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

Schema description coverage is 100%, with both parameters ('period' and 'department') documented. The description adds no additional parameter semantics beyond restating 'pay period' and omitting any mention of the 'department' filter. Thus, it provides no value beyond the schema, warranting the baseline score.

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: 'Generate a payroll report for a given pay period.' It uses a specific verb ('generate') and identifies the resource ('payroll report') and scope. It also distinguishes from sibling HR tools like employee search or offer letter generation.

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 (generating a payroll report for a pay period) but does not explicitly state when not to use it or mention alternatives. It provides clear context but lacks exclusions or comparisons to 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, description carries full responsibility. It discloses return type (employee details, contact info) and the sensitive flag, but the phrase 'Set include_sensitive=true' implies sensitive data is excluded by default, contradicting the schema's default:true. This could mislead the agent about behavior.

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

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

The description is brief and front-loaded, with three short sentences directly covering purpose, return value, and an important option. No redundant words or extraneous detail.

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 search tool with full schema coverage, the description is largely complete: it explains search dimensions, return content, and the sensitive flag. However, the missing clarification about the include_sensitive default creates a small but notable gap.

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

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

Schema coverage is 100% and all parameters are described. The description adds little beyond the schema by essentially restating query and department semantics, and does not clarify the default value discrepancy for include_sensitive.

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 with a specific verb ('Search') and a clear resource ('employee directory'), and enumerates search dimensions (name, department, role). It is easily distinguishable from sibling tools like run_payroll_report or update_employee.

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 the tool (searching for employee info by name/dept/role) but does not explicitly mention alternatives or exclusions. The sibling list makes it obvious, but explicit direction would be stronger.

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 mentions that any field can be modified, implying potentially destructive changes, but it doesn't describe consequences, reversibility, required permissions, or side effects. For a mutation tool, this is insufficient transparency.

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 directly states the action and scope, with no filler or redundant information. It is appropriately concise 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?

The tool has two parameters (one a free-form object), no output schema, and no annotations. The description omits useful context such as what the tool returns, how errors (e.g., invalid employee ID) are handled, or whether updates are transactional. For a tool that can modify arbitrary fields, this leaves the agent without enough information to anticipate 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?

The input schema already describes both parameters clearly: employee_id as an integer to identify the employee, and fields as an object of key-value pairs to update. The description adds example field names but doesn't explain the format, nesting, or validation rules of the fields object. With 100% schema coverage, the description's incremental value is minimal, warranting a baseline score.

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 ('Update') and the resource ('employee's record'), and lists example modifiable fields such as name, role, salary, and department. While it doesn't explicitly contrast with sibling tools, the verb+resource pairing makes the tool's 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?

The description provides no guidance on when to use this tool versus alternatives, no prerequisites, no exclusions, and no mention of appropriate scenarios. It only states what the tool does, not when it should be selected over other HR tools like search_employees or run_payroll_report.

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 must fully disclose behavioral traits. It mentions 'optional sudo elevation,' which hints at privileged execution, but it does not disclose potential destructive side effects, required permissions, or output behavior. For a tool that runs arbitrary shell commands, this is a significant transparency gap.

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

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

The description is two sentences and front-loads the purpose. Every word contributes: the first sentence states the action and context, the second mentions shell commands and sudo. No redundancy or fluff.

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

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

For a high-risk admin command execution tool, the description is underpowered. It lacks any mention of return values, error handling, timeout behavior despite the schema having a timeout parameter, or warnings about irreversible changes. The schema partially covers parameters but the overall tool behavior is not fully described.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds no parameter detail beyond what the schema already provides; it only restates that shell commands and sudo are supported. No extra syntax, format, or edge-case info is given.

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 what the tool does: 'Run administrative system commands for maintenance and troubleshooting.' The verb 'Run' and resource 'administrative system commands' make the primary action explicit. It distinguishes from siblings like it.query_audit_log or it.get_system_config by focusing on command execution, though it does not explicitly name alternatives.

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 'for maintenance and troubleshooting' provides clear context for when to use the tool. However, it does not mention when not to use it or explicitly compare with alternatives, 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 provided, the description carries the full burden. It clearly indicates a read-only operation and specifies the returned data types, which is useful. However, it does not disclose potential side effects, permission requirements, or the sensitivity of returning API keys and database URLs, nor the behavior when no key is provided or when a key is not found.

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 extremely concise: two short sentences totaling 14 words. It front-loads the primary action ('Read') and immediately follows with the return types. No unnecessary words 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?

The tool is simple, with one optional parameter and no output schema, so the description is reasonably sized. It explains the tool's purpose and return content, but it omits details such as the effect of leaving the key empty (though the schema covers this), error behavior, and security/prerequisite context. For a config getter, it is adequate but not fully complete.

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

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

The schema description for the 'key' parameter is 100% complete, so the description adds minimal additional semantic value. It mentions 'system configuration values' but does not elaborate on the parameter's role beyond what the schema already states. Baseline of 3 is appropriate given full 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 uses a specific verb ('Read') and identifies a clear resource ('system configuration values'). It further details that it returns database URLs, API keys, and other service configuration, which distinguishes it from sibling tools like it.query_audit_log or it.manage_api_tokens.

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 what the tool does but provides no guidance on when to use it versus alternatives. Sibling tools such as it.manage_api_tokens manage API keys, and without explicit differentiation, users/agents may be uncertain whether to use this tool or the sibling for retrieving API keys. No exclusions or alternative references are given.

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 must bear full responsibility for disclosing behavioral traits. It only states that tokens provide access; it does not disclose side effects of revoking tokens, permission requirements, or whether actions are reversible. This leaves the agent without critical safety context for a management action like revoke.

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, front-loaded with the three main actions. Every clause adds value, and the structure is immediately scannable.

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 no output schema and no annotations, the description should ideally clarify return values or per-action requirements, but it does not. However, the schema covers parameter semantics thoroughly, and the tool's actions are straightforward. The description is adequate but leaves room for improvement regarding what each action returns or requires.

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 little beyond what the schema already provides—'for user accounts' is the only extra semantic hint. Since the schema fully documents the action, scope, and username parameters, the description's contribution is minimal but not misleading.

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 generates, lists, or revokes API tokens for user accounts, which is a specific resource type distinct from sibling tools like it.manage_users or it.query_audit_log. It uses specific verbs and names the resource.

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

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

No guidance is provided on when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or scenarios where another sibling tool would be more appropriate, such as using it.manage_users for user account management.

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 responsibility for behavioral disclosure. While it states the tool performs mutations, it fails to mention side effects, permissions required, reversibility of actions, or return values. For a user management tool, important behaviors like account deactivation implications or idempotency are not addressed, leaving significant gaps.

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

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

The description is two sentences, front-loaded with the primary action, and contains no filler. Every word contributes to understanding the tool's scope. It is appropriately concise and well-structured.

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

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

The tool supports four distinct actions (list, create, update, disable), but the description only covers create/update/disable explicitly and ignores the 'list' action entirely. With no output schema, the agent is left without clarity on expected results for any action. The description is too brief for a multi-action management tool, failing to explain behavior per action or response 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?

The input schema has 100% description coverage for all parameters, so the baseline is 3. The description's mention of 'roles and permissions' only reiterates the role and permissions properties without adding new meaning, syntax, or relationships. It adds no 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 clearly states the tool's function with specific verbs ('Create, update, or disable') and a distinct resource ('user accounts in the NovaTech identity system'). It distinguishes itself from sibling tools like it.manage_api_tokens by focusing on user accounts rather than tokens, 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?

No guidance is provided on when to use this tool vs alternatives. The description does not mention any exclusions, prerequisites, or alternative tools for similar tasks. It simply lists capabilities without contextualizing when each action (create, update, disable, list) should be chosen, leaving the agent without decision-making support.

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 must carry the full burden of disclosure. It only states the search and filter capabilities, but does not disclose return format, ordering, rate limits, or permission requirements. This is a significant gap for a tool that reads security logs.

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, focused sentence that front-loads the primary purpose and then lists the filter dimensions. There is no filler or redundancy, 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?

Given the simple schema with three optional parameters and no output schema, the description is minimally adequate. However, it omits behavioral details such as what the returned results look like, any ordering, or access restrictions, leaving some gaps for a security-related 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?

All three parameters have schema descriptions, giving 100% coverage. The description's mention of 'actor, action type, or time range' simply echoes the parameter names and does not add additional semantic detail beyond what the schema already provides. 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 uses the specific verb 'search' with a clear resource ('system audit log') and purpose ('security events'). It distinguishes itself from sibling tools like it.manage_users or it.get_system_config, which handle different IT resources.

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 the usage context: investigating security events in the system audit log. It does not explicitly mention when not to use it or name alternative tools, but the context and filter options provide clear guidance.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool creates, updates, or lists campaigns, which implies mutating behavior, but it does not disclose return values, pagination, side effects, partial update semantics, or any required permissions. For a tool with zero annotation coverage, this is insufficient transparency beyond basic CRUD.

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 and relatively efficient. The first sentence states the primary actions; the second expands on what 'manage' covers. However, the second sentence is somewhat redundant with the first, as 'create, update, or list' already implies management. Still, it is concise with no filler or excessive length.

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 CRUD tool with 3 parameters and no output schema, the description adequately conveys the tool's actions and the main data fields. It does not explain return values or edge cases like pagination or the need for campaign_id in updates, but the schema covers the campaign_id requirement. Given the tool's moderate complexity, the description is minimally viable but leaves some contextual gaps.

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

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

Schema description coverage is 100% (all parameters have descriptions), so the baseline is 3. The description adds little beyond the schema: it repeats the list of campaign details (channel, budget, target audience, email templates) that already appear in the 'data' parameter description. No additional meaning or syntax is provided beyond what the schema already contains.

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: 'Create, update, or list marketing campaigns.' It names a specific verb ('create', 'update', 'list') and a specific resource ('marketing campaigns'), and further details the managed fields (channel, budget, target audience, email templates). This distinguishes it from sibling tools like mktg.send_campaign_email and mktg.query_analytics, which have 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 implies when to use the tool (for CRUD operations on campaigns) but does not explicitly contrast it with alternatives such as send_campaign_email or query_analytics. There is no direct statement about when not to use this tool or which sibling should be used instead. The action enum helps clarify, but the prose lacks explicit 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 full burden of behavioral disclosure. It states 'update' as a possible action but does not disclose any side effects, permission requirements, reversibility, or what the update operation actually changes. This is a significant gap for a mutation-capable tool.

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

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

A single, focused sentence that front-loads the actions ('List or update') followed by the resource and scope. Every word contributes to the meaning 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?

The description is insufficiently informative for a tool with no output schema and no annotations. It does not explain what an 'update' entails (no additional config fields are mentioned) or what the response looks like. While the parameters are clear, the outcome and side effects are left entirely ambiguous.

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 provides complete descriptions for both parameters (action and platform) with enums, achieving 100% coverage. The description adds context about the company and platforms but does not add meaningful semantic detail beyond the schema, 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's function with specific verbs ('List or update') and a specific resource ('social media account configurations'), plus a defined scope ('NovaTech's presence on Twitter, LinkedIn, and Facebook'). This distinguishes it from sibling marketing tools like manage_campaigns or query_analytics.

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

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

The scope is made very clear (managing social account configs), and the actions are enumerated. However, it does not explicitly mention when not to use it or point to alternative tools for other resources (e.g., campaigns). Still, the context is unambiguous enough for an agent to infer appropriate use.

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 disclosing behavioral traits, but it fails to do so. It does not explicitly state that the tool is read-only, mention rate limits, authentication requirements, or describe the return format. The verb 'Query' implies a read operation, but no additional context is given about what happens when filters are applied, how results are paginated, or whether any side effects occur. This is a significant gap given the lack of annotations.

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

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

The description is concise and well-structured, consisting of two sentences. The first sentence front-loads the core purpose with a verb and resource, while the second sentence adds helpful examples of the data types it covers. There is no redundant or filler content; 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?

Given that this is a relatively simple query tool with three optional parameters and no output schema, the description is minimally adequate. It fails to mention what the tool returns (e.g., raw events vs. aggregated metrics) and lacks any usage context. However, the simplicity of the tool and the high schema coverage mitigate the need for extensive explanation. A more complete description would clarify the return format and any implicit behavioral constraints.

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

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

The schema description coverage is 100%, with each parameter (since, user_id, event_type) having a clear description. The tool description adds a bit of context by listing example event types (page views, API calls, feature usage) that align with the event_type parameter, but it does not add significant meaning beyond the schema. The baseline score of 3 applies since the schema already provides adequate parameter documentation.

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

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

The description clearly states the tool's function with a specific verb ('Query') and the resource ('user analytics and event data'). It enumerates the types of data (page views, API calls, feature usage, user engagement metrics), making its scope understandable. However, it does not explicitly differentiate itself from sibling tools like it.query_audit_log or fin.query_invoices, which also deal with data queries, though the domain is implicitly distinct.

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 no guidance on when to use this tool versus alternatives, nor does it mention any prerequisites, exclusions, or preferred contexts. It only describes what the tool does, leaving the agent to infer usage scenarios from the tool name and description. There is no mention of when not to use it (e.g., for audit logs or financial data).

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, leaving the description to carry the full burden of behavioral disclosure. The description only mentions the two content modes, but fails to disclose side effects (e.g., email actually sent), permission requirements, or response/error behavior. For a mutation-like tool, this is a significant transparency gap.

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

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

The description is two sentences, front-loaded with the core purpose, and contains no fluff. Each clause adds relevant information, 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?

With 3 parameters, no output schema, and no annotations, the description provides the essential purpose and a hint of parameter relationships, but does not explain return values, side effects, or prerequisites. It is minimally viable but leaves gaps for an agent that needs to know the impact and success criteria.

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's mention of 'campaign template or custom body content' adds no new meaning beyond the schema, which already documents that custom_body overrides template. The description does not enhance parameter understanding.

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 starts with a specific verb and resource: 'Send a marketing email to a customer or prospect.' It also notes the two content modes (campaign template or custom body), making the tool's scope clear and distinct from siblings like mktg.manage_campaigns.

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: to send a marketing email to a customer or prospect, with the option of a template or custom content. However, it does not explicitly exclude alternatives or mention when not to use it, so it lacks full exclusion 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 explains what information is retrieved and how to search, but does not disclose behaviors such as behavior when no parameters are provided, parameter precedence when both are given, or return format (no output schema). This is a moderate level of transparency 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?

The description is two sentences, front-loaded with the action ('Retrieve customer account profiles'), and includes the key scope and search methods without any unnecessary words. 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 lookup tool, the description covers the main purpose and parameters. However, the absence of an output schema and the optional nature of both parameters leave ambiguity about return structure and behavior when no parameters are supplied. The description is adequate but not fully complete for all context.

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

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

Schema description coverage is 100% because both 'email' and 'customer_id' have descriptions. The description adds only the 'or' relationship between the two parameters, confirming they are alternative search keys. This adds marginal value beyond the schema, so the baseline score 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 retrieves customer account profiles, specifying the content (contact information, subscription plan, account notes) and the search keys (customer ID or email). This is a specific verb+resource combination that distinguishes it from sibling tools like support.read_tickets or support.search_knowledge_base.

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 usage for looking up customer profile information by ID or email, providing clear context for when to use this tool. It does not explicitly name alternatives or exclusion criteria, but the domain-specific purpose makes the appropriate use case 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?

No annotations are provided, so the description carries the transparency burden. It adds a notable behavioral detail: 'Returns ticket details including customer message body,' which highlights the sensitive content. However, it does not mention authentication, rate limits, or pagination behavior, leaving gaps expected 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 concise, containing two short sentences that front-load the primary action and then add useful details. No wasted words or irrelevant information, making it easy to scan.

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 read operation with 3 optional parameters and no output schema, the description sufficiently covers the core purpose and return value. It does not explain default count behavior or pagination, but these are minor gaps given the schema covers defaults, making it almost complete.

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

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

Schema coverage is 100%, with all three parameters already described. The description redundantly lists the filter enums (status, priority) but adds no new meaning beyond what the schema provides. It does mention the return body but that is not parameter-specific, so 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 ('Read customer support tickets') and the resource, with specific filters (status, priority) and return details. It distinguishes itself from sibling tools like support.reply_to_ticket and support.search_knowledge_base by focusing on reading ticket data.

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 this tool (reading support tickets) but does not explicitly mention alternatives or exclusions. While sibling tools are distinct, there is no direct 'use this instead of X' guidance, so it stops short of a 5.

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

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

With no annotations provided, the description carries the full burden of disclosing behavior. It explicitly states that the reply goes to the customer's email and that the ticket is marked as resolved, which is a non-obvious side effect. However, it does not cover other possible behavioral aspects like reversibility 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 consists of two concise sentences that front-load the main action and then provide the key side effect. There is no filler or redundant information, 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 simple 2-parameter tool with no output schema and no annotations, the description covers the core behavior and the important side effect of marking the ticket resolved. It is adequate, though it lacks potential caveats such as whether the ticket must be open or if the action is permanent.

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 descriptions for both parameters ('Reply message content' and 'Ticket ID to reply to'), and the description adds no additional parameter meaning. With 100% schema coverage, the baseline score 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 identifies the tool's function with a specific verb ('Send') and resource ('customer support ticket'), and it distinguishes itself from sibling tools by noting the reply is sent to the customer's email and the ticket is marked as resolved. This makes the purpose unambiguous and well-differentiated.

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: to send a reply and resolve a ticket. It does not explicitly mention alternative tools or exclusions, but the context is sufficient for basic selection among related support tools like read_tickets or search_knowledge_base.

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 implies a read-only operation through 'Search' but does not disclose return format, pagination, or any limitations. While it is clearly non-destructive, the absence of details about output behavior leaves room for 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 conveys the action, resource, and scope without any waste. Every word contributes meaning, making it exceptionally concise and well-structured.

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

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

The description adequately defines the tool's purpose but lacks details about what the search returns (e.g., summaries, IDs, full articles) or any usage limitations. Since there is no output schema, the description could be more complete by disclosing result format, though it remains minimally viable for a simple search tool.

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

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

The input schema already describes both parameters with 100% coverage, including the category enum values. The tool description adds no additional semantic value beyond what is in the schema, 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 identifies the verb 'Search' and the resource 'internal knowledge base', with specific scope (NovaTech products, troubleshooting guides, company policies). This distinguishes it from sibling support tools like support.reply_to_ticket and support.read_tickets, which have 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 provides clear context that this tool is for searching knowledge base articles, making it obvious when it should be used. It does not explicitly mention alternatives or exclusions, but the context is unambiguous given the tool's sole focus on searching, so no further guidance is needed.

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