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

Annotations only declare readOnlyHint=true, but the description goes well beyond that: it explains the fleet-majority baseline derivation algorithm, that it functions without a declared gold image, that injected endpoints skip live collection, and that truncated results require re-running with a higher limit. This is exactly the behavioral context the annotation 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-loads the [READ] tag and the one-line purpose, then moves to usage, args, return shape, and a concrete example. Given the absence of schema descriptions and an output schema, every block earns its place 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?

With no output schema and 0% parameter coverage, the description compensates fully by documenting the return dict fields (baselineSource, driftedCount vs driftedEndpoints.items, truncation) and the truncation recovery path, so an agent has everything needed to invoke and interpret the call.

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

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

Schema description coverage is 0%, so the description must carry the load, and it does: all five parameters (baseline, fields, endpoints, target, limit) are explained with their semantics and defaults, including what omitting baseline triggers and that endpoints is an injection bypass of live collection.

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 — reporting endpoints whose fields have drifted from a baseline — and narrows the concept with '(patch/agent/OS/profile)'. An agent can distinguish this drift analysis from patch_status or patch_compliance, though no sibling is named explicitly, so it falls short of full sibling differentiation.

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

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

Gives clear operating context: it answers 'which endpoints have drifted from the fleet?' and explains that passing 'endpoints' yields pure analysis while a 'target' pulls live inventory, and that it works before any gold image exists. It does not, however, state when to prefer this over patch_compliance or endpoint_health_score.

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

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

Annotations only say readOnlyHint=false, idempotentHint=false, destructiveHint=true; the description adds substantial extra context the annotations cannot carry: it discloses that the prior profile is captured before switching, that an undo record and audit trail are produced, and exactly how dry_run differs from the real call. This is well beyond the structured hints.

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

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

The write/risk tag and the one-line purpose are front-loaded, the behavior paragraph follows, and the Args block closes it. Every sentence earns its place and none restates schema or annotation content verbatim.

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 high-risk write tool with no output schema, the description supplies the missing pieces an agent needs: reversibility, the automatic undo/audit behavior, and precise dry-run semantics. Nothing required to invoke it correctly is absent.

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

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

Schema description coverage is 0%, so the description carries the full burden, and it documents all four parameters, including the useful cross-reference that endpoint_id comes from endpoint_list and that target may be omitted for the default. The explanations are brief (e.g. profile_id is just 'Config profile to assign'), leaving a little room for richer semantics.

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

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

The description states a specific verb and resource ('Assign a config profile to an endpoint') and immediately qualifies the operation with [WRITE][risk=high] and '(reversible)'. An agent can distinguish this mutation from read siblings like endpoint_get or endpoint_list 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 gives concrete guidance on the preview path (dry_run=True resolves the same path, reads the same before-state, refuses on the same grounds) and explains the undo relationship, which frames when to use this versus just writing. It does not, however, name an explicit alternative tool or state when NOT to use this call.

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

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

The readOnlyHint annotation already declares this is a safe read, and '[READ]' merely repeats it. The description does add genuine context with 'normalised to the stable shape' (a return-shape promise in the absence of an output schema) and the target-default behavior, but says nothing about not-found errors or auth requirements.

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

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

Front-loaded one-line purpose followed by a compact args block; every element is functional. The redundant '[READ]' tag is the only waste, since the annotation already conveys read-only status.

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

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

For a simple two-parameter read with no output schema, the description covers the call mechanics and hints at the response shape. It stops short of describing failure modes, target resolution errors, or what 'stable shape' concretely contains.

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

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

Schema description coverage is 0%, so the description must carry the burden, and it largely does: endpoint_id accepts 'id (or uuid/mac)' and target is an endpoint-management target name from config with a documented default of omit-for-default. Only minor gaps remain, such as id format examples or validation behavior.

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

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

States a specific verb and resource ('One managed endpoint by id') plus the output guarantee ('normalised to the stable shape'), which is more than a restatement of the name. It references endpoint_list as the id source, giving implicit sibling separation, but never explicitly contrasts itself with that list tool.

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?

Usage is implied through 'endpoint_id ... as returned by endpoint_list', which tells the agent to obtain ids from the sibling list tool first. There is no explicit when-not-to-use guidance or handling for a missing/invalid endpoint.

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

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

Annotations only declare readOnlyHint=true; the description adds substantial behavioral context beyond that — the deduction model and cited 'reasons', the fact that no live pull occurs, the fleet-majority baseline derivation when no baseline is supplied, and the truncation/re-run semantics. This is exactly the extra context annotations cannot carry.

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-line purpose, then progressively deeper detail in Args/Returns/Example blocks. The length is justified by zero schema coverage and no output schema — each section supplies information the structured fields lack. No filler sentences.

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 fully documents the return dict shape (endpointsEvaluated, baseline, summary bands, worst.items, truncated, note) and explains the truncation workflow. Combined with the example, an agent has everything needed to call and interpret the tool.

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

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

Schema description coverage is 0%, so the description must carry the load, and it does: it enumerates the expected endpoint row fields (id, hostname, online, lastSeenHours, agentVersion, patchLevel), defines stale_hours semantics and default, explains baseline omission behavior, and defines limit's worst-first truncation. All four parameters are meaningfully specified.

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+output shape: 'Composite per-endpoint health score (0-100), worst endpoints first.' This is clearly distinguishable from siblings like patch_status, drift_report, and overview, which cover narrower or different scopes. An agent knows exactly what it gets back.

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 ('which endpoints are worst?') and states a critical usage constraint: it is pure analysis over injected inventory rows shaped like endpoint_list output, with no live connection. It doesn't explicitly name an alternative sibling (e.g., overview vs drift_report) for adjacent questions, which keeps it just 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?

The readOnlyHint annotation already covers the safety profile, and the '[READ]' tag merely restates it. The description adds no behavioral detail beyond the annotation — nothing about scope, pagination, or filtering for what could be a long list.

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 returned fields, followed by a compact Args line. No filler sentences; every element earns its place.

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

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

With no output schema, the description usefully names the returned fields, and the single optional parameter is explained. It stops short of covering list size/pagination behavior, but for a simple read-list tool it is largely 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 0% (the schema gives only 'string', default null), so the description carries the full burden and delivers: it explains target is an endpoint-management target name from config and that omitting it uses the default. That is meaningful guidance the schema lacks.

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 ('List all managed endpoints') and enumerates the returned fields, which implicitly separates it from single-endpoint siblings like endpoint_get and endpoint_health_score. No sibling is named explicitly, so it stops short of a 5.

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

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

The '[READ] List' framing and the target parameter note imply the listing use case, but there is no explicit when-to-use, when-not-to-use, or routing to alternatives such as endpoint_get or 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?

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds genuinely new context: prior online state is recorded for the audit trail, the action cannot be undone so no undo descriptor exists, and dry_run provides a preview path. It stops short of stating permission/auth requirements or rate limits.

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

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

The [WRITE][risk=medium] tag is front-loaded and the key constraint ('no safe inverse') appears in the first sentence. The dry_run rationale sentence is somewhat padded ('the whole value of asking first'), but the Args block is tight and 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?

With no output schema, the description would ideally mention the return shape of a dry_run preview (does it report online state and last-seen duration?), but it does cover safety, reversibility, param semantics, and preview behavior adequately for a destructive single-action tool.

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

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

Schema coverage is 0%, so the description carries the full burden, and it documents all three parameters: endpoint_id (with provenance 'as returned by endpoint_list'), dry_run (preview semantics), and target (config target name, omit for default). This is a solid compensation for the empty schema, though target's description is terse.

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 — 'Request an endpoint reboot' — and immediately scopes it ('no safe inverse'). It does not explicitly contrast itself with any sibling that performs a similar action, though its reference to endpoint_list for id provenance ties it into the toolset.

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

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

The description frames when to use dry_run=True ('knowing whether the endpoint is even online before committing'), which is useful implied usage. However, it never states when to reach for endpoint_reboot versus other endpoint-management siblings such as endpoint_assign_profile, so alternative-based guidance is absent.

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?

Goes well beyond the readOnlyHint annotation: it discloses that every flag carries a number rather than a verdict, that each returned list is a truncation envelope, that re-running with a higher limit is the remedy, and that stormCount is the full episode count. This is unusually rich behavioral context for a read-only 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?

Front-loads the purpose and the question answered, then structured Args/Returns/Example sections where nearly every line carries information. It is long, but the length is justified by the 8 params and the missing output schema; a slightly tighter Returns section would be the only trim.

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 8 undocumented params, the description supplies the full return envelope (stormCount, storms items shape, truncation flags, thresholds) and an example call, leaving nothing an agent needs to invoke or 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?

With 0% schema description coverage across 8 parameters, the description fully compensates: each arg is documented with its meaning, default, and semantics (e.g. window_s defines 'concurrent', min_concurrent defines a storm, sinced_hours applies only when sessions is omitted). The single biggest schema gap is closed.

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 specific verbs and resources: 'Detect login storms + rank the slowest login/boot contributors,' and frames the exact question it answers. This clearly distinguishes it from siblings like session_list or overview.

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?

Explains the two operating modes ('Pass sessions for pure analysis, or a target to pull live via session_list'), routing the agent between injected-data analysis and live collection. It stops short of explicit when-not/alternative guidance for cases like simple session lookup, so it does not reach 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?

The annotations already declare readOnlyHint=true, so safety is covered. The description adds the '[READ]' tag and the 'one-shot' behavioral note (single call returns a fleet summary), but it says nothing about cost, pagination, or data freshness — it is adequate rather than 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?

Front-loaded with the operation and a bracketed mode tag, then scope, then usage, then args. No sentence is redundant and there is 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?

Given one optional param, no output schema, and only a readOnly annotation, the description supplies purpose, triage role, and parameter meaning — enough to invoke correctly. Missing only minor details like whether output is paginated or refreshable.

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?

Single optional parameter with 0% schema description coverage, so the description must explain 'target'. It does: 'Endpoint-management target name from config; omit for the default', covering meaning and default behavior. It does not clarify accepted target formats, but the core semantics are conveyed.

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: 'One-shot fleet health: online/offline, stale endpoints, version spread.' It names exactly the aspects reported, so the agent knows the scope is an aggregate fleet snapshot rather than a per-endpoint call.

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 'Call this first to triage a managed-endpoint fleet before drilling into a specific endpoint, login storm, or drift report' — which names the alternatives (endpoint_get, login_storm_analysis, drift_report) and the sequencing rule. That is precisely the when/when-not guidance an agent needs.

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 readOnlyHint already covering safety, the description adds substantial behavior: injected-only operation requiring caller-supplied inventory, exact string-match semantics on patchLevel ('not a version-semantics parser'), and the truncation invariant that the rate is always over the whole fleet, never the capped list. These are non-obvious traits no annotation conveys.

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 verdict and the distinguishing contrast first, then Args, Returns, and an Example. Every section is useful, though enumerating the full return dict key list is somewhat list-y and could be trimmed without losing meaning.

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

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

No output schema exists, and the description compensates by documenting the return dict keys and the semantics of the rate computation, plus a concrete example. For a 4-param, no-output-schema tool this is fully complete.

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

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

Schema description coverage is 0%, so the description must carry the full load, and it does: endpoints (injected inventory rows, e.g. from endpoint_list), target_patch (omit to use fleet-majority), sla_pct (default 95.0), and limit (suggested default 200). Each parameter gains meaning beyond its bare title/default.

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 ('Patch-compliance SLA measure: % of the fleet on the target patch level') and explicitly distinguishes itself from its sibling by naming patch_status and explaining the reframing. An agent can tell it apart from patch_status without opening either 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?

Clearly routes the agent: it explains this is a compliance-verdict view of patch_status and that the operation is injected-only ('pass endpoints ... no live collection'), pointing to endpoint_list as the source. It gives strong context but stops short of an explicit when-not-to-use rule (e.g. when to prefer raw patch_status).

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

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

Annotations already declare readOnlyHint=true, and the [READ] tag reinforces it. Beyond that, the description discloses real behavioral detail: passing endpoints injects inventory rows and skips live collection, and behind.truncated signals the result was capped and should be re-run with a higher limit. This is substantive context that annotations alone would not convey.

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

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

The purpose line is front-loaded and the Args/Returns block is scannable and free of filler. It is slightly verbose for a four-parameter read tool, but each line carries distinct information rather than padding.

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 correctly documents the return shape: keys, the distinction between behindCount and the returned items, and the truncation contract. The main gap is that it never states how this differs from patch_compliance or drift_report, leaving sibling selection to inference.

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

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

Schema description coverage is 0%, so the schema provides only titles and defaults. The description compensates fully: it explains target_patch's fallback to the fleet-majority level, endpoints' injected-inventory behavior, target's config-driven default, and limit's default of 200. Every parameter gains meaning beyond the raw schema.

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

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

The description names a specific verb+resource: patch-level distribution plus identification of endpoints behind a target level. That is far more than a restatement of the name. It does not, however, distinguish itself from the sibling patch_compliance or drift_report, which an agent could plausibly confuse it with.

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?

Usage is implied through the arg semantics: omit target_patch to fall back to the fleet-majority level, and omit target to use the configured default. But there is no explicit when-to-use-this-vs-patch_compliance guidance, no exclusions, and no mention of prerequisites such as credentials or config availability.

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

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

readOnlyHint=true plus the '[READ]' tag make the safety profile explicit, so the description isn't carrying that burden. It adds value by listing the returned record fields, but says nothing about result ordering, pagination, volume limits, or what 'result' encodes, and the 1..720 hour cap is the only real constraint surfaced.

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 [READ] marker and resource, then a compact Args block covering both parameters. No filler sentences; every line carries information the 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 two-parameter read tool with no output schema, the description compensates by enumerating returned fields and documenting both args. It is nearly complete, though it omits ordering/pagination behavior and any note on whether the default target requires configured credentials.

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

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

Schema description coverage is 0% (the schema only carries titles and defaults), so the description must compensate and largely does: since_hours is documented with its range and default (1..720, default 24), and target is explained as an endpoint-management target name from config with the omit-for-default behavior. Only minor gaps remain, e.g., what a named target actually scopes.

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

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

The description names a specific verb+resource ('[READ] Recent login/boot sessions') and enumerates the returned fields (endpoint, user, login_ms, boot_ms, result), so the agent knows exactly what comes back. It distinguishes itself functionally from login_storm_analysis and endpoint_list by being a raw session feed, but it does not explicitly route against those siblings.

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

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

Usage is only implied: 'Recent login/boot sessions' plus a since_hours look-back window suggests a time-bounded recent-activity query, but there is no explicit when-to-use, when-not-to-use, or named alternative (e.g., login_storm_analysis for aggregated anomaly detection). The target arg's 'omit for the default' note gives minor contextual 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?

Annotations already declare readOnlyHint=false, destructiveHint=true and idempotentHint=false; the description adds real value on top by explaining that the actual risk tier lives with the dispatched inverse tool, that dry_run previews without executing, and that the token is single-use. It does not describe what the inverse dispatch returns or what failure looks like, so it is not maximally transparent.

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 [WRITE][risk=medium] tag and the core behavior/constraint sentences are front-loaded and efficient, and the Args block is compact. The Args list partially restates schema parameter names, but each entry adds meaning, so waste is minimal.

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 non-idempotent, destructive, three-parameter mutation with no output schema, the description supplies the missing context an agent needs: the risk marker, the once-only token rule, the preview path, and parameter sourcing. Only the result shape of the dispatched inverse call is left unspecified, which is a minor gap.

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

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

Schema description coverage is 0%, so the description carries the full burden and largely meets it: undo_id is traced to its source (undo_list or `_undo_id` in a write result), dry_run is defined as a preview flag, and target is explained as pass-through to the inverse tool. The pass-through semantics of `target` (when it is rejected or ignored) remain somewhat vague.

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 gives a specific verb+resource ('Apply a recorded undo') and explains the mechanism (dispatching its inverse tool), which separates it cleanly from the sibling undo_list that only lists tokens. An agent can immediately tell what this does that its siblings do not.

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 context of use (apply a token obtained from undo_list or an `_undo_id` in a write result) and offers dry_run=True as the preview path, plus the constraint that a token can be applied only once. There is no explicit when-not-to-use or named alternative beyond undo_list, so it stops just short of a 5.

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

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

Annotations only declare readOnlyHint=true, and the [READ] marker is consistent with that. Beyond annotations, it discloses the critical effectVerified semantic — false means the reversed change is PROBABLE, not confirmed — plus the 'one extra row fetched' truncation mechanism. This is exactly the behavioral 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 [READ] tag and purpose, then Args/Returns sections. Nearly every sentence earns its place, though the effectVerified and truncation paragraphs are dense and could be marginally 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 specifies the return shape ({undos[], returned, limit, truncated}) and explains truncated semantics. Combined with the parameter and behavioral notes, 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 coverage is 0%, so the description carries the full burden and does so: limit is documented with range (1..500) and default (50), and target is explicitly disclosed as unused/CLI-uniformity-only. No parameter is left ambiguous.

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 recorded, not-yet-applied undo tokens') plus ordering ('most recent first'), which immediately distinguishes it from the sibling undo_apply that consumes the tokens. An agent can tell what this returns 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 routes the agent: 'Use the undoId with undo_apply,' naming the sibling that performs the action. It also gives a conditional: when effectVerified is false, check live state before applying. This is explicit when-to-use and how-to-proceed guidance.

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