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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds only the source system and an example call; it says nothing about what an alert record contains or what happens if the ID is unknown (error vs empty), which is the remaining behavioral 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?

Front-loaded purpose sentence followed by a short usage block and one example; nothing is redundant. The header/emoji markup and the stray closing </example> tag are minor noise but cost nothing in clarity.

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

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

For a one-parameter read-only getter with 100% schema coverage and declared readOnlyHint, the description plus schema is nearly sufficient. The only missing piece is return-shape information, which has no output schema to carry it.

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 the single parameter is already documented as "The ID of the alert to retrieve." The example (alertId=3Yr) adds a hint about ID format, but otherwise the description defers entirely to the schema – the baseline case.

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

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

States a specific verb and resource ("Retrieve a specific alert by ID") and names the source system, Mackerel. The singular "by ID" implicitly contrasts with the sibling list_alerts, but no sibling is named explicitly.

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

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

The "USE THIS TOOL WHEN USERS: Investigate a particular alert" block gives a clear triggering condition, reinforced by a worked example. It does not, however, tell the agent when to prefer list_alerts or get_alert_logs instead.

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?

readOnlyHint=true already establishes this as a safe read. The description adds useful context that returned logs are status-change history with transition reasons, but says nothing about ordering, pagination semantics, or response shape beyond that. With annotations covering safety, this is a modest but real addition.

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?

Front-loaded purpose sentence followed by short usage bullets and a code example, with no redundant prose. The emoji section header and the 'USE THIS TOOL WHEN USERS' scaffolding are mild padding but do not bury the key line.

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 3-parameter read tool with full schema coverage and a readOnly annotation, the definition covers purpose, triggering conditions, and an invocation example. Only the returned log fields/ordering are left unexplained, which is a minor gap given no output schema exists.

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 limit, nextId, and alertId all documented in the schema itself. The description only restates alertId and shows the ID format via the example (alertId=3Yr); it adds no meaning beyond the structured fields, so baseline 3 applies.

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

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

States a specific verb and resource: retrieve logs for a specific alert by ID from Mackerel. This is clearly distinct from list_alerts (enumeration) and get_alert (the alert object itself), though the description never explicitly contrasts with 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?

Provides explicit when-to-use bullets (view status change history, investigate alert transitions and reasons) plus a concrete call example. Missing any exclusion or pointer to the sibling get_alert for the alert's current state, so the agent must infer the boundary.

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

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

The readOnlyHint annotation already tells the agent this is a safe read operation. The description adds that it retrieves dashboard configuration and widgets, but does not describe permissions, failure behavior, or other operational 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 purpose is front-loaded and the description is reasonably short. The use-case bullets and example are helpful, though some content restates the initial retrieval sentence.

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-only lookup, the definition is complete enough: the operation, ID parameter, and general returned content are clear. It could be improved by noting that list_dashboards can be used to find an unknown dashboard ID.

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 single dashboardId parameter is already documented by the schema. The example shows a sample ID value, but the description does not add significant semantic detail 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 states a specific verb and resource: retrieve a specific dashboard by ID from Mackerel. It is clear what the tool does, though it does not explicitly contrast itself with siblings such as list_dashboards or update_dashboard.

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 'USE THIS TOOL WHEN USERS' section gives clear scenarios for retrieving dashboard details and viewing configuration/widgets. It provides when-to-use guidance but does not explicitly state when not to use it or name alternative 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?

The readOnlyHint annotation already establishes that this is a safe read operation. The description adds useful metric-name categories, but does not disclose return format, time-series granularity, rate limits, or constraints on the time range.

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 definition is front-loaded and organized into purpose, usage, metric names, and examples. It is somewhat lengthy with emoji headings and repetitive examples, but the content is generally purposeful for metric selection.

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 explains how to call the tool and which metric names are available. However, with no output schema, it does not describe the return shape or time-series format, and it omits constraints such as maximum time range or data resolution.

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

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

Schema coverage is 100%, so the schema already documents all four required parameters. The description adds meaningful guidance for the name parameter by enumerating standard, custom, AWS, Azure, and GCP metric naming conventions, plus concrete examples.

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

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

States a specific verb and resource: retrieve metrics data for a specific host from Mackerel. It does not explicitly differentiate from the sibling get_service_metrics, but the host-specific scope makes the purpose clear.

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 'USE THIS TOOL WHEN USERS' section gives a clear context for host metrics and performance analysis, but it largely restates the purpose. It provides no when-not conditions or explicit alternatives such as get_service_metrics.

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?

readOnlyHint=true already tells the agent this is a safe read, so the annotation carries the safety profile. The description adds no extra behavior beyond that: nothing about what happens with an unknown ID, error responses, or what fields the configuration contains. With annotations covering the basics, this is adequate but thin.

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?

Front-loaded with the purpose followed by a usage condition and one compact example. The 'USE THIS TOOL WHEN USERS: Get details of a specific monitor' bullet slightly restates the first sentence, a minor 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 single-parameter read tool with readOnlyHint annotations and no output schema, the description covers the essentials for correct invocation. It could briefly say what the returned configuration includes or how to handle an unknown ID, but nothing critical is missing.

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

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

Schema coverage is 100% for the single monitorId parameter, so the baseline is 3. The example value ('2cSZzK3XfmB') usefully illustrates the ID format, but no additional semantics (scope, permissions, whether the ID is the display ID) are added 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?

States a specific verb and resource ('Retrieve a specific monitor configuration by ID from Mackerel'), so an agent can distinguish it from the sibling list_monitors. It stops short of explicitly naming the list vs. get distinction, but the scope is unambiguous.

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

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

The 'USE THIS TOOL WHEN USERS' block gives clear context ('Get details of a specific monitor') and a concrete example call. It lacks an explicit exclusion or an alternative reference (e.g., use list_monitors to enumerate), so it falls short of the 5 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?

readOnlyHint=true already tells the agent this is a safe read, so the description's main job is to add beyond that. It clarifies the metric namespace and gives concrete call examples, but says nothing about pagination, rate limits, or the shape of returned series 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?

Front-loaded with purpose and usage guidance, and the examples are genuinely useful for the tricky metric-name format. The emoji-headed bullet lists add some visual bulk but each section 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 query tool with no output schema, the description supplies what the agent needs to pick it and form a valid metric name. Only the return-format and empty-result behavior remain unspecified, which is a minor gap given the annotations.

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

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

Schema coverage is 100%, so all four parameters are already documented and the 'name' param already carries the same example metric names. The description reinforces the metric-name formats and shows them in context, but does not add syntax or format meaning beyond the schema, so baseline 3 applies.

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

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

States a specific verb+resource ('Retrieve metrics data for a specific service') and disambiguates from the sibling get_host_metrics by explaining that service metrics aggregate multiple hosts and their collective roles. An agent can distinguish this tool's scope without opening 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 explicit 'USE THIS TOOL WHEN USERS' block and the definition of what a service metric is provide clear context for selection. However, it never names alternatives such as get_host_metrics or list_http_server_stats, so exclusions are left to inference.

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 only declare readOnlyHint=true, so the description carries the rest and does add value: pagination via limit/offset, default page size of 20 with a max of 100, and the rationale that includeAttributes defaults false to reduce response size while includeEvents defaults true because events carry error information. It doesn't describe the shape of the returned spans, which would round it out.

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 lead sentence and USE-WHEN block are well front-loaded, but seven examples is more than needed: the 'combined filtering and pagination' example merely recombines behaviors already demonstrated separately, and every example repeats the same placeholder traceId, adding length without new 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?

With no output schema, the description should say what comes back; it implies pages of spans and mentions events/attributes but never sketches the span record or whether total counts are returned. Everything needed to invoke correctly is present, so the gap is modest rather than disqualifying.

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

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

Schema coverage is 100%, so the baseline is 3, but the examples add real semantic guidance the schema lacks: duration is expressed in milliseconds and compared as a floor (duration=100 = spans over 100ms), and errorSpansOnly combined with limit/offset is shown for paged error triage.

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

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

States a specific verb+resource ('Retrieve trace data by trace ID from Mackerel') and the analysis domain (distributed tracing), which cleanly separates it from the list_traces sibling that returns collections rather than a single trace.

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 'USE THIS TOOL WHEN USERS' block gives five concrete scenarios (bottleneck analysis, error propagation, request flow, latency debugging, architecture docs) plus worked examples. It never names the alternative for enumerating traces (list_traces) or states when NOT to use this tool, 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?

readOnlyHint=true already establishes this is a safe read, so the description's job is to add context beyond that. It mentions closed vs. open alerts, but says nothing about result ordering, default page size, or how nextId continues a paged read — the mechanics an agent needs for repeat calls.

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 purpose sentence and use-when bullets are front-loaded and scannable, and the examples are compact. Slight redundancy between the 'including closed alerts' bullet and the withClosed example, but nothing wasteful.

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

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

For a read-only list tool with no output schema and fully documented parameters, the description covers what to call it for and how to toggle closed alerts. Pagination behavior via nextId is the one gap, though the schema carries it.

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 all three parameters are already documented. The example list_alerts(withClosed=true) usefully demonstrates that the default excludes resolved alerts, but limit and nextId semantics are left entirely to the schema. Baseline 3 applies.

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

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

States a specific verb and resource — 'Retrieve alerts from Mackerel' — and the bullets make clear it returns alert collections rather than a single alert. It does not explicitly contrast with siblings like get_alert or get_alert_logs, which an agent could confuse with 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 'USE THIS TOOL WHEN USERS' block gives concrete trigger conditions (active alerts, including closed alerts) and the examples show both default and withClosed invocations. There is no explicit when-not guidance or named alternative for single-alert lookups.

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?

readOnlyHint=true already establishes the safe-read profile, so the description's main added value is the retrieval scope. It says nothing about pagination limits or that the response is truncated by default, which matters for a tool claiming to return "all" dashboards.

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?

Purpose and trigger conditions are front-loaded in two short blocks, with no filler prose. The <examples> block is largely redundant for a zero-required-parameter call, adding length without new 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?

With no output schema, the description should carry more: it names the returned fields (ID, title) but omits pagination behavior and the fact that widget details are stripped by default, both of which affect whether "all dashboards" is actually returned.

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 limit, offset, and summary are fully documented in the schema with defaults. The description adds no syntax, range, or usage nuance beyond the schema — the only weak hint is "ID and title," which gestures at summary=true. Baseline 3 applies.

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

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

States a specific verb and resource ("Retrieve all dashboards from Mackerel") and the user goal it serves ("Get ID and title of each dashboard"). It doesn't explicitly contrast with the sibling get_dashboard, but list-vs-get is self-evident from the naming.

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 "USE THIS TOOL WHEN USERS" block gives concrete triggering conditions (listing dashboards, needing IDs and titles), which an agent can match intent against. No when-not-to-use guidance or named alternatives (e.g., get_dashboard for a single dashboard) is provided.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds usage scenarios but omits notable behavior: the 30-minute from/to range constraint (only in schema), default sort column P95, and the shape of returned statistics. Useful but not rich 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?

Purpose statement and usage bullets are front-loaded and easy to scan. The four examples are somewhat verbose for a CRUD-list tool, but each demonstrates a distinct parameter combination, so little is pure 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?

With 11 parameters, no output schema, and no description of what the returned statistics contain (latency aggregates, query text, counts), the definition leaves the return payload undocumented. When/how is covered, but an agent cannot anticipate the response shape.

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

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

Schema description coverage is 100%, so every parameter including enums (orderColumn, orderDirection) and defaults is already documented. The examples illustrate a few parameter combinations (pagination, filtering) but add no semantics beyond the schema; baseline 3 applies.

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

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

States a specific verb and resource ('Retrieve database query statistics from Mackerel'), which is unambiguous. It does not differentiate itself from siblings like list_http_server_stats or list_traces, so an agent must infer that this covers DB query stats specifically.

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 'USE THIS TOOL WHEN USERS' bullets give clear usage contexts (slow queries, high-frequency queries, performance investigation). However, no exclusion criteria or named alternatives are given, so when-not-to-use is left 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?

Annotations already establish readOnlyHint=true, so the safety profile is covered. The description adds genuine operational context beyond that: default page size of 20, how to page forward with offset, and a summary mode to shrink response size. However, the summary parameter appears only in examples and not in the schema, so the behavioral promise is not fully backed by a structured field.

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 purpose and usage triggers are front-loaded before the examples, so an agent gets the essentials immediately. The example block is somewhat padded — two of the five examples both demonstrate pagination and one relies on an undocumented parameter — but no sentence is purely 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 list tool with all 7 optional parameters fully documented, the description covers selection, filtering, pagination, and response-size control. With no output schema, it could say more about what a host record contains, but that gap is minor for an enumeration endpoint.

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 every one of the 7 parameters is already documented, and the baseline is 3. The examples do show realistic combinations of service, role, status, limit, and offset, which adds modest value, but they also demonstrate list_hosts(summary=true) for a parameter absent from the input schema, potentially misleading an agent into an invalid call.

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 and resource ("Retrieve hosts from Mackerel") and enumerates concrete capabilities: listing, filtering by service/role/name, and status checks. It doesn't explicitly distinguish itself from siblings like list_services or get_host_metrics, but the resource boundary is obvious from the name and text.

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 "USE THIS TOOL WHEN USERS" block plus five worked examples make the intended invocation contexts very clear, including filter combinations and pagination. It stops short of naming an alternative tool (e.g., pointing to get_host_metrics when the user wants metrics rather than host records), which keeps it below 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?

readOnlyHint=true already tells the agent this is a safe read, so the description only needs to add context. It omits the most operationally important constraint, the 30-minute maximum time range, which lives only in the schema, and says nothing about pagination behavior or result ordering semantics beyond example arguments.

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?

Purpose and use cases are front-loaded correctly, but the four examples repeat the same serviceName/from/to boilerplate and spend significant space restating what the schema already declares. A single example plus prose about pagination and sorting would be tighter.

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 12-parameter, no-output-schema tool that returns statistics, the description should at least indicate the shape of the returned metrics (latency, error rate, request counts) and reinforce the time-window and sort defaults. The sketch of use cases plus examples is adequate to invoke it, but leaves genuine 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%, so every parameter, enum, and the 30-minute limit is already documented in structured fields. The examples do show useful parameter combinations (environment+version, method+route, page+perPage), but they add no semantics the schema lacks, which is the expected baseline-3 case.

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

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

States a specific verb and resource ('Retrieve HTTP server statistics from Mackerel'), so the agent knows exactly what data comes back. It does not distinguish itself from conceptually adjacent siblings such as list_db_query_stats or get_service_metrics.

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 bulleted 'USE THIS TOOL WHEN USERS' list gives clear analytical scenarios (slow endpoints, high-traffic routes, error rates, API performance). It never names an alternative tool or states when not to use this one, so routing against siblings is left 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds that this retrieves all monitor configurations from Mackerel, but it does not disclose pagination behavior, return shape, authentication needs, or rate limits. For a simple read-only list tool this is adequate, but it goes only modestly beyond the annotation.

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 core sentence is front-loaded and clear, but the use-case bullets largely restate the purpose, and the example adds little value for a zero-parameter tool. It is not bloated, but some content does not earn 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?

This is a simple zero-parameter read-only list operation with an annotation covering safety. The description is sufficient for an agent to invoke it correctly, though it omits pagination and return-format details that could matter for a list endpoint.

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 there are no parameter semantics to explain. The empty schema is fully self-describing, and the description does not need to compensate for undocumented parameters.

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

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

The description clearly states a specific verb and resource: retrieve all monitor configurations from Mackerel. It implies a list-all operation, which helps distinguish it from the singular get_monitor sibling, though it does not explicitly name that sibling or contrast the two.

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 'USE THIS TOOL WHEN USERS' section gives clear use cases: getting a list of all monitors and viewing monitor configurations. It does not provide exclusions or explicitly route users to get_monitor for a single monitor, so it lacks full when-not/alternatives 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?

The readOnlyHint annotation already establishes that this is a safe read operation. The description adds useful output context by naming service names, memos, and roles, but it does not mention pagination, ordering, account scoping, or other operational behavior. With annotations covering safety, this is adequate 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 purpose is front-loaded and the usage bullets are easy to scan. The example block for a zero-argument call is somewhat redundant, but it does not create meaningful bloat.

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 parameterless read-only list tool with no output schema, the description provides enough to call it correctly: what it retrieves and when to use it. It could be stronger with account-scope or pagination details, but the core 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?

There are zero parameters, so parameter semantics are not applicable and the baseline is 4. The description does not need to explain any input arguments.

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 and resource: retrieve all services, and clarifies the fields shown (names, memos, roles). It is clear against most siblings by resource, though it does not explicitly name alternatives such as get_service_metrics or list_hosts.

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 'USE THIS TOOL WHEN USERS' section gives concrete triggering scenarios: getting a service list and viewing service names, memos, and roles. It lacks explicit when-not-to-use guidance or named alternatives, but the context is clear.

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

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

The readOnlyHint annotation already establishes that this is a safe read operation. The description adds useful context about distributed tracing analysis and demonstrates filtering and pagination, but it does not disclose return shape, result limits, permissions, or pagination metadata beyond the examples.

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

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

The description is front-loaded with purpose and usage guidance, then provides examples that are useful for a complex 16-parameter tool. The examples are somewhat repetitive, repeating serviceName, from, and to in every block, but the structure remains clear and the content generally 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 the rich input schema, read-only annotation, and absence of an output schema, the description covers the main usage contexts and demonstrates key filters and pagination. It is sufficient for common invocation, though it could better explain what traces are returned and when to use get_trace instead.

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 all 16 parameters and nested attribute filters are already documented in the schema. The examples demonstrate common parameter combinations, but they do not add much semantic 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?

States a specific verb and resource: search and retrieve traces from Mackerel for distributed tracing analysis. It is clear what the tool does, but it does not explicitly distinguish itself from the sibling get_trace tool or clarify list/search vs single-trace retrieval.

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 'USE THIS TOOL WHEN USERS' list gives concrete usage contexts: time-range search, latency filtering, service/environment/version filtering, and distributed system investigation. It does not state when not to use it or name get_trace as the alternative for single-trace lookup.

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?

Despite readOnlyHint already declaring the safety profile, the description discloses a lot beyond annotations: a documented 1 request/second rate limit, default returned fields, body truncation with a bodyTruncated marker, and that the response echoes the actual timeRange searched. The cursor contract — that it carries time range and sort order so from/to/order are ignored and filters must stay fixed — is exactly the kind of non-obvious behavior an agent cannot get from the schema alone.

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?

Purpose is front-loaded, the use-case and response-size sections are scannable, and nothing is padded with filler. Seven worked examples for a 14-parameter tool with nested objects is defensible, though a couple (e.g. the plain keyword and time-range cases) partially duplicate the schema descriptions.

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 14-parameter read tool with nested bodyAttributes and no output schema, the description supplies the missing return-side information — default field set, truncation behavior, and the pagination.nextPageCursor/previousPageCursor contract — so an agent can both call and paginate it correctly without further 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 coverage is 100%, so 3 is the floor, but the description adds real semantics on top: serviceNamespace omission silently narrows the search to namespace-less services, from/to omission falls back to lookbackMinutes, and pageCursor must be passed through as-is. The examples also demonstrate non-obvious parameter shapes like bodyAttributes keyPath/operator combinations.

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

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

States a specific verb and resource ('Search logs of a service from Mackerel') and enumerates three concrete investigative use cases. It never differentiates itself from sibling tools that also surface logs or traces (get_alert_logs, get_trace, list_traces), so an agent deciding between those must infer the boundary.

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 'USE THIS TOOL WHEN USERS' block gives clear triggering contexts (error investigation, trace lookup, keyword/structured-body matching), and the response-size section establishes a recommended filter ordering. There is no explicit when-not-to-use guidance and no sibling named as an alternative, which keeps it 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?

No annotations are supplied, so the description carries the full behavioral burden for a destructive mutation. It never says whether this is a full replacement (all five params are required, strongly implying widgets not resubmitted are lost), what happens to an invalid dashboardId, what permissions are needed, or what is returned. The example illustrates payload shape but discloses nothing about side effects.

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

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

The core action is front-loaded in one sentence, followed by tightly scoped bullets and a single illustrative call. The example earns its place by showing a markdown widget inside the widgets array, though it also carries the minor cost of not illustrating any of the other widget types.

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 on a complex nested schema with no annotations and no output schema, an agent still has to guess replacement semantics, failure modes and return value. The description is sufficient to construct a call but leaves gaps that matter for a destructive update.

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 nested widget, graph, layout and range structures are already documented in structured data; baseline 3 applies. The worked example slightly reinforces the widget shape but adds no semantics about required-or-not fields or defaults beyond what the schema states.

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

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

States a specific verb (update) and resource (dashboard identified by ID) within a named product. The use-when bullets narrow it to title/memo/urlPath and widget configuration, which cleanly separates it from the read-only siblings get_dashboard and list_dashboards.

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?

Two explicit 'USE THIS TOOL WHEN USERS' conditions give clear context for invocation. There are no exclusions or named alternatives (e.g. 'to create or delete a dashboard use X', 'call get_dashboard first to retrieve existing widgets'), so the routing guidance is directional but incomplete.

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