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

With no annotations, the description carries the full burden and adds genuinely non-obvious behavior: the tool runs through the Dynatrace Bridge browser extension in the user's logged-in browser, and on failure the agent must report the error rather than fall back to browser automation. It does not state read-only guarantees, rate limits, or expected latency, but the environment/transport caveat is high-value context that no structured field provides.

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, then usage, then follow-ups, then the transport caveat -- the ordering an agent needs. No sentence is filler, though the first sentence is a long enumeration and the filter list partly restates schema names, adding 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?

No output schema exists, so the description must describe return values, and it does: ranked failure reasons with type, status, failure share, exception classes/messages plus top stack frames, failed downstream calls, and affected requests. Combined with usage routing and the extension dependency, an agent has everything needed to call and interpret this 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 the baseline is 3 and the schema already documents all 18 parameters. The description adds value beyond the schema by grouping the shared trace filters (response_time_min_ms, http_code, failed, request, url_contains, request_kind, raw_filters) and stating their collective effect -- they narrow the analysed requests -- and by restating that `service` accepts an id or a name.

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?

Opens with a specific verb+resource ('Explains why requests of a service fail in a time window') and enumerates the exact output shape (ranked failure reasons, type, HTTP status, failure share, exception classes/messages with stack frames, failed downstream calls). It is clearly distinguishable from siblings like top_exceptions and list_traces, which it explicitly frames as complementary.

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?

Gives an explicit entry condition ('Start here for "why does this service fail": use it when a service shows a failure rate or a problem names it') and names the follow-up alternatives with the arguments that select them (list_traces with failed:true/http_code, top_exceptions for counts). This is the when/when-not/alternatives pattern done well.

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 exist, so the description carries the full burden and does so: it discloses that two analysis requests run sequentially, that it executes through the Dynatrace Bridge browser extension in the user's logged-in browser, and instructs the agent to report failures rather than fall back to browser automation. It also previews what the output contains, including that omitted items are counted.

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 before usage and follow-ups, and every paragraph serves a distinct job (what it shows, when to use it, where to go next). It is dense and long, but for a 17-parameter analysis tool the length is largely earned rather than padded.

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 complex multi-part analysis tool with no output schema, the description still explains the return structure (hotspot breakdown, histogram, outlier tail, omission counts), the filter surface, the browser dependency and the failure path. An agent has enough to call it correctly and interpret the result without further documentation.

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 a 3, but the description adds genuine value by grouping the 'shared trace filters' and giving usage examples (`response_time_min_ms: 2000`, `request` for a single endpoint) that explain intent rather than restating the schema. It does not clarify the interaction between time_from/time_to/minutes_lookback or the filter precedence, which the schema already handles in detail.

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?

Opens with a specific verb and resource: 'Shows where the response time of a service goes and how it is distributed', then enumerates the two analysis parts (hotspot breakdown and response-time histogram). It also distinguishes itself from siblings by naming service_flow, method_hotspots, top_database_statements and list_traces as different tools.

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 states when to reach for it ('Start here for "why is this service (or one of its endpoints) slow"') and which filters apply in which situation, with a concrete example (`response_time_min_ms: 2000` analyses only slow requests). It also routes the agent onward with named follow-ups for each sub-question.

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

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

With no annotations, the description carries the full burden and does so: it discloses the runtime dependency (executes through the Dynatrace Bridge browser extension in the user's logged-in browser), an explicit failure protocol (report the error, do not open tabs or automate), and output behavior (limit default 20 / max 200, omitted rows are reported, resolved UTC window shown in the header). This is materially more than the schema provides.

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 core purpose, then discovery routing, then environment/failure caveat. Each of the three short paragraphs carries distinct, non-redundant information with no 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?

No output schema exists, yet the description describes what the table contains (CPU time, share of total, GC time, peak timing, supported deeper analyses) and how omissions are surfaced. Combined with the browser-extension caveat and the explicit routing to follow-up tools, an agent has everything needed to call and interpret 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 description coverage is 100%, so all six parameters (text, limit, time_to, time_from, environment, minutes_lookback) are already documented in the schema, including the ISO-8601/UTC handling and lookback semantics. The description adds only the cross-tool note about passing the process group id downstream, which is about the consumer tool, not this one's parameters. Baseline 3 is correct.

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 ('Lists the process groups that consumed the most CPU in the window') and immediately scopes it to Dynatrace continuous CPU profiling. It also enumerates the returned metrics, so an agent can tell it apart from sibling tools like method_hotspots or trace_statistics without opening a 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?

Explicitly says when to start here ('which process burns the CPU') and names three follow-up alternatives (method_hotspots, thread_analysis, memory_allocation_hotspots) plus a distinct route for per-endpoint CPU (trace_statistics with metric CPU_TIME). It even specifies the handoff value: pass the PROCESS_GROUP id as process_group.

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

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

With no annotations, the description carries the full burden and does so well: it discloses the browser-extension execution model, the default 24h window, that a run is counted with full duration, that runs still executing at window end may be missing, and that unnamed rows are collected and marked in the output. It also gives explicit error-handling instructions rather than leaving retry behavior ambiguous.

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 purpose and usage routing are front-loaded, and the paragraphs are organized by concern (purpose, service selection, window/sort, follow-ups, runtime). It is longer than strictly necessary — the sort list and several filter semantics duplicate schema descriptions — but every block adds usable context.

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 tool with no annotations and no output schema, the description covers the output columns, the attribution caveat for unnamed rows, the window resolution rules, and the follow-up chain. Nothing an agent needs to select and invoke this tool correctly 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%, so the baseline is 3, but the description adds genuine meaning beyond the schema: default service `CronJobs`, how multiple same-named services are combined, the resolved-window behavior across `time_from`/`time_to`/`minutes_lookback`, and the semantics of `name`/`response_time_min_ms`/`failed`. Some of this (e.g. the sort enum) merely restates the schema, keeping it short of a 5.

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 opening sentence states a specific verb and resource ('Ranks cron jobs by how much time they take') and enumerates the returned metrics, so an agent immediately knows this is a ranking/statistics tool over cron jobs. It also names the sibling it complements (`list_service_requests`) and what it does that sibling cannot, making it distinguishable at a glance.

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

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

It gives explicit when-to-use phrasing ('the tool for "which cron jobs are the slowest"'), states the default service and how to override it, describes the default time window, and prescribes follow-ups (`list_traces` then `get_trace`). It even handles the failure case (no such service exists) and gives operational guidance (report errors, don't automate the browser).

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

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

With no annotations, the description carries the disclosure burden and does so well: it states the tool works with no extension connected, that check_session opens a Dynatrace tab in the foreground of the user's browser, and that it verifies login state per environment. It is honest about a side effect (opening tabs), though it doesn't cover latency/cost of probing all environments.

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?

Well front-loaded: purpose first, then when-to-call, then the optional parameter, then the routing guide. The extensive per-tool routing block is genuinely useful but concerns the sibling tools rather than this one, so it dilutes conciseness somewhat even though each line is dense and 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?

With no output schema and no annotations, the description fully compensates by enumerating the returned fields (version, upgrade availability, per-browser extension version, environment name/id/URL) and the error-recovery role. Nothing an agent needs to call this correctly 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% and the single parameter's schema already documents the read-request behavior and the default of false. The description adds only the goal framing ('see whether the browser is still logged in'), which is a slight enrichment but largely overlaps the schema. Baseline 3 is appropriate.

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

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

States a specific verb+resource: reports bridge usability, server version/upgrade availability, extension connection and version per browser, and configured environments with name/id/URL. This is clearly a status/meta tool, cleanly distinguished from the diagnostic siblings (list_problems, service_overview, etc.).

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?

Gives explicit trigger conditions: 'Call this first when another Dynatrace tool fails with a connection, environment or session error, or when the user asks which environments are available.' It also notes exclusions (works even with no extension connected) and provides a full routing map to siblings, so an agent knows exactly when this tool applies vs. 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?

No annotations are present, so the description must carry behavioral disclosure — and it does add real value: entities only inside the time window are returned, resolution goes through the Dynatrace Bridge browser extension, and on failure the agent is told to report the error rather than fall back to browser automation. It stops short of describing the output shape (there is no output schema, so return format is only partly inferred from the schema descriptions).

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?

Well front-loaded — purpose first, then parameter guidance, then behavior, then the failure-handling caveat. It is longer than strictly necessary (the type list is repeated almost verbatim in the schema), so it is efficient but not maximally tight.

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 9-parameter, all-optional search tool with no annotations and no output schema, the description covers the essentials: what is searched, what is returned (ids and names), time-window semantics, limit behavior with omitted counts, and the browser-extension dependency with failure guidance.

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 genuine semantic value: worked selector examples (pods of a workload, tagged services), a list of valid type values, and practical fields examples beyond the schema's list. It notably omits the interaction between selector and the other params except to say type/name are ignored.

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 ('Searches Dynatrace monitored entities of any type and returns their ids and names') and makes the differentiating role explicit: it converts a user-mentioned name into the entity id other tools need. It also distinguishes itself from the sibling get_entity by naming that tool as the follow-up for full properties.

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?

Gives concrete when-to-use conditions ('turn a name the user mentions into the entity id', 'list what exists'), an explicit edge case (called with neither type nor selector, it lists entity types), and routes to the alternative get_entity for all properties and relationships.

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

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

No annotations are provided, so the description carries the full burden, and it does disclose a major behavioral trait: execution goes through the Dynatrace Bridge browser extension in the user's logged-in browser. It also gives failure guidance ('report the error to the user; do not try to open browser tabs or automation instead'), which is unusually valuable context. It does not explicitly state read-only semantics for the query.

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 paragraphs, each with a distinct job: what it returns, how to search, and how it executes. The purpose and the query_metrics routing are front-loaded, and nothing is padded.

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 compensates by enumerating the returned fields (id, unit, aggregations, dimensions, entity types) and by covering execution path and failure handling. Also notes limit/omission behavior. Nothing an agent needs to call this safely 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%, so baseline would be 3, but the description adds real meaning beyond the schema: concrete free-text examples ('response time', 'container memory', 'v8 heap') and concrete selector patterns ('builtin:service.*', 'builtin:kubernetes.workload.*'). That elevates it above the schema baseline.

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 (searches) and resource (Dynatrace metric catalogue) and enumerates what comes back (metric ids, unit, aggregations, dimensions, entity types). It is clearly distinguishable from the sibling query_metrics, which it explicitly references.

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?

Gives an explicit condition for use ('before query_metrics whenever you are not sure of the exact metric id') and names the alternative tool. The reader knows exactly when this tool is the right choice versus query_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?

With no annotations, the description carries the full burden and does so well: it discloses the per-tile request cost to Dynatrace, the default/maximum tile_details budget (12 default, at most 30), that remaining tiles are listed without queries and their ids returned for a follow-up call, and that execution runs through the Dynatrace Bridge browser extension in the logged-in browser. This is exactly the operational context an agent needs.

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-loads what the tool returns in the first sentence, then devotes the second paragraph to the token-cost mechanics and the browser-extension dependency. It is dense but every sentence earns its place; slightly long given the parameter volume.

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?

Ten parameters, no annotations, and no output schema, yet the description explains the return shape, the tile budget semantics, the follow-up call path, the time-window behavior, and the failure mode. Nothing material an agent needs to call it correctly 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% and the property descriptions are already detailed, so baseline is 3. The description adds value beyond the schema by explaining cross-parameter relationships, e.g. that `tile` overrides the default first-`tile_details` chart tiles and that the output names the tile ids to pass as `tile` next.

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 ('Shows one Dynatrace dashboard') and enumerates exactly what is returned: owner, tags, every tile with type and title, and metric selectors for chart tiles. It explicitly distinguishes itself from siblings by pointing to `list_dashboards` for ids and `query_metrics` for reading the underlying data.

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

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

Gives concrete conditions: `dashboard` accepts an id from `list_dashboards` or a name (ambiguous names return candidates); `tile` selects which tiles' queries to read; `run_queries: true` executes the selectors. It names `query_metrics` as the alternative for reading the same data and instructs what to do on failure (report the error, do not fall back to browser automation).

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

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

With no annotations, the description carries the full behavioral burden and does add genuinely important context: the call runs through the Dynatrace Bridge browser extension in the user's logged-in browser, and on failure the agent should report the error rather than attempt browser automation. It stops short of explicitly stating read-only semantics, rate limits, or environment-connection prerequisites (though it points to dynatrace_bridge_status for environment names).

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 return contents, then invocation rules, then the environment/failure caveat — a sensible ordering with little waste. The parenthetical property enumeration per entity type is somewhat long, but it earns its place by showing breadth for a type-agnostic tool.

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 7-parameter, no-output-schema, no-annotation tool, the description does most of the necessary work: it describes the response shape, disambiguates the name-vs-id path, and flags the browser-extension dependency and failure protocol. It does not explain the time-window parameters (time_from/time_to/minutes_lookback) in prose, leaving that entirely to the schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The prose largely restates what the schema already says ('Pass `entity` as an id ... or as a name together with `type`'; ambiguity returns candidates) and adds no syntax or format detail beyond it, though the cross-tool note about reusing related ids is a useful extension.

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 ('Returns one Dynatrace entity in full') and enumerates the returned content: type, first/last seen, tags, management zones, type-specific properties, and relationships with ids/names. The word 'one' plus the relational detail plainly separates it from the many list_* siblings (list_pods, list_services, find_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?

Gives concrete invocation guidance: pass `entity` as an id or as a name together with `type`, note that an ambiguous name returns candidates, and that related ids can be fed back into get_entity or query_metrics entity selectors. It does not, however, state when to prefer this over find_entities or get_host/list_pods for the same object.

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

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

With no annotations, the description carries the full behavioral burden and does so well: it discloses the transport (runs through the Dynatrace Bridge browser extension in the user's logged-in browser), the failure mode (report the error, do not attempt browser automation), ambiguous-name behavior, and environment defaulting. This is exactly the operational context an agent needs.

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 returned fields, then parameter guidance, then the bridge/transport caveat, which is a sensible ordering. The first paragraph is dense and long but each clause adds a distinct facet of the return payload, so little is wasted.

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 6-parameter, no-output-schema, no-annotation tool, the description covers return contents, input forms, defaulting behavior, cross-tool follow-ups and the failure path, so an agent can call it correctly without further inference. Nothing essential 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%, so the baseline is 3, but the description adds value beyond the schema: it clarifies that a host name from list_pods works for Kubernetes nodes, and points to dynatrace_bridge_status for the environment parameter whose valid values are intentionally not listed. That cross-referencing exceeds what the schema alone conveys.

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 ('Returns one host in detail') and then enumerates exactly what is returned: OS, CPU/memory, IPs, monitoring mode, availability/downtimes, problems, usage series, disks, processes and events. This lets an agent distinguish it from generic entity tools like get_entity without opening schemas.

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

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

Gives concrete routing: accept host id or name, treat Kubernetes nodes as hosts using names from list_pods, follow up with get_process or query_metrics with entityId selector, and consult dynatrace_bridge_status for environment names. It lacks an explicit when-not-to-use or a direct comparison against get_entity, but 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?

No annotations are present, so the description carries the full burden and does so well: it discloses the default vs `detail` output modes, that Davis/trigger/path sections come from internal endpoints and degrade gracefully with a note, and the browser-extension runtime with explicit failure-handling guidance. The only gap is the absence of auth/permission notes, but the coverage is otherwise 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?

Led by the core purpose, then parameters, then operational caveats – well front-loaded. The middle sentence is dense and long but every clause conveys distinct return-content semantics, so it earns its place despite the length.

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

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

With no output schema, the description must describe return values and it does so exhaustively: default overview fields, long-form `detail` sections, fallback behavior on unavailable endpoints, and the trailing hand-off fields. Nothing an agent needs to call or interpret this tool 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% (baseline 3), and the description adds genuine value beyond the schema: it explains the two accepted `problem` id formats, spells out what each `detail` enum section contains at length, and links the returned service id/window to downstream tools.

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?

Opens with a specific verb+resource: 'Returns one Dynatrace problem.' It then enumerates the exact contents of the default output (status, severity, entities, Davis findings, etc.), which makes it clearly distinguishable from the sibling `list_problems` (singular retrieval vs listing).

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?

Tells the agent where the `problem` argument comes from ('the internal problem id from `list_problems`') and where the output feeds ('to pass to `analyze_failures` and `list_traces`'). It gives clear usage context but stops short of an explicit when-to-use-this-vs-that rule (e.g. versus list_problems).

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

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

With no annotations, the description carries the full burden and does disclose non-obvious behavior: the tool 'runs through the Dynatrace Bridge browser extension in the user's logged-in browser,' instructs the agent to surface failures to the user, and explicitly forbids browser-automation fallbacks. It also notes the environment default and the ambiguity-returns-candidates behavior. Not covered: any auth/permission requirements or pagination/response-size 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?

Three short paragraphs: what it returns, how to supply the entity id and where to go next, and the execution/failure model. It is front-loaded and every sentence carries routing or behavioral information. It runs slightly long, but nothing is redundant 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 no-annotation, no-output-schema, single-entity detail tool, the description compensates well by enumerating the returned fields, the id formats, the ambiguity path and the failure/reporting model. Remaining gaps are minor: no mention of output size, rate limits, or permission requirements.

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 earns above baseline by adding semantics the schema does not: that an ambiguous name returns candidates with their ids (never guesses), where ids originate, and that omission of `environment` resolves to the first configured environment listed by `dynatrace_bridge_status`. Window-resolution logic for time_from/time_to/minutes_lookback is largely already in the schema.

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

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

States a specific verb and resource and immediately disambiguates the two entity kinds it can return (PROCESS_GROUP_INSTANCE vs PROCESS_GROUP), then enumerates the payload: technology/version, host, pod, container, workload, hosted services, callers/callees, CPU and memory, events. An agent can distinguish this from get_host, process_runtime and list_pods without opening any 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?

Names explicit alternatives and the condition that selects them: 'Follow up with `process_runtime` for JVM / Node.js metrics, or the service tools with a service id from the list.' It also tells the agent where valid process ids come from (get_host, process_runtime, find_entities). There is no explicit when-not guidance, but the routing is clear enough for correct 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?

With no annotations, the description carries the full burden and does so well: it discloses sibling-call collapsing, that the output always reports what was hidden, and the operational constraint that the tool runs through the browser extension and that failure should be reported rather than worked around. It stops short of describing permission/authentication requirements or error modes beyond the extension failure.

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-loads the output shape, then usage, then large-trace controls, then follow-up, then the browser constraint, in four tight paragraphs. The long enumeration of tree fields is the one place that approaches padding, but it earns its place given there is no output schema.

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 9-parameter tool with no output schema and no annotations, the description supplies the missing return-format detail, the window-resolution rule, the large-trace capping semantics, and the runtime environment, so an agent has everything needed to call 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 coverage is 100%, so the baseline is 3; the description adds behavior the schema does not state, namely that hidden output is always reported ('the output always says what was hidden', 'the output says how many were omitted') and that the response header shows the resolved absolute UTC window.

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 and resource ('Shows one trace as an indented span tree') and enumerates exactly what each line contains, so an agent can distinguish it from list_traces (discovery) and get_trace_details (deep dive) 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?

It states precisely where the required identifiers come from ('Pass `trace_id` and `call_uri` exactly as printed by `list_traces`') and the follow-up path ('Follow up with `get_trace_details` on a node's `callURI`'). The time-window rule and the alternative tool are both named explicitly, leaving nothing 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?

With no annotations, the description carries the full burden and does so richly: secret/credential parameters and headers are masked, auth/cookie/token headers are never shown, each output section gets its own share so one cannot crowd out others, the method tree hides sub-threshold and pass-through frames and reports how many were hidden, and the tool depends on the user's logged-in browser via the Dynatrace Bridge extension. These are exactly the behavioral traits an agent cannot infer from 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?

Purpose is front-loaded, followed by invocation, then output/parameter behavior, then the operational caveat, with no filler sentences. It is long, and the parameter paragraph partly restates schema defaults (limits, caps), which slightly dilutes density for an otherwise tight definition.

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

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

For an 11-parameter tool with no output schema and no annotations, the description covers what is returned section by section, how output is bounded, how secrets are masked, and the browser-extension execution model. An agent has enough to call it correctly and to interpret the result.

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 description adds meaning beyond the schema: min_method_ms also drops pass-through frames and the output reports the hidden count, the time parameters resolve to a stated absolute UTC window in the response header, and lookback interacts with time_from/time_to. These go beyond the per-field schema text.

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 opening sentence states a specific verb+resource (retrieve everything recorded about one trace node) and then enumerates exactly what that includes: exceptions with stack traces, the method tree, downstream calls, SQL, HTTP headers, host/process, technologies. This clearly distinguishes it from get_trace (which prints nodes) and list_traces (which prints entry calls).

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

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

It gives concrete invocation context: pass the call_uri as printed by get_trace or list_traces, with a time window containing the trace, establishing the get_trace -> get_trace_details flow. It also gives failure guidance (report the error, don't fall back to browser automation). It stops short of explicitly saying when NOT to use it versus trace_statistics or analyze_* siblings.

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

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

With no annotations, the description carries the full burden and does so well: it discloses that the tool runs through the Dynatrace Bridge browser extension in the user's logged-in browser, tells the agent to report errors rather than open tabs, and forbids browser automation. It does not explicitly state read-only semantics, but 'lists... visible to the user' implies 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?

Three short paragraphs, front-loaded with purpose, then the follow-up tool, then the runtime caveat. Every sentence earns its place and nothing is redundant.

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?

There is no output schema, but the description compensates by listing the returned fields, and the environment parameter's discovery path (dynatrace_bridge_status) is documented in the schema. Limit/pagination semantics live in the schema rather than the description, which is acceptable but leaves the description slightly short of fully self-contained.

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

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

Schema description coverage is 100%, so the schema already documents text, limit and environment. The description repeats the `text` matching behavior (name, owner, tags) without adding syntax or format beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Lists the Dynatrace dashboards visible to the user') and enumerates the returned fields (id, name, owner, last modification, tags). It clearly differentiates itself from sibling get_dashboard by describing what that tool adds (tiles, metric selectors).

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?

Routes the agent explicitly to get_dashboard as the follow-up when tiles/metric selectors are needed, and explains how the `text` filter behaves. It gives clear usage context but no explicit when-not-to-use condition or a competing list-type sibling to avoid.

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 exist, so the description carries the full burden and does so: it discloses the deduplication rule (identical type/title/entity/K8s reason collapsed into one row with count and first/last time), the unfiltered default (every event in the window), and the browser-bridge execution constraint with explicit failure handling ('report the error to the user; do not try to open browser tabs').

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?

Well front-loaded: what is listed and how events collapse come first, then scope, then routing, then the bridge caveat. It is long, and some scoping detail duplicates schema descriptions that already carry examples, but nearly every sentence adds a distinct fact.

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 9-parameter tool with no annotations and no output schema, the description covers what the tool returns (grouped rows with counts and first/last timestamps, resolved UTC window in the header, omitted-count reporting) and how it executes. Nothing an agent needs to call it correctly 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%, so the baseline is 3, but the description goes beyond the schema with composite entitySelector examples (fromRelationships.isInstanceOf for workload pods), a raw eventSelector example, and the interaction semantics of event_selector overriding event_type/status. That is real added meaning over the already-documented 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?

States a specific verb and resource (lists Dynatrace events) plus the event taxonomy it covers — deployments, restarts, Kubernetes, availability/anomaly, custom info — and names the distinguishing scoping fields. An agent can tell it apart from list_problems and get_entity without opening any 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?

Explicitly frames the use case ('what changed' around a breakage) and routes to the right follow-ups (get_entity, service_overview, list_problems for the same window). It stops short of an explicit exclusion, e.g. when to prefer pod_events for pod-scoped Kubernetes events, so it is clear context rather than full when/when-not coverage.

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

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

With no annotations, the description carries the full burden and does disclose a non-obvious execution trait: it runs through the Dynatrace Bridge browser extension in the user's logged-in browser, plus explicit failure handling ('report the error to the user; do not try to open browser tabs'). It doesn't discuss pagination/truncation semantics beyond what the schema says, which keeps it below a 5.

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 tight sentences front-load what is returned, then route to follow-ups, then cover the browser-extension execution caveat. No filler, and the most important information (the resource and its fields) comes first.

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 7-parameter, zero-required listing tool with no output schema and no annotations, the description covers the resource, the returned fields, the parameter interplay, the sibling alternatives, and the unusual browser-extension runtime. An agent has everything needed 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%, so the baseline is 3; the description rises above it by adding parameter relationships and provenance the schema does not state — notably that `workload` and `name` can be combined, and that `workload` ids/names come from `list_workloads`. It still leaves the time-window parameters entirely to 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+resource (lists Kubernetes pods) and enumerates the exact payload returned: phase, node, IPs, restart count, age, CPU/memory requests and limits, and containers with ids. It also anchors the concept to the Dynatrace entity type CLOUD_APPLICATION_INSTANCE, which sharply separates it from siblings like list_workloads or list_services.

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 tells the agent how to drive it ('Pass `workload` ... and/or `name`') and where the workload id comes from, then names three concrete follow-ups (pod_resources, pod_events, process_runtime) for adjacent needs. That is real routing guidance rather than implied usage.

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

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

With no annotations, the description carries the full behavioral burden and does well: it discloses that execution goes through the Dynatrace Bridge browser extension in the user's logged-in browser, that a failure must be surfaced rather than worked around, that an open problem starting before the window is still included, and that truncation is reported ('The output says how many were omitted'). It does not cover permission requirements or rate/response-time behavior, so it falls short of a 5.

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 paragraphs ordered by importance: what it returns, how to filter, where to go next, then the execution caveat. Dense but front-loaded and free of filler; the returned-field enumeration is long, though it substitutes for a missing output schema and therefore earns its space.

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 10-parameter, read-only listing tool with no output schema, the description compensates by enumerating return fields, explaining the time-window resolution across time_from/time_to/minutes_lookback, covering the environment default and pointing at dynatrace_bridge_status for environment names. Nothing an agent needs to call it correctly 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 baseline is 3. The description largely restates filter semantics already documented per-parameter (status, impact_level, severity, entity_selector, text, time window), adding only the enumerated returned fields and a minor gloss on text matching that is slightly narrower than the schema's own wording ('id, title and entity names' vs. the schema's inclusion of root cause).

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 ('Lists the problems Dynatrace (Davis) raised that were active in the time window') and enumerates the exact fields returned, so the agent knows what it gets without opening a schema. It also distinguishes itself from the sibling get_problem, which is explicitly named as the follow-up for evidence.

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?

Gives an explicit entry-point instruction ('Start here for "what is wrong right now" or "what happened at that time"') plus the hand-off rule ('Follow up with get_problem (pass the P- id)'). Failure handling is also prescribed: report the error rather than falling back to browser automation.

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

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

With no annotations present, the description carries the full burden and does so: it discloses the unverified internal endpoint layout, that unrecognized fields are dumped under `details` so nothing is hidden, that execution goes through the Dynatrace Bridge browser extension in the logged-in browser, and what to do on failure (report, don't automate a browser).

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 compact paragraphs, front-loaded with purpose then usage then execution caveat; every sentence is load-bearing, though the middle paragraph's tool list is dense enough that some readers may skim it.

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?

No output schema, so the description compensates by describing the returned columns and the `details` catch-all, plus the environment-resolution caveat pointing at dynatrace_bridge_status. An agent has everything needed to call this 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 all six parameters are already documented in the schema; the description adds little parameter-level meaning beyond the window concept already covered by time_from/time_to/minutes_lookback. 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 ('Lists the process crashes Dynatrace detected') and enumerates the returned columns (time, process, host/pod, signal/exception, entity ids), which distinguishes it from generic listing siblings like list_events or list_problems.

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 gives triggering conditions ('a service became unavailable, a pod restarted, or a problem mentions a crash') and names concrete follow-ups (get_process/get_host for ids, pod_events for K8s restarts, list_problems for the same window), leaving nothing 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?

With no annotations, the description carries the burden and does disclose a genuinely non-obvious execution trait: the tool runs through the Dynatrace Bridge browser extension in the user's logged-in browser, with explicit failure handling (report the error, do not open tabs or use browser automation). It also describes row content and that output states omitted rows. It does not cover auth/permissions or rate limits, so it falls short of a 5.

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

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

Four tight paragraphs, front-loaded with what it lists and what sort to use; the browser-extension caveat is correctly placed last. Slight redundancy with the schema (re-listing sort criteria that are already an enum) costs it a point.

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

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

For an 18-parameter tool with no output schema and no annotations, the description covers row composition, per-service-type row semantics, the required `service` lookup path, and the extension dependency. Missing details are minor and schema-covered (limit/pagination, time-window defaults), so it is nearly complete.

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

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

Schema coverage is 100%, so a 3 is the baseline. The prose still adds meaning the schema cannot: the default sort and why each sort value matters, the cross-tool contract that a printed row id or name can be passed as `request` by other tools, and how `service`/`request` resolve by name vs id. That is real semantic value on top of 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 (list the requests/statements/hosts of one service) and immediately defines what a 'row' means for web/method, database, and 'Requests to unmonitored hosts' services. It explicitly differentiates itself from trace_statistics, cron_job_statistics and list_services, so an agent can route without opening siblings.

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

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

Gives concrete when-to-use guidance tied to the sort argument ('which endpoint is slow', 'costs the most time', 'fails'), names the alternative for the cross-service question (trace_statistics) and for cron jobs (cron_job_statistics), and points to list_services for discovering the required `service` value.

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

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

With no annotations, the description carries the burden and does disclose meaningful behavior: it runs through the Dynatrace Bridge browser extension in the user's logged-in browser, and on failure the agent should report the error rather than fall back to browser automation. It also warns that several services can share a name (one per process group), which affects interpretation of results. It does not cover rate limits or return/pagination detail beyond what the schema's `limit` already says.

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 action and the returned metrics, then filtering, then investigation recipes, then the runtime caveat about the browser extension. Three dense paragraphs where each sentence earns its place; slightly long but not padded.

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?

No output schema exists, and the description fills that gap by enumerating the returned metrics and noting that the response header resolves the absolute UTC window and that `limit` reports omitted counts. All 10 parameters are documented, and it routes the agent to `dynatrace_bridge_status` for environment names the description cannot list.

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 prose adds meaning beyond the schema: partial matching for `service_type` ('a part such as "database" is enough'), case-sensitivity of `tag` versus case-insensitive `name`, and that all sort keys rank highest-first with `name` as the exception. It also notes the duplicate-name/id disambiguation, which the schema does not.

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 ('Lists the services Dynatrace monitors') plus the exact metrics returned (avg/p90 response time, failure rate, request count, RPM). It distinguishes itself from siblings by naming `service_overview` as the follow-up for a single service and positioning itself as the entry point for service investigations.

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 when-to-use: find a service id, identify slow/failing/busy services, and start any service investigation. It maps concrete intent to arguments ('which services are slow → sort: "response_time"') and names the alternative (`service_overview`) for drilling into one service.

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, so the description carries the full burden—and it does: it explains the browser-extension execution model, the fetch_limit-then-sort two-stage retrieval, the 'slowest among newest fetched' caveat, default ordering, partial-window/sampling warnings, and the 'do not use browser automation' failure path. This is exactly the non-obvious behavior an agent needs.

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, then filters, then per-trace fields, then the retrieval-limit mechanics, then the bridge runtime caveat. Dense but every block earns its place; it could be trimmed slightly (some per-trace fields enumerated) but no sentence is pure filler.

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

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

Given 19 params, no output schema, and no annotations, the description covers the return shape (list of trace fields including the traceId/callURI get_trace needs), the tricky fetch_limit/limit interaction, and the execution environment. An agent has everything needed to call it correctly and interpret results.

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 already 100% (baseline 3), but the description adds cross-parameter semantics that the schema does not: e.g. 'request name needs service', 'url_contains works with or without service', 'minutes_lookback is ignored when time_from is given', and the fetch_limit vs limit distinction. These add genuine value beyond field-level docs.

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?

Starts with a specific verb+resource ('Lists individual traces (PurePaths)') and scopes it precisely ('requests of one service, or of the whole environment when service is omitted'). It also name-drops the sibling get_trace as the follow-up, distinguishing it from trace_statistics and analyze_* tools.

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 states when to use it ('find concrete slow or failed requests, then open one with get_trace') and the description enumerates the alternative filters and quirks (url_contains vs request for non-web) in the param docs. Routing is unambiguous for the main follow-up 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?

With no annotations, the description carries the full burden and delivers non-obvious behavior: the tool runs through the Dynatrace Bridge browser extension in the user's logged-in browser, and on failure the agent should report the error rather than fall back to browser automation. It does not state permission/auth requirements, rate limits, or explicitly that it is a read-only operation, so it stops short of a 5.

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 tight paragraphs: capability/returns first, filtering and usage second, transport caveat third. Every sentence carries information, with the most decision-relevant content front-loaded. Slightly long but not padded.

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?

No output schema exists, and the description compensates by detailing the returned fields (workload type, namespace, cluster, running vs desired pods, CPU/memory against requests and limits). With 8 optional params and a documented transport dependency, the main remaining gap is the absence of explicit auth/permission 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 documents all 8 parameters including defaults, formats, and edge cases. The description restates filter semantics (case-insensitive substring name, exact namespace, cluster name or KUBERNETES_CLUSTER id) but adds nothing the schema does not already contain, so the baseline 3 applies.

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

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

States a specific verb and resource ('Lists Kubernetes workloads') and enumerates exactly which kinds (deployments, stateful sets, daemon sets, jobs) and the Dynatrace entity type. It also names what is returned (namespace, cluster, running vs desired pods, CPU/memory vs requests/limits), so an agent can distinguish it from sibling list tools 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?

Explicitly names the sibling tools this feeds ('list_pods', 'pod_resources', 'pod_events', 'process_runtime') and the two conditions to reach for it (finding a workload id, spotting workloads near their limits). It also gives filter semantics (name substring, namespace exact, cluster name-or-id), leaving no inference about when 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?

With no annotations, the description carries the full burden and discharges it: it explains why the default window is 15 minutes (large call trees for busy process groups), what happens when profiling is unavailable ('the tool says so and what to do'), and an operational constraint — it runs through the Dynatrace Bridge extension in the user's logged-in browser, and on failure the agent must report the error rather than use browser automation.

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 what the tool returns, then usage triggers, then caveats and the browser-extension constraint in short, scannable paragraphs. The opening sentence is a long run-on listing output sections, but every sentence still carries information an agent needs.

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 7-parameter, no-annotation, no-output-schema tool, the description covers output shape, failure modes with remediation, environment resolution, and an operational constraint — everything needed to call it correctly and interpret its outcome.

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 description adds semantic value beyond the schema: it frames 'survivors_only' as leak/heap-growth candidates and explains the 15-minute default as a deliberate size-management choice. Time-window semantics and the environment default are left to 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?

Specific verb+resource ('Shows where a process group allocates memory') with the exact output sections enumerated (allocated/surviving bytes, allocation per API, top methods with callers and object types, most allocated types). This is clearly distinguishable from siblings like method_hotspots and cpu_by_process_group, which cover different signal types.

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 trigger conditions are given: 'high garbage-collection time or memory growth', plus 'survivors_only: true' for leak/heap-growth candidates. It also points to cpu_by_process_group to discover which process groups support memory profiling. It stops short of naming a rival tool to prefer for adjacent questions, hence 4 rather than 5.

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

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

With no annotations, the description carries the disclosure burden and does so well: it explains that the tool runs through the Dynatrace Bridge browser extension in the user's logged-in browser, that an unconfigured environment resolves to a default, that browsers/tab automation must not be attempted on failure, and that numbers are stack samples rather than milliseconds. It does not mention rate limits, auth failure modes beyond 'report the error', or result-size behavior beyond the limit defaults.

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, then structured in short paragraphs covering views, state defaults, scoping, and the browser-extension caveat. Every sentence carries information, though the length is on the heavier side and a couple of sentences (e.g. the environment caveat) could be tightened.

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?

No output schema exists, yet the description describes the return shape (sample share per API group and thread state, then hot methods, plus omitted-count reporting) and the window-resolution behavior. For an 11-parameter, no-annotation, complex analysis tool, an agent has everything it needs to invoke it and interpret results.

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 description adds real meaning the schema lacks: flat view ranks by self share while also reporting total share including callees, tree view is pruned at min_share_percent, and active states are counted by default with include_waiting opting waiting threads in. It also states the resolved absolute UTC window is echoed in the response header.

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 — showing which methods consume time, broken down by sample share per API and per thread state — anchored to a named data source (Dynatrace code-level stack samples). It is plainly distinguishable from siblings such as memory_allocation_hotspots, cpu_by_process_group and thread_analysis.

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?

Gives concrete routing rules: 'Pass exactly one of service or process_group', where the ids come from (list_services, trace_statistics, cpu_by_process_group), and an explicit follow-up ('use thread_analysis for the thread groups behind the samples'). It stops short of explicitly excluding the other hotspot-style siblings, so it's clear context rather than full when/when-not guidance.

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

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

No annotations are provided, so the description carries the full burden, and it does substantial work: it discloses the aggregation semantics (identical events collapsed by reason and message, with count and first/last time, newest first) and the unusual execution path (runs through the Dynatrace Bridge browser extension in the user's logged-in browser) plus failure handling guidance. It stops short of stating the operation is read-only/non-mutating or any permission requirements, which is the remaining gap for a zero-annotation 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?

Three short paragraphs, front-loaded with what the tool returns, then the selection rule, then the environment caveat. No filler sentences, and the most decision-relevant facts (what it lists, which param to pass, what it depends on) come first.

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 7 parameters, zero required, no output schema, and no annotations, the description covers the return shape (grouped events, count, first/last timestamp, ordering, omitted count), the window resolution behavior, the environment default, and points to dynatrace_bridge_status for environment names. An agent has everything needed to call it correctly without guessing.

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 a real constraint the schema does not encode (required list is empty): exactly one of workload or pod must be passed, and a name matching several entities returns candidates rather than guessing. That mutual-exclusivity rule is the kind of semantics the schema alone would not convey.

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 ('Lists the Kubernetes events Dynatrace recorded') and then enumerates the concrete event categories (probe failures, container kills/back-offs, scheduling, image pull, mount failures, spec changes). This clearly distinguishes it from siblings like list_events and pod_resources without needing the schema opened.

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?

Gives an explicit selection rule ('Pass exactly one of workload or pod') and a concrete trigger condition ('Use it after pod_resources shows restarts, OOM kills or a pod that is not running, with the window narrowed to that time'), naming the sibling that precedes it. Nothing about when to reach for this rather than alternatives is 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?

No annotations, so the description carries the full burden and does so well: it discloses the output shape (findings plus summarised min/avg/max/last/trend series), the mutual-exclusivity constraint, and the unusual execution path (Dynatrace Bridge browser extension in the logged-in browser) with explicit failure handling guidance. It omits any payload-size or pagination caveats, but max_series in the schema partly covers that.

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 the 'start here' triage signal, then parameters, then the execution caveat. It is dense and long for three paragraphs, but each paragraph has a distinct job (what it returns, when to use it, how it runs) and none is filler.

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

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

With no output schema and 7 parameters, the description compensates by explaining the return format (findings plus per-pod/per-container summarised series) and the routing to sibling tools. An agent has everything needed to select and invoke it, including the browser-extension dependency and failure protocol.

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 description adds real meaning beyond the schema: the schema declares no required fields while the description states 'Pass exactly one of `workload` or `pod`', a constraint absent from the structured data. It also frames time_from/time_to as a way to narrow around a peak.

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 ('Shows the resource behaviour of the pods of a Kubernetes workload, or of one pod') and enumerates the exact metrics returned (CPU usage, throttling, RSS/working set, OOM kills, restarts). It is clearly distinguishable from sibling tools like pod_events and process_runtime, which it names as the next steps rather than duplicating.

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 says 'Start here for why does this pod restart / get OOM-killed / run slow', names the alternative tools to try afterwards ('pod_events', 'process_runtime'), and states the selection constraint 'Pass exactly one of `workload` or `pod`'. It even points to `list_workloads` for finding inputs.

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

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

With no annotations, the description carries full burden and delivers: it discloses the per-technology metric behavior, the summarised-series return shape (min/avg/max plus a table over time), the exactly-one-selector constraint, and the execution channel plus failure protocol ('runs through the Dynatrace Bridge browser extension ... report the error to the user; do not try to open browser tabs or use browser automation instead').

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, then the mutually-exclusive selector rule, then when-to-use, then the execution-channel caveat. The long metric enumeration is justified since there is no output schema, but it is the one densest block in an otherwise tight three-paragraph description.

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?

No output schema exists, yet the description explains the return shape (summarised series with min/avg/max, time, last, trend, and a table over time), the selector constraint, defaults, and the failure path. Nothing an agent needs to invoke it correctly 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 baseline is 3, but the description adds a selection rule the schema does not express: 'Pass exactly one of pod, workload, process_group or process'. It also explains the default/omission behavior for environment via dynatrace_bridge_status, though time window semantics are largely already in the schema.

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

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

States a specific verb and resource ('Reports runtime metrics of the processes ... running in a pod, a workload or a process group, or of one process') and enumerates the technology-specific metrics returned. It is clearly distinguishable from pod_resources (host/pod resource view) and get_process (callers/callees/hosted services), which are named in the 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?

Gives an explicit trigger ('Use it when pod_resources shows memory growth or CPU saturation and you need to know whether heap, GC or the event loop is the cause') and an explicit follow-up ('Follow up with get_process for callers, callees and hosted services'). The alternatives are named rather than implied.

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

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

With no annotations, the description carries the full burden and does well: it discloses execution through the Dynatrace Bridge browser extension in the logged-in browser, instructs on failure handling (report the error, do not automate a browser), and explains unit-conversion behavior including the raw-value fallback and the caveat that transformations like ':rate' change units. It does not spell out auth/permission prerequisites or rate limits, so it falls just short of 5.

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?

Long but well-organized and front-loaded: purpose and return shape come first, then selector syntax, scoping, resolution, and the execution caveat. The bulleted examples earn their space as they are the core invocation skill, though the description is on the edge of verbose.

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

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

For an 8-parameter tool with no output schema, the description still explains the return summary, unit handling, the browser-extension execution path, and failure behavior, while the input schema covers every parameter. An agent has everything needed to invoke and interpret 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 coverage is already 100%, so baseline is 3, but the description adds real meaning: the metric selector language with transformation examples, resolution point-spacing semantics ('Inf' for a single value, default chosen by Dynatrace), and how the time window resolves. This goes beyond the schema's terse per-parameter strings.

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 ('Runs a Dynatrace metric query') and immediately clarifies scope ('the data behind any chart') plus exactly what is returned (min/avg/max, timestamp, last value, trend, table). It is unmistakably distinct from the sibling discovery tool find_metrics, which it explicitly names.

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?

Gives concrete usage guidance: how to build a selector with three worked examples, the ':names' tip, entity scoping via entity_selector, resolution semantics, and routes metric-id discovery to find_metrics. It stops short of explicit when-not-to-use guidance against analytical siblings such as analyze_response_time or service_overview.

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

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

With no annotations, the description carries the full burden and does so: read-only ('The bridge cannot change settings'), secret masking, compact nested-list output format, and the browser-extension dependency with explicit failure handling. This is unusually 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?

Front-loaded with purpose, then organized by mode, then caveats. Every sentence earns its place: mode selection, scope, effective semantics, output/masking, and failure handling. No redundancy with the parameter list.

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 7-parameter, no-output-schema tool, the description supplies what's missing elsewhere: print format, masking, omission reporting, scope defaults, and the bridge failure protocol. An agent has everything needed to invoke it correctly.

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

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

Schema description coverage is already 100%, so the baseline is 3. The description nonetheless adds semantics the schema lacks, such as examples of schema ids, the meaning of entity-level overrides for `scope`, and what `effective: true` actually returns (inherited values and defaults).

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 ('Reads Dynatrace configuration (Settings 2.0)') and enumerates the categories covered (alerting profiles, anomaly detection thresholds, failure detection rules, etc.), which cleanly separates it from observability siblings like get_problem or query_metrics. The read-only scope is stated up front.

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 declares the two operating modes and the condition that selects each: without `schema` it lists schemas, with `schema` it prints configured objects at `scope`. It also explains narrowing via `search`, the `effective` flag behavior, and the fallback when the bridge fails ('report the error to the user; do not try browser automation').

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

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

With no annotations, the description carries the full burden and does so: it discloses the unusual execution path (runs through the Dynatrace Bridge browser extension in the logged-in browser) and prescribes error handling ('report the error to the user; do not try to open browser tabs'). It also describes what the output contains per caller, which is behavioral context the schema cannot supply.

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, then usage, then filter guidance, then the runtime caveat, so an agent can stop reading early. Slightly long because the filter list partly echoes schema-documented parameters, but no sentence is 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 19-parameter tool with no annotations and no output schema, the description covers purpose, selection criteria, parameter interactions, return contents, sibling alternatives, and the browser-extension execution constraint. An agent has everything needed to call 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 coverage is already 100%, so the baseline is 3, but the description adds real interpretive value: it groups the 'shared trace filters' and gives concrete usage examples (`request` backtraces one endpoint, `failed: true` only failed calls) that clarify how parameters combine rather than merely restating them.

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 ('Shows who calls a service ... the upstream caller tree, level by level') and even sketches the shape of the returned caller data. It is clearly distinguishable from siblings like service_flow and statement_callers.

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 says what problem it solves ('find which upstream service, endpoint or job causes the load or the failures') and names the correct alternative for a related case ('For one SQL statement use `statement_callers`'), plus a follow-up path with `list_traces`.

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

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

With no annotations, the description carries the burden and does so thoroughly: it discloses output content per node, the fact that execution goes through the Dynatrace Bridge browser extension in the user's logged-in browser, and explicit failure handling ('report the error to the user; do not try to open browser tabs or use browser automation'). This is exactly the operational context an agent needs and cannot get from 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?

Three tight paragraphs: output shape first, then usage and follow-up routing, then execution-model caveats. Front-loaded with what the tool returns, and no sentence is redundant despite 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?

There is no output schema, but the description enumerates the per-node metrics (response-time contribution, request share, calls per calling request, average time per call, call count, failed calls) and the tree structure, which fully compensates. Combined with the execution-model note, an agent can call and interpret this 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% and the schema documents all 18 parameters in detail, so the baseline is 3. The description restates only `service` (id or name) and `max_depth`, adding no syntax or format detail 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?

States a specific verb and resource ('Shows what a service calls ... downstream call tree of services, databases and external hosts as an indented tree') and describes the exact output shape. It implicitly distinguishes itself from the sibling service_backtrace by naming that tool as the 'opposite direction'.

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?

Gives an explicit use case ('see which dependency a slow or failing service spends its time in') and names follow-up alternatives with their conditions: analyze_response_time, recursive service_flow on a downstream id, top_database_statements for database nodes, and service_backtrace for the reverse direction.

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

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

With no annotations, the description carries the full burden and does well: it discloses the execution model (runs via the Dynatrace Bridge browser extension in the user's logged-in browser), the required error-handling behavior, and the ambiguity policy (a name matching several entities returns candidates instead of guessing). It does not explicitly state that the call is read-only/side-effect free, which is the only meaningful 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 with the one-sentence summary before any enumeration, and each subsequent paragraph has a distinct job (what you get, how to call it, where to go next, execution caveat). The payload enumeration in sentence one is long, but it is load-bearing information for judging whether this tool fits a need.

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 must say what comes back, and it does — latency percentiles, failure rate, throughput, trend, upstream/downstream relationships, infrastructure, and affected problems. Combined with the drill-down map and the browser-extension caveat, an agent has everything needed to call it and interpret the result.

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 prose reinforces the `service` id-vs-name ambiguity rule and the window resolution behavior, but these are already documented in the schema; the description adds no syntax, format, or constraint detail beyond it (e.g. no extra guidance on relationship_limit tradeoffs).

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 opening sentence states a concrete verb+resource with scope ('Everything about one service in one call') and then enumerates the exact payload categories: type/technology/tags, latency percentiles, failure rate, throughput, relationships, process groups/hosts/k8s, and problems. An agent can distinguish this from get_entity, list_services, or analyze_failures without opening any 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?

It explicitly routes discovery through `list_services`, then names the drill-down alternatives (`list_service_requests`, `list_traces`, `analyze_failures`, `analyze_response_time`, `service_flow`, `service_backtrace`, `get_problem`) and the condition for using each. It also states a failure-mode policy (report the error, do not fall back to browser automation), which is uncommon and valuable.

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

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

With no annotations, the description carries the full burden and does well: it discloses the default response_time_min_ms of 100, that a name matching several entities returns candidates instead of guessing, and the operational constraint that the tool runs through the Dynatrace Bridge browser extension with explicit failure handling ('report the error to the user; do not try to open browser tabs'). It omits any auth/permission requirements, which keeps it short of a 5.

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 and output shape, then the necessary inputs, then the follow-up and the browser-extension caveat. The middle sentence enumerating ten shared trace filters duplicates the schema and is the one slightly wasteful element, but overall it is tight and well ordered.

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 17-parameter tool with no output schema, the description compensates by naming the columns returned and the ordering, plus the follow-up tool and the runtime environment caveat. Nothing critical is missing for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents all 17 parameters in detail. The description restates only the required trio and the default of response_time_min_ms, adding little 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?

The first sentence gives a specific verb and resource ('Lists the slow executions of one SQL statement on a database service'), states the ordering ('slowest first'), and enumerates the returned columns. It is clearly distinguishable from siblings such as top_database_statements and statement_callers.

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 states the required inputs, tells the agent where the statement id comes from ('id from `top_database_statements`, or a part of the SQL text'), and prescribes the follow-up step via get_trace with the returned traceId/callURI. It does not explicitly contrast itself with statement_callers or top_database_statements, but the context is otherwise 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?

With no annotations the description carries the full burden, and it does so well: it discloses the browser-extension dependency, instructs the agent to report failures rather than attempt browser automation, notes that an ambiguous service name returns candidates instead of guessing, and mentions the output reports how many items were omitted. It does not cover auth requirements or return-format details beyond counts and the tree.

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

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

Four tight paragraphs are front-loaded with purpose, then inputs, then follow-ups, then a runtime caveat. The opening sentence is dense with enumerated outputs but still readable; nothing sentence-wise is wasted, though the enumeration could be trimmed slightly.

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

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

For an 18-parameter trace tool with no output schema, the description covers purpose, key filter semantics, follow-up routing, and the browser-bridge operating constraint. There is no output schema, yet the description does describe the shape of the result (tables, counts, caller tree) and truncation behaviour, leaving only minor gaps around permissions and exact result 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: it groups the shared trace filters and gives a concrete semantic example (response_time_min_ms backtraces only the slow executions), and clarifies that `statement` accepts either a top_database_statements id or a text fragment. That is useful clarification beyond the schema's field-level text.

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 first sentence names a specific verb and resource – tracing what causes one SQL statement – and enumerates the exact output: executing services, requests, background tasks, cron jobs with SERVICE_METHOD ids, counts, and the upstream caller tree. It also names the sibling tools that feed it (top_database_statements) and that continue the workflow (slow_statement_executions, list_traces), so an agent can place it precisely among siblings.

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

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

It states the two required inputs and where their values come from, explains that shared trace filters narrow the analysed requests, and explicitly routes follow-up work to slow_statement_executions or list_traces with the right parameter wiring. It lacks an explicit when-not-to-use statement (e.g. vs service_backtrace or service_flow), so it stops short of a 5.

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

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

With no annotations, the description carries the full burden and does well: it discloses the browser-bridge execution dependency, instructs the agent to report rather than work around failures, and explains ranking behavior ('ranked by its samples' vs 'ranked by CPU time'). It does not cover permissions, rate limits, or result-size behavior, keeping it at 4 rather than 5.

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 paragraphs, front-loaded with purpose, then usage, then the environment caveat. Every sentence carries information, though the browser-bridge paragraph is slightly verbose relative to the rest.

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

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

For an 8-parameter tool with 100% schema coverage and no output schema, the description supplies the missing operational context: process-group name resolution ambiguity, environment defaults tied to dynatrace_bridge_status, and the bridge execution model. Only a brief note on expected result scope 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 baseline is 3. The description goes beyond the schema by explaining the state filter's semantics and giving a concrete enum usage example ('LOCK for lock contention') that the schema enum alone doesn't convey, and clarifying that output states how many groups were omitted.

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 ('Analyses the threads of a process group'), names the underlying capability (Dynatrace continuous thread analysis), and enumerates what the output contains (state counts, thread groups ranked by CPU time). An agent can distinguish this from siblings like cpu_by_process_group or method_hotspots without opening a 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?

Gives explicit diagnostic scenarios ('see whether a process is CPU-bound, blocked on locks or stuck in I/O') and an example of when to use the state filter ('LOCK for lock contention'), plus a named follow-up tool for methods. It stops short of stating when NOT to use this versus the sibling process tools, which is the only gap.

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

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

No annotations, so the description carries the full burden and does: it discloses the 100-statement cap by total time (and that other sorts only re-order that set, so a rare slow statement can be missing from 'slowest'), that combining costs two analysis requests, that SQL text is truncated, and that it runs through the Dynatrace Bridge browser extension with a failure instruction instead of automation.

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 the 'which SQL is slow' framing are front-loaded, and the paragraphs are ordered by importance (purpose, service semantics, sort caveat, follow-ups, transport caveat). It is dense rather than bloated, though the wall of filter-related detail makes it longer than a reader strictly needs before the first call.

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 19 optional parameters, no annotations and no output schema, the description still tells the agent what comes back (per-statement metrics and ids), when output is incomplete (the 100-statement cap), the default behaviour without `service`, and which tools continue the investigation. Nothing essential for a correct call 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%, so the baseline is 3, but the description adds semantics the schema does not: how `sort` interacts with the 100-statement cutoff, how `service` names combine or behave like ids, and that `full_sql` restores the truncated text. Those interactions are the parts an agent would otherwise get wrong.

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?

Opens with a specific verb and resource ('Lists the SQL statements of a database') and enumerates exactly what each row contains (total time, avg, median, p95, slowest execution, execution count, statement id). The tagline 'The tool for which SQL is slow / expensive' makes the intent unmistakable and separates it from siblings like statement_callers and slow_statement_executions.

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 states the branches: pass a service name to get all same-named services combined by statement text, pass an id for one alone, and call it with no `service` to list database services. It names both follow-up tools and what to pass them (`service` plus the statement id), and explains when the shared trace filters apply.

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, so the description carries the full burden and does well: it discloses the browser-extension/logged-in-browser execution path, the failure-handling rule (report to user, no browser automation), the unverified reading of the Dynatrace aggregate columns, and that omitted classes are reported in the output. It does not explicitly state that the call is read-only, but 'ranks analysed requests' makes that clear in 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?

Front-loaded with purpose, then usage/routing, then execution caveat — a logical order. The first paragraph is dense and the aggregate-column caveat is wordy, but every sentence carries information an agent needs; no 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 an 18-parameter tool with no output schema and no annotations, the description supplies the result shape (classes, count, aggregates, top services with ids), the scoping rules and the failure mode. Remaining per-parameter detail is fully covered by the schema, so the definition is complete enough to call 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 coverage is 100%, so the baseline is 3; the description nonetheless adds value beyond the schema by enumerating the shared trace-filter set, clarifying the service/no-service branch, and explaining the meaning of the aggregate columns the parameters feed into. Marginal but real lift over the already-thorough 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 — 'Ranks the exception classes thrown in traced requests' — and immediately qualifies the notion of 'top' by naming the aggregates used (LOAD, AVERAGE, MAX). This is clearly distinguishable from siblings like analyze_failures, list_traces and top_database_statements.

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 positions itself as the entry point ('Start here for which exceptions occur most'), states the no-service vs with-service branches, and names two concrete follow-ups (analyze_failures for a failing service, list_traces with raw_filters for the traces). Nothing is left to inference.

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