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

With no annotations, the description carries the full burden. It discloses key behavioral traits like session-only private notes and mandatory is_shared for api_key callers, but omits return values, potential errors, or permission requirements.

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: three short sentences covering purpose, critical constraint, and attachment capability. Every sentence adds value with no redundancy.

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

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

For a create tool with no output schema, the description explains the core functionality and key constraints but does not mention the return value or error handling. It is adequate but leaves some 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 coverage is 100% with detailed descriptions for all parameters. The description adds a summary of constraints but does not go beyond the schema's already thorough 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 'Create a note' and adds distinguishing details about shared vs. private notes and attachment targets, differentiating it from sibling tools like list_notes. The verb and resource are 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?

The description provides essential usage context, such as api_key callers needing is_shared=true and the ability to pin notes via attachments, but it does not explicitly mention when to use this tool over alternatives or 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?

With no annotations, the description carries the full burden. It discloses that the tool creates a review request and returns its ID and status, and that it is for human oversight. However, it does not mention potential side effects, asynchronous behavior, or that the review may require polling. The schema covers idempotency and timeout, but the description itself adds only minimal 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 short sentences with no filler, front-loading the core action and return value. 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?

Given the tool's complexity (8 parameters, nested objects, idempotency, timeout, callbacks) and no output schema, the description is too brief. It does not explain the typical review workflow (e.g., list templates, create, then get/decide) or what happens after submission. The schema helps, but the description alone does not orient the agent sufficiently.

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 8 parameters have schema descriptions (100% coverage), so the baseline is 3. The tool description adds no parameter-specific information; it only states the return value. The schema already provides rich context such as calling list_templates for payload fields.

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 'Submit' with resource 'review request' and purpose 'human oversight'. It distinguishes from sibling tools by implying creation vs querying/acting (e.g., get_review, decide_review).

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 when human oversight is needed, but it does not explicitly mention when to use this tool versus alternatives. It lacks exclusions or references to related workflow steps like polling with get_review. The schema mentions calling list_templates first, but the description itself provides no such 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, and the description does not disclose any behavioral traits such as whether duplicate slugs are overwritten, validation rules, or side effects of creation. This leaves the agent without information about the operational 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?

The description is a single, front-loaded sentence with no filler or redundant detail. It communicates the core purpose 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?

Despite the schema covering parameters well, the description lacks context about the creation process, potential errors, return values, or implications of nested field structures. For a create tool with 6 parameters and no annotations, the description is too brief to be fully complete.

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

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

Schema description coverage is 83%, so the schema already documents most parameters. The description only mentions 'form fields and available actions', which adds no new semantics 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 uses a specific verb 'Define' with a clear resource ('new review template') and mentions key contents ('form fields and available actions'). This clearly distinguishes it from siblings like gatewerk_update_template and gatewerk_list_templates.

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 'Define a new review template' clearly indicates this is for creating a new template, providing clear context. However, it does not explicitly state when not to use it or name alternative tools like update_template for modifications.

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 full burden. It discloses the deprecated status and high-level behaviors (approve, reject, edit with modified payload, retry with feedback), but omits side effects, permissions, and response handling. This adds some context beyond the schema but not complete 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 a single compact sentence with a deprecation prefix. It is highly concise, front-loads the critical warning, and every phrase contributes meaning.

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 6 parameters, a nested object, and no output schema, yet the description provides only a high-level overview and a redirect to the successor. Deprecation mitigates the need for full detail, but for an active tool this would be incomplete. It does not explain return values or error behavior.

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 detailed parameter descriptions. The tool description adds only slight mapping between decision types and parameters (e.g., 'retry' implies feedback), but this is also inferable from the schema. The description provides no substantive extra parameter meaning.

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 a decision on a pending review and enumerates the supported decision types (approve, reject, edit, retry). The deprecation prefix explicitly names the successor tool, gatewerk_take_review_action, distinguishing it from siblings.

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

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

The deprecation notice provides explicit guidance to use gatewerk_take_review_action for templates with custom actions, which is a clear when-to-use alternative. It lacks further context on legacy usage, but for a deprecated tool this is sufficient.

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 adds the key behavioral detail that existing reviews using the template are not affected, which is valuable context for a delete operation. However, it does not mention irreversibility, permissions, or response 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 consists of two short sentences, the first stating the action and the second a caveat. No unnecessary words are present.

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 delete operation, the description covers the main functional purpose and the critical side-effect regarding existing reviews. It could mention irreversibility, but the provided information is sufficient for the tool's complexity.

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 fully documents the single parameter template_id with its format (gw_tpl_...). The description does not add additional semantic detail beyond the schema, so a baseline of 3 is appropriate.

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

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

The description uses the specific verb 'Remove' with the resource 'a template', making the action unambiguous. It also states that existing reviews are unaffected, which distinguishes this from potential related operations on templates.

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

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

The description does not explicitly state when to use this tool over alternatives like gatewerk_update_template or gatewerk_create_template. The usage is implied by the tool name and sibling context, but no direct guidance or exclusions are 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 full burden of behavioral disclosure. It discloses the return payload (parent chain run plus current step) and the 404 error condition for non-chain reviews. For a simple read-only getter, this is adequate, though it does not mention authentication or rate limits.

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 zero filler. Every sentence adds value: the first defines the operation, the second explains the return value and error behavior.

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 getter with no output schema, the description is complete: it states what is returned, the error case, and the primary use case. No critical operational details are missing, and the low complexity means this level of detail is fully 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 input schema already provides 100% coverage for the single parameter (review_id) with a clear description 'Review ID (gw_rev_...)'. The tool description adds no extra semantic detail about the parameter, but the schema is sufficient, so the baseline of 3 applies.

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

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

The description uses a specific verb+resource construction: 'Get chain context for a review,' clearly distinguishing it from siblings like get_review (which retrieves review details) and get_chain_run (which retrieves chain details). It further clarifies what is returned (parent chain run plus current_step_number), leaving no ambiguity about its purpose.

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 the intended use case ('useful to discover whether a review is part of a chain and what step it represents'), providing clear context. However, it does not explicitly name alternative tools or provide exclusion conditions, so it stops short of full when/when-not 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?

Since no annotations are provided, the description carries the full burden. It transparently discloses the return structure (status, mode, rejection_policy, steps[] with review_id, status, dependency wiring), which goes beyond the schema. It does not mention error behavior or permissions, but for a read operation this is adequate.

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

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

The description is two concise sentences, front-loaded with the action and followed by return details. Every word adds value, with no redundancy or filler.

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

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

For a simple one-parameter getter, the description explains the return payload well, compensating for the lack of an output schema. It lacks explicit differentiation from similarly named siblings, but the fundamental retrieval context is 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% and the parameter chain_run_id is documented with type and format hint (gw_chain_...). The description does not add extra semantics, but with full schema coverage the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Fetch') and resource ('chain run by ID'), clearly stating what the tool does. It distinguishes from sibling tools like gatewerk_get_chain_for_review and gatewerk_get_review by focusing on the chain run ID lookup.

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 given on when to use this tool versus alternatives. The description only states the action and return information, leaving the agent to infer usage from the name with no exclusions or alternative recommendations.

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?

Without annotations, the description carries the behavioral burden. The verb 'Get' implies a read-only operation, and the listed contents plus the presentation use case clarify that no mutation occurs. It does not explicitly address auth or errors, but these are less critical for a one-ID getter.

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: one sentence stating scope and contents, one sentence giving a use case. No redundant phrases 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 tool with one parameter and no output schema, the description provides a good overview of return contents and a practical use case. It could detail response structure more, but the enumerated elements offer adequate context for invocation.

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 fully documents the single 'review_id' parameter with a format hint (gw_rev_...). The description does not add further parameter semantics beyond referring to it as 'by ID', so the baseline 3 applies.

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

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

The description clearly states the tool's function: 'Get full review details by ID' and enumerates the included elements (payload, status, decision, feedback, template metadata). This distinguishes it from sibling tools like query_feedback or list_review_actions, which likely target subsets.

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?

Includes explicit usage instruction: 'Use this to present structured review forms in conversation.' This indicates the intended scenario, though it does not mention exclusions or specific alternatives. The sibling tool names imply specialized alternatives, so the guidance is sufficient.

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 safety and behavior. 'View' implies a read-only operation, but it is not explicitly stated as non-destructive. The description does describe the output behavior (metrics) but omits any caveats like timezone handling, status limitations, or whether the data is pre-aggregated or computed on demand.

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 (about 25 words) that front-loads the purpose ('View review metrics') and then lists the specific metrics in a clear, scannable sequence. Every word earns its place, and there is no 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?

For a zero-parameter, read-only stats tool with no output schema, the description provides a sufficient overview of the return content. It lists all the metric dimensions, which is enough for an agent to know what to expect. It does not specify the exact response shape or edge cases, but given the tool's simplicity, it is nearly 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 tool has zero parameters, and the schema coverage is trivially 100% (empty object). Per the rubric, 0 params baseline is 4. There are no parameter details needed, so the description does not need to add any param semantics beyond what the empty schema already communicates.

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 the tool's function with a specific verb ('View') and resource ('review metrics'), and enumerates the exact metrics returned (total count, breakdown, average time, per-template counts, daily trend). This distinguishes it from sibling tools that handle individual reviews, templates, or actions.

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 tool is for aggregated overview rather than detailed individual data, but it does not explicitly state when to use it over alternatives like list_reviews or get_review. There are no exclusions or alternative tool mentions, so the usage context is only implicit.

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 discloses that only notes visible to the caller are returned and supports cursor pagination, which are useful behaviors. However, it does not explicitly state read-only safety, permissions, or response shape, leaving some 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?

Two concise sentences: first states the core purpose and scope, second enumerates filters and pagination. Every word contributes, with no redundancy or fluff.

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

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

Given 9 parameters and no output schema, the description covers the main usage (filters + pagination) and clarifies the tool's scope. It omits return value structure and ordering, but for a list tool this is a reasonable trade-off given schema descriptions.

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 grouping (e.g., 'target' as attached_to_kind + attached_to_id) and lists filter categories, which goes beyond the schema's individual parameter 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 verb ('List') and resource ('notes visible to the caller within a project'). It also lists filters and pagination, which distinguishes it from sibling listing tools like list_reviews and list_templates.

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 when to use this tool (to list notes with optional filters) but does not explicitly state when not to use it or name alternatives. The context is clear enough for an agent to select it for note-listing 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 for behavior. It discloses the non-mutating nature via the verb 'Introspect' and specifies the exact return structure (canonical TemplateActionConfig[] and its fields). While it doesn't explicitly mention authorization or side effects, the introspective verb and detailed output description provide significant behavioral context.

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

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

The description is two concise sentences. The first states the primary purpose; the second lists the return fields and provides a critical usage hint. Every sentence earns its place, and the structure is front-loaded with the core function.

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 (one parameter, no nested objects, no output schema) and the absence of annotations, the description is quite complete. It explains the return shape in detail (the field list) and gives usage context relative to a sibling tool. Minor gaps exist (no explicit statement of read-only, no error or authorization notes), but for an introspection tool, the description covers the essential aspects.

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 review_id with a description ('Review ID (gw_rev_...)'). The description in the tool adds some context by referring to 'a review's template', but doesn't add syntax or additional meaning beyond the schema. With 100% schema coverage, 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 'Introspect' and clearly states the resource ('the configurable actions available on a review's template'). It distinguishes itself from sibling tools by explicitly mentioning its relationship to gatewerk_take_review_action, making its purpose unmistakable.

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

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

The description provides explicit usage guidance: 'Use before gatewerk_take_review_action to choose a valid action_id.' This tells the agent exactly when to invoke it and how it relates to an alternative/aspect of a subsequent tool, satisfying the when-to-use criterion and highlighting a precondition.

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 behavioral burden. It discloses that the tool returns a paginated list, which is useful, but it does not mention default limits, error behavior, or any side effects. Since this is a read-only list operation, the lack of destructive behavior is implied, but not explicitly stated.

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 main purpose. Every word is informative and 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?

Given the tool's simplicity (list with optional filters), the description is mostly complete: it states the action, mentions filters and pagination. The high schema coverage fills in the parameter details, and no output schema exists, so describing the return as a paginated list is sufficient. However, it could briefly enumerate the filter fields for quick reference without relying solely on the schema.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters. The description adds only the generic phrase 'optional filters', which does not add meaning beyond the schema. Baseline 3 is appropriate as the schema does the heavy lifting.

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

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

The description clearly states the tool lists reviews, using the specific verb 'List' and resource 'reviews'. It also mentions optional filters and pagination, which differentiates it from sibling tools like get_review (single item) and list_review_actions (different 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?

The description implies usage for browsing reviews with filters, but it does not explicitly state when to use this tool versus alternatives, nor does it mention any exclusions or prerequisites. It is clear enough for a simple list operation but lacks the explicit guidance seen in high-quality 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, the description carries the burden of behavioral disclosure. It clearly states the tool returns all templates with their fields and actions, implying a read-only operation with no side effects. It does not mention auth or rate limits, but for a simple list operation this is adequate.

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

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

The description is two short sentences, front-loaded with the main action and followed by output details. Every word earns its place, with no unnecessary fluff or 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?

For a simple zero-parameter list tool, the description is complete. It explains what is returned (all templates with fields and actions) and is consistent with the tool's name and siblings. No output schema exists, but the description sufficiently conveys the return value's scope and content.

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 tool has zero parameters, so the schema covers everything. The description adds context about the output (fields and actions), which is useful. The baseline for zero parameters is 4, and the description meets that baseline without needing parameter details.

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 as retrieving review templates, using a specific verb ('Discover') and resource ('review templates'), and explicitly states it returns all templates with their fields and actions. This distinguishes it from sibling tools like list_reviews or list_notes.

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 tool should be used when you need to see available review templates, but it does not explicitly contrast with alternatives or note when not to use it. For a zero-parameter list tool, the intended usage is reasonably clear, but no explicit guidance or exclusions are 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, the description must carry the transparency burden. It does disclose that results are a timestamped log and gives examples of logged actions, but it does not mention read-only behavior, ordering, pagination, or any side effects. This is acceptable 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 a single, front-loaded sentence with no filler. It clearly conveys the core purpose and a couple of illustrative examples without 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?

The tool has 8 optional parameters and no output schema, so the description needs to provide enough context. It states what is returned and the types of actions, but it omits return shape, pagination behavior, and ordering. This is adequate for a simple query tool but leaves 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%, and the schema already provides meaningful descriptions for all 8 parameters, including examples and actor identifier syntax. The description adds no parameter-specific meaning, 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 queries the audit trail and specifies the resource (audit trail) and what it returns (timestamped log of actions). It is distinct from sibling tools, none of which are audit-trail 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?

The description implicitly tells when to use it (when you need the audit trail), but it does not provide explicit when-not-to-use guidance or mention alternatives. No exclusions are stated, so it meets the 'implied usage' level.

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 explicitly describes the return content ('decided reviews with original payload, edits, and feedback') and the action 'Query' implies a read-only operation. It does not discuss pagination or side effects, but for a query tool the provided detail 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 a single sentence, front-loaded with the action and purpose. Every word contributes to understanding the tool, with no redundancy or filler.

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

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

For a read-only query tool with four well-documented optional parameters, the description is functionally complete. It clearly explains what is returned and the learning purpose. The absence of an output schema is mitigated by the description's summary of return contents. It could mention ordering or filter hints, but the schema covers filters.

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 applies. The tool description adds no additional meaning to the parameters themselves; it only mentions the overall return content, which does not elaborate on limit, offset, outcome, or template filters.

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 queries past review decisions and specifies the return contents: original payload, edits, and feedback. This distinguishes it from sibling tools like get_review or query_audit, which have different data scopes.

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 learning' implies an intended use case, but there is no explicit mention of when to use this tool over alternatives or when not to. No sibling tool names are referenced, leaving the guidance implicit 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. While it discloses the return object and a key field (step_1_review_id), it does not explain side effects (e.g., the chain starts executing, reviewers may be notified), asynchronous behavior, validation failures, or idempotency. This is a thin disclosure for a state-changing 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 a single sentence, well-front-loaded with the action and purpose, with no unnecessary words. It covers the essential who, what, and why efficiently, making it easy for an agent 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 is highly complex with nested definitions, but the description gives only minimal context. It mentions the return value but does not explain overall chain execution semantics, error cases, or how to interpret the run object. With no output schema and high complexity, the description leaves significant gaps for an agent unfamiliar with the domain.

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

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

Schema description coverage is 100%, so the schema already documents all parameter meanings and the baseline is 3. The description does not add any parameter details beyond what the schema provides; it only restates that 'definition' and 'initial_payload' are used. Therefore, no additional value is contributed above 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 identifies the action ('Start'), the target resource ('a chain run'), and the required inputs ('definition + initial payload'). It also states the primary return value (step_1_review_id) and its purpose (passing to reviewers), which distinguishes it from sibling tools like get_chain_run or get_chain_for_review.

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 this tool is used (to initiate a chain run and obtain the first review ID) but does not explicitly mention alternatives or when not to use it. It lacks exclusionary guidance, such as pointing to get_chain_run for status checks or get_chain_for_review for reverse lookups, so it only meets the 'implied usage' bar.

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 adds context about built-in vs custom actions and authentication methods, but does not disclose side effects, state changes, reversibility, or permission requirements. This is partial but not comprehensive.

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

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

Four sentences are dense and purposeful, front-loading the core action and then layering usage distinctions, action_id guidance, and auth support. 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?

The description covers selection, alternatives, action ID resolution, and auth. It lacks response format or error behavior, but given the schema richness and sibling context, it is adequately complete for an agent to 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%, but the description enriches action_id by enumerating built-in values and pointing to introspection for custom ones. It also confirms feedback is conditional and version acts as a concurrency guard, 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 clearly states it invokes a configurable action on a review, with a specific verb and resource. It distinguishes from siblings by noting it supersedes gatewerk_decide_review for custom-action templates and lists built-in action IDs.

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

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

It explicitly says when to use this tool (templates with custom actions) and directs to gatewerk_list_review_actions for custom action IDs. It also mentions the alternative (decide_review) is superseded, providing 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states 'Modify' but does not explain whether the operation is a partial update or full replacement, whether unspecified fields are preserved, or what side effects may occur. It also does not mention any validation, permissions, or potential destructive aspects, leaving significant behavioral ambiguity 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 sentence that is direct and waste-free, clearly enumerating the modifiable aspects without unnecessary elaboration. It is appropriately sized for the tool's simplicity.

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 output schema, and no annotations, the description is too brief to be contextually complete. It does not explain how the update behaves (e.g., whether fields replace or append), what the response looks like, or any constraints. The description leaves critical operational details unaddressed, making it inadequate for reliable invocation.

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 only 17% (only template_id has a description), so the description must compensate. It mentions name, fields, actions, and priority, but uses 'priority' while the schema parameter is 'default_priority', and it omits the 'description' parameter entirely. The description adds little semantic value beyond what the schema already shows, failing to clarify the meaning or format of the fields.

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 ('Modify') and the resource ('an existing template'), and enumerates the fields that can be updated (name, fields, actions, or priority). This distinguishes it from sibling tools like gatewerk_create_template and gatewerk_delete_template, 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?

The phrase 'an existing template' implies it is for updates rather than creation, providing some contextual guidance. However, it does not explicitly state when to choose this over alternatives, nor does it mention any prerequisites or exclusions. The usage is implied but not clearly contrasted with sibling update tools.

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