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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the description does not need to restate safety. The description adds that the tool returns schema, safety category, and executor, but this is more about output content than behavioral traits. No contradiction exists between description and 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?

A single, tightly worded sentence with no filler or redundancy. The key outcome is front-loaded, and 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?

For a simple one-parameter metadata lookup, the description plus annotations cover the essential context: it is a safe, read-only, idempotent operation returning specific details. The description does not explicitly say the action will not be executed, but the readOnlyHint and the focus on metadata make that clear.

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

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

Schema description coverage is 0%, and the schema only says action_id is a non-empty string. The description compensates by explaining that action_id identifies 'one discovered Surfmeter action,' which adds meaning beyond the raw parameter name and type. It does not specify format or source, but for a single opaque identifier this is sufficient.

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 names a specific verb ('Get'), a clear resource (one discovered Surfmeter action), and the exact information returned: schema, safety category, and required executor. This clearly distinguishes it from siblings like search_actions (discovery) and execute_* tools (execution).

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 'one discovered Surfmeter action' establishes that this tool is for actions already found, implying a workflow of discover-then-describe-before-execute. It does not explicitly name alternatives or exclusions, but the intended usage context is clear from the wording.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the destructive nature is covered. The description adds the crucial confirmation requirement and specifies the source of the action, going beyond what annotations state. No contradictions with annotations.

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

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

A single, front-loaded sentence with zero redundancy. It states the purpose, the source, and the critical warning efficiently. Perfectly concise for the information conveyed.

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 there is no output schema and a nested params object, the description lacks essential context: what to put in params, how to identify the correct action_id, and what the return value looks like. The warning to confirm targets is good, but the lack of parameter explanation makes the tool incomplete for correct 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 0%, so the description must explain the parameters. It only implies action_id comes from search_actions but does not clarify its format or the purpose of the params object (nested, with arbitrary properties). This leaves the agent guessing about how to fill params and what action_id looks like.

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

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

The description clearly states a specific verb ('execute') and resource ('destructive Surfmeter action') and explicitly ties the action to surfmeter_search_actions, distinguishing it from read/write sibling tools. It's unambiguous about what the tool does.

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

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

It gives clear guidance to confirm targets and consequences before execution, which is essential for a destructive action. It also indicates the action must come from surfmeter_search_actions, implying the correct prior step. It doesn't explicitly list alternatives, but the 'destructive' qualifier and sibling names make the intended use obvious.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the description's read-only framing adds little safety information beyond structured data. It does add a useful provenance constraint: the action must come from surfmeter_search_actions, which is the main behavioral value.

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 with no filler. It front-loads the core purpose and usefully names the source tool without wasting words.

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

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

For an execute tool with an unrestricted params object, no output schema, and no parameter documentation, this description is too thin. An agent does not know how to construct params, whether to call surfmeter_describe_action first, or what the response will contain. The pipeline hint helps but leaves essential execution details unspecified.

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 0%, so the description must compensate, but it only gives indirect context for action_id by mentioning the action comes from a search. It does not explain the required action_id format or the params object semantics, which are entirely unconstrained in the schema.

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

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

The description states a specific verb ('Execute') and resource ('read-only Surfmeter action'), and explicitly ties the action to the output of surfmeter_search_actions. This clearly differentiates it from the write and destructive execution 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 phrase 'returned by surfmeter_search_actions' provides clear usage context and implies this tool should be called after a search. It does not explicitly state exclusions or alternatives, but the read-only qualifier plus sibling names make the intended scope reasonably clear.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false. The description adds the 'non-destructive' qualifier, which aligns with destructiveHint=false and adds context that this is a mutation but not destructive. However, it doesn't disclose what the mutation does, what side effects occur, or what the response contains. The description doesn't contradict annotations, but it doesn't add much beyond them.

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

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

The description is a single sentence that is concise and front-loads the key information: it executes a mutation, it is non-destructive, and it comes from surfmeter_search_actions. It earns its place, though it could add a bit more detail without becoming bloated.

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

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

For a mutation tool with no output schema, no parameter documentation, and annotations that only cover safety hints, the description is too thin. An agent needs to know what action_id refers to, what params should contain, and what the result of executing a mutation looks like. The reference to surfmeter_search_actions helps but doesn't fully compensate.

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 0%, so the description must compensate for the two parameters. It only mentions action_id implicitly by saying 'mutation returned by surfmeter_search_actions', but it doesn't explain that action_id is the identifier of that mutation, nor does it explain the purpose of the 'params' object. The description adds almost no parameter-level 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 states a specific verb ('Execute') and resource ('non-destructive Surfmeter mutation'), and references the sibling tool surfmeter_search_actions as the source of the mutation. It clearly distinguishes itself from surfmeter_execute_read_action and surfmeter_execute_destructive_action by the 'non-destructive' qualifier, though it doesn't explicitly name those siblings.

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

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

The description says the mutation must be 'returned by surfmeter_search_actions', which gives a clear prerequisite and workflow context. It doesn't explicitly state when not to use it or name alternatives, but the 'non-destructive' qualifier and the sibling set make the usage context reasonably clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: it returns a bounded page, includes total and next_offset pagination metadata, and only shows 'visible' clients. This goes beyond the annotations and helps the agent understand response shape and scoping.

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

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

Two sentences, no filler. The primary behavior (get by id or list) is front-loaded, and the pagination metadata note is a valuable addition. 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 read-only list/get tool with strong annotations and a clear description, this is nearly complete. The only minor gap is that it doesn't explicitly state what 'visible' means (e.g., permission-scoped clients), but that is a domain nuance rather than a critical omission. No output schema exists, so the description's mention of total and next_offset is helpful.

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 33% (only 'id' has a description). The description clarifies that 'id' is optional and switches between single-get and list mode, and that limit/offset control pagination. However, it doesn't add detail about limit bounds or offset semantics beyond what the schema already provides. Baseline 3 is appropriate because the description partially compensates for the low schema coverage.

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

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

The description clearly states a specific verb ('Get') and resource ('Surfmeter client'), and explicitly distinguishes the two modes: single client by id vs. bounded page of visible clients. It also mentions pagination metadata, which helps differentiate it from sibling search tools like surfmeter_search_anomalies or surfmeter_search_measurements.

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 this tool: supply an id for a single client, or omit it to list a page. It does not explicitly name alternatives or exclusions, but the sibling list makes the distinction clear enough. A small gap is that it doesn't say when to prefer surfmeter_search_* tools over this one.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds no additional behavioral traits beyond 'Read', which aligns with annotations. It does not describe response format or pagination, but annotations cover the safety aspects, so a 3 is appropriate.

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 front-loads the verb 'Read' and lists the resources. It is appropriately sized and efficient, though it could benefit from a more structured breakdown of resource options. Overall, it is concise and well-organized.

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

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

Given the tool's complexity with 9 parameters and multiple resource types, the description is incomplete. It lacks guidance on parameter combinations, expected responses, and how to filter results. The absence of an output schema increases the need for description clarity, which is not met. An agent would struggle to construct correct calls without additional context.

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

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

Schema description coverage is 0%, so the description must compensate. It does not explain any of the 9 parameters, including the required 'resource' field or the optional filters like limit, offset, state, and extended. The enum for resource is helpful but not elaborated. The description's list of resources implies the resource parameter but does not connect parameters to behavior, leaving agents to infer semantics.

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

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

The description clearly identifies this as a read operation ('Read') and lists the specific data categories (server metadata, license usage, fleet health, etc.). It distinguishes from sibling tools like surfmeter_search_* and surfmeter_update_client, which serve different purposes. However, it does not explicitly mention the required 'resource' parameter, leaving some ambiguity about how to select among the listed options.

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 provide explicit guidance on when to use this tool vs alternatives. While it is obviously the tool for reading system status, there is no mention of alternatives or conditions that would route an agent away from it. The resource enum in the schema offers some context, but the description itself lacks routing information.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful context about what is returned (action IDs, safety categories, executors, parameter names) but does not disclose behaviors such as how results are ordered, whether queries are fuzzy/exact, or any limits beyond the schema.

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

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

Two sentences with no filler. The primary purpose is front-loaded, the return payload is summarized, and the pointer to describe_action is a single useful clause. Every word contributes.

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 search tool with no output schema, the description covers the main inputs by intent, lists return fields, and provides a natural next step. It could be slightly stronger by explaining the category enum or how to use the returned action IDs, but it is largely sufficient for an agent to invoke it correctly.

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

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

Schema description coverage is 0%, so the description must compensate for documenting the parameters. It vaguely implies 'query' is an intent expression and mentions 'parameter names' as an output, but it fails to explain the meaning of 'query', 'category', or 'limit' beyond what the raw schema already shows. This leaves a significant semantic gap.

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 ('Find'), identifies the resource ('less-common Surfmeter operations'), and states the search is by intent. It also lists the concrete outputs (action IDs, safety categories, executors, parameter names) and clearly separates itself from surfmeter_describe_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 gives clear context for when to use the tool: searching for less-common operations by intent. It also explicitly routes the agent to surfmeter_describe_action for exact schemas. It does not, however, distinguish this from other search siblings like surfmeter_search_anomalies or surfmeter_search_measurements, or state when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds that the operation can aggregate results via Elasticsearch Query DSL, which is useful, but it does not disclose pagination behavior, result shape, or other operational caveats.

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 with the core purpose in the first sentence. The second sentence is a useful practical tip, though it partially duplicates the body parameter description in the schema. Overall, there is no wasteful 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?

With no output schema and five parameters, the description is too sparse. It does not explain how from, size, search_after, or source_only shape behavior, nor does it describe the return structure. An agent would need external Elasticsearch knowledge to use the tool confidently.

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

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

Only one of five parameters (body) has any description, and the tool description mostly repeats the schema's body description by mentioning .keyword. The from, size, source_only, and search_after parameters are left undocumented in both the schema and the description, and the low 20% coverage is not compensated.

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 names a specific verb ('Search and aggregate') and a distinct resource ('anomaly episode documents'), which clearly sets it apart from siblings like surfmeter_search_measurements and surfmeter_search_actions. An agent can identify when this tool is relevant without needing to inspect schemas.

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

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

The description implies this tool is for anomaly episode documents, and offers a concrete tip about using .keyword for exact text fields. However, it does not explicitly state when to prefer this tool over sibling search tools, nor does it mention any alternative 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?

Annotations include readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, which already signal a safe, read-only, open-world operation. The description adds guidance on server-side filtering and .keyword usage, which is useful but not deeply behavioral. It doesn't disclose aspects like performance implications, use of scroll for large result sets, or how it handles indexing.

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

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

The description is only two sentences, front-loaded with the primary purpose and then key usage tips. Every word adds value, and it avoids redundancy with the schema. The structure is clear and 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?

Given the tool's complexity (Elasticsearch DSL) and a moderate parameter count (7), the description covers the core usage pattern (server-side filtering, .keyword) but is missing details like examples of common queries, explanation of scroll for large results, or how 'index_scope' restricts the family. However, the schema provides some descriptions for several params, partially compensating. The lack of output schema is acceptable as the description needn't explain returns.

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 43%, so the description must compensate for the 4 parameters potentially lacking schema descriptions. The description adds semantic guidance on the 'body' parameter (prefer object, use .keyword) which goes beyond the schema. It could detail the 'from'/'size' pagination semantics, but the .keyword hint is significant.

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 is for searching and aggregating measurement documents using Elasticsearch Query DSL. It specifies the primary resource (measurement documents) and the action (search and aggregate). However, it doesn't explicitly distinguish from siblings like surfmeter_search_anomalies or surfmeter_search_actions, though the resource type is implied.

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 guidance on how to use the tool: prefer server-side filters/aggregations and use .keyword for exact text matching. It implies usage context for Elasticsearch querying but does not explicitly contrast with sibling tools or state when NOT to use this tool versus 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?

Annotations already indicate a non-read-only, non-destructive, non-idempotent operation. The description adds the ownership constraint (shared clients are read-only) and the list of updatable fields, but doesn't disclose side effects, permission requirements, or response behavior. It adds some context beyond annotations but not rich 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 concise sentences, front-loaded with the action and resource, followed by the ownership constraint. Every word earns its place 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 covers the core purpose and the critical ownership constraint, but lacks details on response format, error handling, parameter semantics, and potential side effects. For a write tool with 5 parameters and no output schema, more context would be beneficial, though the annotations and sibling context partially fill 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 only 20% (only 'id' has a description). The description mentions 'labels, tags, or client-group assignments' but doesn't map these explicitly to the schema's 'tags', 'label', 'extra_label', and 'client_group_ids', nor explain their meaning or format. It provides only a high-level field list, insufficient to compensate for the low schema coverage.

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

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

The description clearly states the tool updates an owned client's labels, tags, or client-group assignments, providing a specific verb and resource. It distinguishes from sibling read/search tools by explicitly framing this as an update operation, and the ownership constraint further differentiates it.

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

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

The description gives a clear usage condition: only owned clients can be updated, and shared clients are read-only. This implicitly tells the agent when to use this tool, though it doesn't explicitly name alternative tools or state when NOT to use it beyond the shared-client restriction.

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