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

The description adds behavioral context beyond annotations: it advertises 'fast, no raw data transfer' and clarifies how setting interval changes the return shape to 'a timeseries per group instead of a single scalar per group'. This is useful information not present in the readOnly/idempotent hints.

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 tight and well-structured: the first sentence defines the tool, the second paragraph highlights use cases, and the bullet list provides concrete examples. Every sentence earns its place with no fluff.

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

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

Given the tool's complexity (9 parameters, aggregation modes) and the presence of a full input schema plus an output schema, the description provides sufficient context. It explains the core aggregation behavior, interval option, and performance characteristics, making it easy for an agent to select and invoke correctly.

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

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

The input schema already provides 100% coverage for all parameters, so the baseline is 3. The description does reinforce the interval behavior and gives an example with metric and interval, but it does not add new information beyond what the schema already 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?

The description clearly states the tool's function: 'Aggregate and group logs by a field with statistics', with a specific verb, resource, and scope. It distinguishes itself from siblings like search_logs by mentioning 'no raw data transfer' and from simple count tools by focusing on grouped statistics.

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 states 'PERFECT for analytics, charts, and dashboards' and provides concrete use cases via 'Use this when:' with example queries. It also notes that interval handles timeseries without a separate tool. However, it does not explicitly name alternatives or state when not to use the tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context: 'no raw span data transfer' clarifies it performs server-side aggregation without returning raw data, which is a key behavioral trait beyond the annotation safety profile.

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 well-structured and front-loaded: first sentence delivers the core purpose, second explains the key advantage, and the bullet list gives concrete use cases. Every sentence earns its place; no fluff or redundancy.

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

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

Given the tool's complexity (7 params, 4 required), the presence of an output schema, and comprehensive annotations, the description fully covers purpose, usage, behavioral nuance, and relevant alternatives. It leaves no critical gaps for an agent to resolve independently.

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?

Input schema covering all 7 parameters with descriptions gives a baseline of 3. The description's examples implicitly reference group_by and aggregation (e.g., 'p95 latency by service') but add no new parameter-level meaning beyond the schema, so no higher score is warranted.

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 'Aggregate spans by a field for latency/error statistics' and explicitly notes it does not transfer raw span data. It distinguishes itself from the sibling tool search_apm_traces by contrasting aggregation vs. raw span fetching.

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 guidance with concrete example queries ('p95 latency by service', 'Error count by endpoint'), and names the alternative search_apm_traces while highlighting the cost trade-off of fetching raw spans. The 'Use this when' bullet list makes context crystal 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, destructiveHint=false, and idempotentHint=true. The description adds valuable behavioral context by stating it counts 'WITHOUT fetching all data' and is 'fast & lightweight,' which goes beyond the annotations. It does not mention rate limits or exact count semantics, but that is not critical here.

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, front-loaded with the core purpose, and uses bullet points for use cases. Every sentence adds value, with no wasted words.

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

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

Given the simple 4-parameter schema, the presence of an output schema, and full annotation coverage, the description provides enough context. It explains the tool's advantage over search_logs, typical use cases, and that it returns a count rather than log 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?

Schema description coverage is 100%, and each parameter (query, indexes, from_time, to_time) has a clear description in the schema. The tool description itself does not add parameter-level detail beyond what the schema already provides, so it meets the baseline but does not exceed it.

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 counts logs matching a query without fetching all data, using a specific verb and resource. It explicitly distinguishes itself from search_logs, which is a sibling tool, by emphasizing it is for counting rather than retrieving content.

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

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

Provides explicit guidance on when to use this tool, including specific use cases like "How many errors happened?" and "Count logs for a service." It also gives a clear exclusion: search_logs should never be used just to count results, making the alternative 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds a behavioral claim about efficiency ('Much more efficient than fetching all logs with search_logs'), which is useful context beyond the annotations. It does not contradict any 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 description is compact and front-loaded: the core definition appears in the first line, followed by concise use-case bullets. Every sentence contributes to understanding, with no redundant text.

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 full schema coverage, annotations, and an existing output schema, the description fully covers purpose, usage, and the main alternative. It is sufficient for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100%, so the parameters are fully documented. The description reinforces the role of 'field' by giving examples ('@session_id', '@user.id') but adds no new syntax or format details. 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 opens with a specific and unambiguous definition: 'Count UNIQUE values of a field (distinct count / cardinality).' This clearly identifies the operation and resource. It also differentiates from sibling tools like search_logs by positioning itself as the efficient option for cardinality queries.

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 an explicit 'Use this when:' section with concrete question patterns (e.g., 'How many unique users/sessions?', 'Count distinct values'). It also names search_logs as the alternative to avoid, making the choice between tools 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 convey that this is a write operation (readOnlyHint=false) with side effects (openWorldHint=true). The description adds the suggestion to validate first, implying the tool may not fully validate query syntax, but it does not disclose additional behavioral details such as whether creation is immediate or if there are any 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 compact and well-structured: a clear opening sentence, a 'Use this when' section, and three bulleted examples. Every sentence earns its place, 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 the tool's complexity (7 parameters) and the presence of an output schema, the description covers the essential aspects: what it does, when to use it, and how to structure queries. It does not explain return values, but the output schema handles that. Minor gaps like authentication or rate limits are not addressed, but these are less critical for a creation 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 description coverage is 100%, but the description adds meaningful query examples for metric, log, and APM formats that go beyond the schema's generic reference to 'examples above'. This practical guidance helps agents construct valid queries, raising the value above the baseline of 3.

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 'Create' and the resource 'monitor', and specifies the types of data it alerts on (metrics, logs, APM). It also distinguishes itself from the sibling validate_monitor by suggesting validation first.

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?

Explicit 'Use this when' scenarios are given (get notified, set up alerting, monitor SLAs), and validate_monitor is named as an alternative to check query syntax first. However, it does not explicitly state when to use update_alert_monitor or silence_monitor instead, so it falls slightly short of a perfect score.

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 annotations already indicating readOnlyHint=false and idempotentHint=false, the description adds context by explaining the two layout types ('ordered' and 'free') and pointing to the datadog://widget-templates resource for widget definitions. This goes beyond what annotations provide, though it doesn't elaborate on side effects or error handling, which are partially covered by the presence of an output 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?

The description is compact and well-structured: a single opening sentence, a usage condition, a resource pointer, and two bullet points for layout types. Every sentence adds value, and the key information is front-loaded.

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

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

Given the tool's complexity (7 parameters, 3 required), the description covers the essential context: when to use it, how to structure layouts, and where to find widget templates. The remaining parameters are fully described in the schema, so no further description is needed. The presence of an output schema also covers return-value expectations.

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 describes every parameter. The tool description adds extra meaning for layout_type by explaining what 'ordered' and 'free' mean, and for widgets by referencing a resource with ready-to-use definitions. This is valuable enrichment 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 opens with 'Create a new dashboard with custom widgets and layout,' which uses a specific verb and resource, clearly distinguishing it from sibling tools like update_existing_dashboard, get_dashboard_details, and list_all_dashboards. The mention of 'custom widgets and layout' further clarifies its scope.

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

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

The description explicitly states 'Use this when: user wants to visualize metrics, create a monitoring view, or track KPIs,' providing clear context for when the tool is appropriate. It does not explicitly mention exclusions or contrast with alternatives like update_existing_dashboard, but the use-case guidance is strong enough to guide selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds useful context by noting it 'Consolidates metric metadata and tag discovery into a single call,' which explains the tool's scoped behavior. No contradictions found.

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

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

The description is three sentences, front-loaded with the primary purpose, and every sentence earns its place. No filler or redundancy.

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

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

With a single simple parameter, comprehensive annotations, and an output schema present, the description provides sufficient context. It explains the returned content (metadata and known tags) and the intended usage scenario without needing to describe return formatting.

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 description for metric_name gives concrete examples and source tools (list_available_metrics or list_active_metrics). The tool description itself adds no extra parameter semantics, 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 and resource: 'Get metadata (description, unit, type) and known tags for a metric.' It clearly distinguishes from siblings by framing the tool as a consolidation of metadata and tag discovery, which is different from list_available_metrics or query_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?

Provides explicit when-to-use guidance: 'Use this when: you need to understand what a metric means or what tags you can group/filter by before writing a query_metrics or monitor query.' It does not explicitly say when not to use or name alternatives, but the intended 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?

Annotations already mark this as read-only and idempotent. The description adds valuable behavioral nuance by disclosing truncation behavior for large dashboards, referencing fields like 'truncated', 'warning', and 'total_available'. This goes beyond the annotations and helps set expectations about response 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 primary purpose, and the second sentence adds a concise usage hint and a relevant caveat. No wasted words; every sentence earns its place.

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

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

For a simple read tool with an output schema and strong annotations, the description covers the essential context: what it returns and how truncation may affect large responses. The usage scenario is also stated. This is complete 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 already provides full documentation for the only parameter, dashboard_id, with the description 'Dashboard ID from list_all_dashboards'. Since schema description coverage is 100%, the description does not need to add extra parameter semantics, and it doesn't. Baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Get complete dashboard configuration and widgets.' The verb 'Get' and specific resource 'dashboard configuration and widgets' distinguish it from sibling tools like get_monitor_details or get_full_trace, which target different entities.

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 a clear use case: 'Use this when: need to see what's in a dashboard or copy its configuration.' It gives explicit when-to-use guidance, though it does not explicitly state when not to use it or mention alternatives. This is still clear context for the agent.

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, destructiveHint=false, so the safety profile is well-covered. The description adds value by mentioning the specific aspects of the downtime (scope, schedule, status) that the tool reveals, but it does not disclose any other behavioral traits beyond the annotations.

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

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

The description is two sentences, front-loaded with the main purpose and then a clear usage condition. No unnecessary words 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?

The tool is simple (one required parameter, read-only, with an output schema). The description and schema together provide all necessary information: what it does, when to use it, and what input is needed. There are no significant 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?

The schema covers 100% of the parameter (downtime_id) with a helpful description ('Downtime ID from list_downtimes'). The description itself does not add further parameter semantics, but the schema already does the heavy lifting, so the baseline of 3 is appropriate.

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

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

The description clearly states 'Get complete details of a specific downtime' with a specific verb ('get'), resource ('downtime'), and scope ('complete details'). It distinguishes from sibling tools like list_downtimes (which lists all) and schedule/update (which mutate).

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 this when: need to see a downtime's exact scope, schedule, or status.' This clearly conveys when to choose this tool, though it doesn't explicitly mention alternatives like list_downtimes for other contexts. It is still clear and actionable.

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

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

Annotations already indicate a safe read-only, idempotent operation. The description adds useful behavioral context by stating that it returns all spans and timing information, and that it covers the full request flow across services. No contradictions with annotations, but it doesn't disclose error behavior or 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?

The description is concise and front-loaded: the first sentence states the purpose, the second gives usage guidance. Every word earns its place 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?

For a tool with a single parameter, full schema coverage, safe annotations, and an output schema, the description adequately covers the purpose, usage context, and input origin. It doesn't need to explain return values since an output schema exists, and the tool's scope is clear for its 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?

Schema description coverage is 100%, so the schema already fully documents the trace_id parameter. The description's mention of 'after finding a trace ID' reinforces the schema wording, but adds no new syntax or detail beyond what the schema provides.

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

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

The description clearly states the tool's function: 'Get complete trace with all spans and timing information.' This specifies a verb ('get'), a resource ('full trace'), and the scope ('all spans and timing information'), clearly distinguishing it from sibling tools like search_apm_traces or get_log_details.

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 an explicit usage context: 'Use this when: need to see full request flow across services (after finding a trace ID).' This indicates the prerequisite of having a trace ID and the intended scenario, though it doesn't explicitly name alternative tools or 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=true, destructiveHint=false, and idempotentHint=true, so safety is covered. The description adds minimal behavioral context, only implying the tool is for post-search detail retrieval. It does not disclose any additional traits such as authentication needs or behavior about the returned data, which is acceptable given the output schema exists.

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

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

The description is two sentences: the first clearly states the action, the second provides usage context. Every word earns its place, and key information is front-loaded. Minimal 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?

With a single parameter, high annotation coverage, and an output schema describing the return structure, the description is complete. It states what the tool does and when to use it, and the output schema handles return value details. No significant 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% (log_id has a clear description: 'Unique log identifier, as returned in a search_logs result's "id" field'). The description adds no extra parameter semantics 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 clearly states the tool retrieves complete details for a specific log entry, using the specific verb 'Get' and resource 'log entry'. This distinguishes it from sibling tools like search_logs (which searches) and get_full_trace (which handles traces, not logs), and the phrase 'after searching' reinforces the intended workflow.

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

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

The description provides clear context for when to use the tool: 'need full information about a particular log (after searching)'. This implicitly directs the agent to first use search_logs, but it does not explicitly name alternatives or state when not to use the 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?

Annotations already cover read-only and idempotency, so the description adds value by specifying that the tool returns 'complete configuration and current status' and highlights thresholds and notification settings. This gives the agent a clear expectation of the response content.

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 short sentences with no filler. The main purpose is front-loaded, and the usage guidance is concise.

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

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

For a simple one-parameter read tool with rich annotations and an output schema, the description is complete. It covers purpose and usage without redundancy.

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 parameter description already provides semantic context by stating the source of the monitor_id ('from list_all_monitors or search_monitors'). The tool description itself does not need to add more, so baseline 3 is appropriate.

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

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

The description uses a specific verb ('get') and clearly identifies the resource ('complete monitor configuration and current status'). It also distinguishes from sibling tools like list_all_monitors or search_monitors by focusing on detailed configuration and current state.

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 'Use this when:' guidance with concrete use cases (see monitor details, thresholds, notification settings). It does not explicitly name alternative tools for exclusion, but the context is clear enough.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is well covered. The description adds context about recency filtering but does not disclose additional behavioral traits like pagination or response limits. It does not contradict the annotations.

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

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

The description is concise, using two short paragraphs with no filler. The key information is front-loaded, and every sentence serves a purpose.

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

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

The tool is simple with 3 optional parameters, an output schema exists, and annotations provide safety hints. The description conveys the core use case and differentiates from related tools, making it fully complete for an agent to select and invoke 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?

The input schema covers all parameters (host, since, tag_filter) with full descriptions, so the baseline is 3. The tool description adds no extra meaning beyond the schema, but that is acceptable given the high 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 lists metrics that have reported data since a given time, using a specific verb and resource. It also distinguishes itself from the sibling list_available_metrics by emphasizing 'actually emitting data recently.'

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

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

Explicitly provides guidance on when to use this tool—when you want to know what's actively reporting data—and contrasts it with list_available_metrics, making the choice between them 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 clear. The description adds the 'find a specific dashboard' hint (matching filter_query) but no additional behavioral details like pagination or limits, which are covered by the schema. No contradiction 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?

The description is two sentences, front-loaded with the core purpose, and contains no redundancy. Every word contributes meaning, making it highly concise and well-structured.

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

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

For a simple listing tool with optional parameters, an output schema, and rich annotations, this description is adequate. It covers the purpose and use case without needing to explain return values (output schema exists). It could be slightly more complete by naming alternatives, but overall it is sufficiently complete.

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

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

The input schema provides 100% coverage of both parameters (limit and filter_query) with descriptions and defaults. The description adds minimal extra meaning beyond 'find a specific dashboard,' which aligns with filter_query. Since schema covers everything, a baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Browse all Datadog dashboards.' It specifies the resource (dashboards) and the action (browse/list), and the second sentence clarifies the use case: seeing what exists or finding a specific one. This distinguishes it from siblings like get_dashboard_details, create_new_dashboard, and update_existing_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 description explicitly says 'Use this when: want to see what dashboards exist or find a specific dashboard.' This provides clear context for when to invoke the tool. However, it does not explicitly mention alternatives or when not to use it, though the siblings list implies such distinctions.

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 annotations already declaring readOnlyHint=true, idempotentHint=true, and destructiveHint=false, the description adds value by clarifying that the tool returns both monitors and their current alert states. It also hints that filtering is exact (not full-text), which is a useful behavioral distinction. 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?

Three short sentences: the first states the purpose, the second gives a use-case trigger, and the third names an alternative. Every sentence earns its place with no filler or repetition. It is front-loaded and easy to scan.

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

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

For a simple list tool with 6 optional parameters, a high schema coverage, an output schema, and clear read-only/idempotent annotations, the description fully covers what the tool does and when to use it. It even points to a sibling tool for a different use case, making it self-sufficient in context.

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

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

Schema description coverage is 100%, so all 6 parameters already have descriptions. The tool description does not add extra parameter-level detail beyond what the schema provides; it only generically refers to 'exact filters.' Baseline 3 is appropriate when the schema carries the parameter documentation burden.

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 'Browse' with the resource 'all monitors' and explicitly includes 'their current alert states,' which clearly differentiates it from sibling tools like get_monitor_details or create_alert_monitor. It also names 'search_monitors' as an alternative for a different search mode, making the tool's role unambiguous.

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

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

The description provides explicit guidance: 'Use this when: want to see what's being monitored or check alert status.' It also states a clear exclusion: 'For a faceted/full-text search instead of exact filters, use search_monitors.' This is a textbook example of when-to-use and when-not-to-use.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds the 'last hour' time window, which is behavioral context beyond the annotations. No contradictions exist.

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

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

The description is two sentences long, with the primary action first and a clear use-case clause second. 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?

For a simple list operation with two optional parameters and an output schema, the description provides all necessary context: what is listed, the time window, and when to use it. Return format is handled by the output 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 descriptions cover both parameters (env and limit) at 100%, so the baseline is 3. The tool description does not add parameter-specific meaning, but the schema is fully 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 clearly states that the tool lists services sending APM data in the last hour, specifying the resource (services), action (list), and temporal scope. This distinguishes it from sibling tools focused on traces, logs, or 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 description explicitly lists when to use the tool: to see what services are instrumented or to find service names. It does not mention alternatives or when not to use it, 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?

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds the scope 'all metrics available in Datadog' but does not disclose behaviors like pagination limits or the distinction between 'available' and 'active' metrics, which would be useful 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 compact and front-loaded with the tool's purpose, followed by usage context and an alternative. Every sentence adds value and there is 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?

Given the simple tool, rich annotations, and presence of an output schema, the description is nearly complete. The only gap is not addressing the sibling list_active_metrics to clarify the difference between 'available' and 'active' metrics.

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 documents both parameters (limit and filter) with clear descriptions at 100% coverage. The description adds no additional parameter-level meaning, so it meets the baseline but does not exceed it.

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 all metrics available in Datadog and frames it for discovery use cases. It explicitly distinguishes from describe_metric, but does not differentiate from the closely named sibling list_active_metrics, leaving some ambiguity.

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

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

Provides explicit when-to-use guidance ('don't know the exact metric name, or want to discover what's available') and names an alternative tool (describe_metric) for metadata/tag lookups. This gives clear direction for tool selection.

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds useful behavioral context (org-wide scope and that these are monitor mutes) but does not disclose pagination or return-format traits, consistent with the get_calls calibration.

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, front-loaded with the core purpose. No wasted words.

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

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

For a simple read-only list tool with output schema, annotations, and clear parameter descriptions, the description provides complete context for selecting and invoking 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 descriptions cover 100% of parameters, so the baseline is 3. The description does not add parameter-level detail, but the schema's own descriptions are 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 uses a specific verb ('Browse') with a clear resource ('scheduled/active downtimes') and clarifies the concept as 'scoped monitor mutes'. This clearly distinguishes it from sibling tools like schedule_downtime or get_downtime.

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 use cases: 'want to see what's currently muted org-wide, or audit upcoming maintenance windows.' This gives clear context for when to use the tool, though it does not mention alternatives 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 already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds query syntax examples but does not disclose additional behavioral details such as rate limits, pagination, or error behavior. Given the annotations, this is adequate but not enriched.

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

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

The description is concise and front-loaded: it states the purpose in the first sentence, follows with when to use it, and then gives four terse example queries. No wasted words; every line contributes to understanding.

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 a complete input schema, an output schema, and clear annotations, the description covers the essential aspects for selecting and invoking the tool. It provides enough examples to construct valid queries, while the output schema handles return value documentation. Minor gaps (e.g., no note about complex query construction) prevent a perfect score.

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 describes all three parameters with 100% coverage, so the baseline is 3. The description adds value by providing concrete example values for the query parameter (e.g., 'avg:system.cpu.user{*}'), which clarifies the expected syntax beyond the schema's generic description.

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

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

The description clearly states the tool 'Query and visualize time series metrics' – a specific verb and resource. It also provides concrete examples for CPU, memory, host, and tag queries, which differentiates it from sibling tools like 'list_available_metrics' or 'describe_metric' that focus on metadata discovery.

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 includes an explicit 'Use this when' clause: checking system performance, resource usage, or custom metrics. This gives clear context, though it does not mention when not to use it or name alternative tools, 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?

Annotations declare readOnlyHint=false and destructiveHint=false, and the description adds valuable behavioral context: mutual exclusivity of monitor_id and monitor_tags, fallback to all matching scope when neither is set, and the open-ended downtime behavior that requires update_downtime later. This goes beyond the 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?

Three sentences, front-loaded with purpose, and every sentence adds value. No fluff or redundancy; it is concise yet informative.

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

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

For a tool with 8 parameters and an output schema, the description covers the essential context: purpose, when to use, parameter constraints, and edge cases like open-ended downtimes. Output schema exists, so not explaining return format is acceptable.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds critical parameter semantics not duplicated in the schema: the rule that at most one of monitor_id/monitor_tags should be set, and the behavior when neither is set. This helps agents choose parameters correctly.

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

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

The description opens with a specific verb+resource+scope: 'Schedule a downtime to mute a scope of monitors (or one monitor) over a time window.' It clearly distinguishes from sibling tools like silence_monitor by noting when the latter is simpler, providing explicit differentiation.

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 'Use this when' examples (silencing many monitors by scope/tag, or muting on a schedule with a known end time) and names an alternative tool for simpler cases ('silence_monitor is simpler'). This directly addresses when 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 cover read-only/idempotent safety, so description adds meaningful context: pagination, raw span retrieval (vs aggregates), and query syntax quirks. It doesn't overwhelm with irrelevant details, but stops short of disclosing any edge-case behaviors like 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 concise and front-loaded; it states the core purpose, then quick usage criteria, alternative, and examples. No wasted sentences, and examples are scannable.

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

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

With rich annotations, a complete input schema, and an output schema present, the description fully covers when and how to use the tool, including alternative paths. Nothing crucially missing for a read-only search tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description reinforces query syntax through examples but adds no additional parameter-level meaning beyond what the schema already 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?

Description opens with a specific verb+resource: 'Search distributed traces and spans for performance analysis (paginated).' It clearly differentiates from siblings by mentioning aggregate_spans for statistics, and the name itself is descriptive.

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?

Explicit 'Use this when' list and a direct alternative recommendation ('use aggregate_spans instead') with reasoning. Common query examples further clarify when this tool fits.

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 and idempotentHint=true, so the safety profile is covered. The description adds 'Returns paginated results' and contrasts performance with alternatives ('never fetch raw log content'), providing useful behavioral context without contradicting annotations.

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

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

The description is long but well-structured with clear sections. Each bullet names a distinct sibling tool, earning its place. The 'IMPORTANT' block is slightly redundant with the bullets, keeping it from a perfect score.

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 (7 params, pagination, many siblings), the description covers what it does, when to use it, and when not to, with specific alternatives. The output schema exists for return values, so 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 description coverage is 100%, so the description does not need to add much parameter-level detail. It provides general scope (search vs count) but does not go deeper than the schema already does, so baseline 3 applies.

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

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

The description starts with 'Search and VIEW log entries,' which is a specific verb+resource statement. It also explicitly distinguishes from siblings by contrasting with count_logs, count_unique_values, and aggregate_logs_by_field, 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 description includes explicit 'Use this when' and 'DO NOT use for' sections, naming specific alternative tools for each exclusion. This fully satisfies the when-to-use/alternatives requirement.

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, openWorldHint, and destructiveHint, so the safety profile is clear. The description adds behavioral context about the search semantics (full-text, faceted, substring matching) beyond what annotations convey, though it doesn't detail pagination or rate 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?

The description is two sentences: the first states the purpose, the second provides usage guidance with a named alternative. No wasted words, and the key points are front-loaded.

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

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

The description, combined with a 100%-covered schema, rich annotations, and an output schema, fully covers purpose, usage, safety, and return values. The tool is simple enough that no additional context is needed for an agent to select and 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 100%, with both query and per_page clearly documented in the input schema. The tool description adds no new parameter-specific meaning beyond what the schema already provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool performs 'Full-text/faceted search across monitors' with examples of facets (tag, status, text in query/name). It also distinguishes itself from list_all_monitors by noting the exact-match limitation, making the purpose immediately obvious.

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

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

The description explicitly guides when to use this tool: 'Use this when: list_all_monitors's exact-match filters aren't enough'. It names the alternative tool and provides a concrete use case (searching by substring across facets), effectively covering both when and 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 indicate a write operation (readOnlyHint=false) with open-world side effects. The description adds value beyond annotations by explaining the semantics of gauge, count, and rate metric types, which are not detailed in the schema. It does not discuss data persistence or rate limits, but the annotations cover the safety profile adequately, so the description adds useful context without contradicting structured data.

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

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

The description is compact and well-structured: a one-line summary, a 'Use this when' sentence, and a bulleted list of metric types. Every sentence contributes to understanding the tool's purpose and usage. There is no redundancy or filler, and the most important information is front-loaded.

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

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

Given the tool's complexity (6 parameters, nested points array) and the rich schema and annotations, the description is mostly complete. It covers the core use case and metric type semantics, and the schema already documents parameter formats. The only minor gap is that it does not mention any prerequisites (e.g., authentication) or explicitly contrast with read-only metric tools, but these are partially covered by annotations and sibling context.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful semantic detail for the metric_type parameter by defining each allowed value (gauge, count, rate) with real-world examples (e.g., temperature for gauge, events per second for rate). This enhances understanding beyond the schema's brief description, so it earns a 4.

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

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

The description starts with a specific verb and resource: 'Send custom metric data points to Datadog.' This clearly states what the tool does and distinguishes it from sibling tools like query_metrics or list_available_metrics, which are read-oriented. The 'Use this when' clause further clarifies its intended use for tracking custom application metrics or business KPIs.

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

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

The description explicitly states when to use the tool: 'Use this when: need to track custom application metrics or business KPIs.' It also explains the three metric types with examples, helping the agent choose the correct type. However, it does not explicitly mention alternatives like query_metrics for reading metrics, so it lacks an explicit 'when not to use' clause.

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 idempotentHint=true and destructiveHint=false. The description adds 'temporarily' and clarifies it affects notifications, not the monitor itself, and is for a single monitor. This enriches the behavior beyond annotations without contradiction.

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, front-loaded with the primary purpose, and gives usage guidance in a few tight sentences. Every sentence adds value, with 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?

Given the tool's moderate complexity, the description covers purpose, use cases, alternative, and scope. An output schema exists, so lack of return-value details is not a gap. The description is sufficient for correct tool selection and 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 100%, so baseline is 3. The description does not add parameter-specific details beyond the schema; it only refers to 'single monitor' which is already implicit in monitor_id. No additional semantics are provided.

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

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

The description clearly states a specific verb and resource: 'mute/silence monitor notifications' for a single monitor. It distinguishes from the sibling tool schedule_downtime by noting it is for single monitors, not scheduled/scoped muting.

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

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

Explicitly provides when-to-use scenarios ('performing maintenance, testing, or a known issue') and excludes scheduled/scoped silencing, recommending schedule_downtime as the alternative. This is direct guidance with a named alternative.

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, idempotentHint=true, and destructiveHint=false, which cover the safety and mutation profile. The description adds only the trigger condition for use, not deeper behavioral details like required prior state or scope-matching semantics. The scope constraint is in the parameter schema description, not the main description.

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 the purpose in the first and usage guidance in the second. It is front-loaded and contains no redundant phrasing 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 two-parameter tool with a complete schema and output schema, the description covers the essential purpose and the appropriate timing. It could have explicitly mentioned that the scope must match the mute scope in the main description, but that is already in the parameter description. It does not need to explain return values since an 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?

The input schema has 100% description coverage, with both parameters documented: monitor_id ('Monitor to unmute') and scope ('Unmute a specific scope (must match the mute scope)'). The tool description itself adds no additional parameter semantics. The baseline of 3 applies when the schema is comprehensive.

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 'Resume' with the resource 'notifications from a muted monitor', clearly identifying the action. The context line 'Use this when: maintenance is complete or ready to receive alerts again' reinforces the tool's role. The name unsilence_monitor and sibling silence_monitor make the distinction obvious.

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

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

The description explicitly states when to use the tool: 'maintenance is complete or ready to receive alerts again.' It does not explicitly mention when not to use it or point to a specific alternative, but the sibling silence_monitor is the obvious inverse. This is clear situational guidance, though not as explicit as a full when/when-not breakdown.

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 description goes beyond annotations by explaining overwrite semantics ('Overwrites given fields; rest is unchanged') and the irreversible nature of changes ('no undo tool... not recoverable'). This adds critical behavioral context that complements the destructiveHint annotation without contradicting it.

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

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

The description is three sentences, front-loaded with the primary action, followed by usage context and a critical warning. Every sentence earns its place 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?

The tool has a full input schema and an output schema, so the description need not explain return values. It covers the key behavioral aspects (overwrite, non-recoverability) and usage scenarios, making it complete for an agent to correctly invoke the tool.

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

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

Schema coverage is 100%, so the schema already documents each parameter. The description adds meaningful parameter semantics by clarifying that only provided fields are overwritten and others remain unchanged, which is essential for correct usage. It also maps example actions (adjust thresholds, notifications) to parameter use.

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: 'Modify an existing monitor's configuration.' It uses a specific verb and resource, and distinguishes from sibling tools like create_alert_monitor and silence_monitor by focusing on modification. The added detail about overwriting given fields further clarifies scope.

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

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

The description provides a 'Use this when' section listing specific scenarios (adjust thresholds, change notifications, update alert logic), giving clear usage context. It does not explicitly name alternatives or exclusions, but the guidance is sufficient for an agent to choose this tool over create or silence 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?

Annotations already declare destructive and read-only status. The description adds crucial warning that there is no undo, and the previous configuration is unrecoverable. This adds value beyond annotations without contradicting 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 two sentences, front-loaded with the primary action, followed by clear usage guidance and a critical warning. No unnecessary words 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?

Given an output schema exists and annotations cover safety, the description adequately captures the tool's purpose, usage scenarios, and irreversibility. It does not detail every optional parameter, but the schema covers that. Slight room for mentioning partial update behavior, but overall complete.

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

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

Schema coverage is 100%, and each parameter is well-documented in the schema. The description does not add significant new parameter semantics; it repeats the 'now' usage already present in the schema. 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 modifies an existing downtime, specifically its scope, schedule, or message. The verb 'modify' and the resource 'existing downtime' are specific, and the mention of 'existing' distinguishes it from creation tools like schedule_downtime.

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 when-to-use scenarios: extending/shortening a window, changing scope, or ending early with 'now'. It lacks explicit alternatives or when-not-to-use, but the context is sufficiently clear for selection among sibling tools.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds essential behavioral context: the partial overwrite semantics and the critical warning that there is no undo and previous state is not recoverable. This goes beyond the structured annotations and is highly valuable for an agent deciding whether to invoke the tool.

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

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

The description is three sentences, front-loaded with the main action, and every sentence carries meaningful information. There is no redundant fluff, and the warning is placed at the end as an important caveat. It is appropriately concise for the tool's complexity.

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 has 8 parameters, a required dashboard_id, and an output schema, the description covers the essential context: what it does, when to use it, the partial-update semantics, and the destructive irreversibility. The annotations cover idempotency and read-only hints, so the description does not need to repeat those. No critical context is missing for safe and 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?

The input schema has 100% description coverage for all parameters, so the baseline is 3. The description adds value by explaining the general parameter behavior ('anything omitted is unchanged') and linking parameters to use cases (widgets, layout, config). This helps the agent understand that parameters are independent and optional, with no default-resetting behavior.

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 ('Modify') and resource ('existing dashboard'), and clearly states the update semantics (overwrites given fields, omitted unchanged). It distinguishes itself from sibling tools like get_dashboard_details and create_new_dashboard by explicitly targeting modifications.

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 use cases ('when need to add widgets, change layout, or update dashboard config'). While it doesn't name alternatives directly, the context of sibling tools makes it clear that creation or retrieval are separate. It could be stronger by explicitly saying 'use create_new_dashboard for new dashboards', but the guidance is clear enough.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations: it explicitly states 'never creates, modifies, or persists' and provides a specific permission caveat about log alert validation requiring log data read access. This helps the agent anticipate potential permission errors.

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

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

The description is concise and well-structured: the first sentence states the core purpose, followed by a clear 'Use this when' directive and a brief caveat. Every sentence earns its place, with no fluff or redundancy.

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

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

Given the tool's straightforward validation function and the presence of an output schema, the description is complete. It covers purpose, usage context, safety guarantees, and a potential permission edge case. There is no missing information that would impede an agent from using the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-level detail beyond the schema, but it does mention the 'log alert' monitor type in the permission note, which is a parameter-specific behavioral nuance. However, it does not explain query syntax or monitor_type values beyond what the schema already provides.

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

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

The description clearly states the tool's function: 'Validate a monitor query's syntax without creating anything.' It uses a specific verb (validate), names the resource (monitor query), and explicitly distinguishes itself from create_alert_monitor by stating it never creates, modifies, or persists a monitor.

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 an explicit usage scenario: 'Use this when: want to check a monitor definition is well-formed before calling create_alert_monitor, especially for hand-built queries.' This clearly tells the agent when to use it and directly names the alternative (create_alert_monitor) for the actual creation step.

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