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

Annotations already declare readOnlyHint=true, and the description echoes this with a '[READ]' tag. The description adds the bucketing behavior (hour/day aggregation) which is useful beyond annotations, but says nothing about pagination, limits, default time range behavior, or what happens when since/until are omitted.

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

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

Front-loaded purpose in one sentence followed by a short parameter list. No filler. Could be marginally tighter but earns its place.

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

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

For a 3-param read-only analysis tool with no output schema, the description covers the basic contract but leaves gaps: no return shape, no default range behavior, no indication of what 'op counts' means concretely. Adequate but should do more given zero schema coverage.

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 burden and does explain since/until as ISO timestamps and bucket as hour/day. However, it doesn't state the default bucket ('day' per schema), doesn't say what happens when timestamps are omitted (both default to null), and doesn't clarify timestamp format expectations beyond 'ISO'.

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 ('Op counts bucketed by hour/day') and adds a scope qualifier ('monitoring-continuity evidence'), so an agent can tell what the tool produces. It is distinguishable from siblings like query_audit_events or coverage_summary, though no sibling is named explicitly.

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

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

No guidance on when to use this versus query_audit_events or coverage_summary, both of which also concern audit activity. 'Monitoring-continuity evidence' hints at a use case but gives no explicit when/when-not criteria.

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

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

The readOnlyHint annotation already establishes the safety profile, and the description adds useful behavioral context: the report covers high-risk writes with approver and rationale, defaults to high/critical-risk writes only, and is framed as a compliance artifact. It does not contradict the annotation and adds meaningful domain detail beyond what annotations provide.

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

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

The description is front-loaded with the tool's read-only nature and purpose, briefly lists compliance relevance, then documents arguments compactly. Each sentence carries useful information, with only minor redundancy between the [READ] marker and the overall read-report framing.

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 three-parameter, read-only reporting tool with no output schema, the description gives enough context to invoke it correctly: what the report contains, the compliance use case, and the semantics of every argument. It does not describe pagination or exact response structure, but the core invocation context is complete.

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

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

Schema description coverage is 0%, so the description must compensate. It documents all three parameters meaningfully: since/until as ISO timestamps that bound the reporting period, and high_only as a filter where True means high/critical-risk writes only and False means all writes, including its default behavior.

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

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

The description states a specific scope: a read-only report of high-risk write operations that includes approver and rationale, forming a change-approval trail. It clearly distinguishes the resource from generic audit/event siblings, though it does not explicitly name or contrast an alternative 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?

The description implies compliance reporting use via SOC 2, PCI, and HIPAA references, but it gives no explicit when-to-use guidance, no when-not-to-use conditions, and no named alternatives among the many sibling tools such as query_audit_events or activity_timeline.

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 assert readOnlyHint=true, so the safety profile is covered, but the description adds real behavioral context beyond it: it validates the cron line, starts no daemon, and flags the non-interactive master-password env note. That is useful operational detail the annotation does 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?

Front-loaded with the [READ] tag and the core deliverable, then a per-argument list. Every sentence earns its place; slightly verbose in the middle paragraph but nothing 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, the description correctly characterizes the return as a ready-to-paste cron line plus command, and documents all four inputs. An agent has enough to call it correctly; only the exact output shape and period grammar are left implicit.

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 burden and does so well: it enumerates valid framework values, defines cron as a 5-field expression with a default, gives period examples ('7d', 'last-7-days'), and explains sign as adding --sign. Only minor format ambiguity for period remains.

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+resource (composes/validates a crontab line and the exact `bundle generate` command) and immediately scopes it against the sibling generators: it is a hint/command composer, not an executor. '[READ] ... WRITES NOTHING and starts no daemon' cleanly separates it from generate_evidence_bundle and export_bundle.

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 implies the usage context ('periodic sealed-bundle generation', 'an operator can schedule'), which tells the agent when it fits. However, it never names an alternative tool or states when NOT to use it (e.g. versus calling generate_evidence_bundle directly), leaving routing 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?

readOnlyHint=true is confirmed by the [READ] prefix with no contradiction, and the description goes well beyond it. It explains the populationSize vs sample relationship, when truncated is set, and warns that scanTruncated=true means the population is only a slice and no coverage claim should be made — a genuine correctness caveat an agent could not derive from annotations alone.

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

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

Front-loaded with the purpose, then a compact Args list, then return-value semantics — no wasted sentences. The formatting with escaped backticks is a little noisy but each clause 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 present, the description compensates by naming and interpreting the key return fields (populationSize, sample, truncated, scanTruncated) and their interaction. For a read-only evidence tool this covers everything needed to call it and interpret the result without misleading coverage claims.

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 does: framework enumerates hipaa/pci_dss/soc2/gdpr, control_id gives per-framework examples, since/until are ISO timestamps bounding the period, and sample_size is defined as the number of representative rows. All five parameters gain meaning absent from 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?

Starts with a bracketed operation mode ([READ]) and states a concrete verb+resource+scope: evidence rows for ONE control, plus population size and a reproducible query. The 'ONE control' scoping makes it distinguishable from broader siblings like query_audit_events or coverage_summary 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?

The Args block explains what each parameter means but never says when to reach for this tool instead of query_audit_events, coverage_summary, or generate_evidence_bundle, and states no prerequisites or exclusions. Usage is only faintly implied by the scoping wording, so an agent gets no routing 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=true, so the description's '[READ]' tag adds little. It discloses the aggregation at per-control granularity and the period scoping, which is useful context, but omits output format and return shape details beyond what annotations cover.

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 verb and resource, followed by an args block. Efficient and structured. The '[READ]' prefix is redundant given readOnlyHint, a minor waste.

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

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

Given no output schema and no annotations covering return shape, the description could say more about what a coverage summary contains (counts, per-control status?). It gives enough to invoke correctly but leaves the result format 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 coverage is 0%, so the description must compensate — and it does describe all three: framework's valid values (hipaa/pci_dss/soc2/gdpr) and the since/until ISO timestamp bounds. It doesn't note that since/until are optional or their defaults, so slightly short of 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?

Specific verb+resource: 'Per-control coverage for a framework over a period'. The [READ] tag and parenthetical '(are we covered?)' make the intent unambiguous. It doesn't explicitly name gap_analysis or control_evidence as siblings, so it falls 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 parenthetical '(are we covered?)' hints at the question this answers, but no explicit when-to-use, when-not-to-use, or alternative routing is given. An agent must infer from sibling names like gap_analysis and control_evidence when to prefer this 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?

readOnlyHint=true already declares the safety profile, so the '[READ]' prefix is largely redundant. The description does add useful content scoping — it says the report covers denials, errors and budget-exceeded ops — but says nothing about volume limits, pagination, or how results are aggregated.

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 the resource, followed by a one-line rationale and a compact args block. The 'not rubber-stamp' clause is motivational framing that is slightly ornamental but still carries interpretive value.

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 and no annotations beyond readOnlyHint, so the description must carry the load. It identifies the report's contents but leaves open what happens when since/until are omitted (both default null) and what the returned evidence looks like.

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

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

Schema description coverage is 0% and the schema only supplies an 'anyOf' string/null type for each field. The description compensates by naming both parameters and giving their format ('ISO timestamps') and role ('bounding the period'), which is the key information 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 resource — denied, error and budget-exceeded operations — with the analytical angle (enforcement + anomaly evidence). An agent can tell what this report contains, though it isn't explicitly differentiated from siblings like approval_report or query_audit_events.

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 explains why the report matters ('denials prove the governance controls actually block') but never states when to reach for it versus the many sibling reporting tools (coverage_summary, approval_report, query_audit_events). No exclusions, prerequisites, or alternatives are offered.

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 and destructiveHint=true, so the write profile is covered there; the description reinforces it with the [WRITE][risk=medium] tag. Beyond that it discloses genuinely non-obvious behavioral caveats about the produced OSCAL artifact (control ids are not resolved against an imported catalog, and OSCAL has no 'partially satisfied' state), which is real added value. It still never says that out_path may overwrite an existing file, which is the concrete destructive behavior the annotation warns about.

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 one-line purpose and the [WRITE][risk=medium] tag, then the format-specific caveat, then a compact Args block. The OSCAL paragraph is long but each clause (output filename, read-first pointer, two limitations) earns its place; 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?

For a destructive, non-idempotent write tool with no output schema, the description covers formats, defaults, and the OSCAL artifact's caveats well. It leaves two gaps an agent would want: whether calling it again overwrites an existing output file, and what is returned on success (a confirmation, the written path, or the document itself). Those matter precisely because destructiveHint=true and idempotentHint=false.

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 parameter burden, and it largely does: bundle_path is defined as a bundle .json, fmt is spelled out as markdown/csv/json/oscal, and out_path's default is stated as 'alongside the bundle'. What it omits is the non-enum validation constraints (allowed extensions, wildcard behavior) and whether out_path must be an existing directory.

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?

Names a specific verb (render/export) and resource (bundle), and enumerates the four concrete output formats. It also distinguishes itself from oscal_assessment_results by positioning that tool as the way to get results inline rather than exported to a file, so an agent can separate the two 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?

Explicitly routes the agent: 'Read oscal_assessment_results first if you need the document inline plus its limitations', which names an alternative and the condition that selects it. There is no equivalent guidance for the markdown/csv/json formats or for when not to export (e.g. before verification), so the coverage is uneven rather than complete.

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 [READ] marker aligns with readOnlyHint=true, and the description adds real value beyond annotations: it discloses the return shape (reason + remediation per control) and a methodological caveat that audit trails evidence operating effectiveness strongly but control design only partially. That caveat is genuine behavioral context an agent cannot get from the annotation.

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

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

Front-loads what the tool returns, then the caveat, then a compact Args block. Every element earns its place with no filler, though the trailing arg list is slightly clipped in style.

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 carries the return-value burden, and it does so by describing what each gap entry contains. Combined with the readOnlyHint annotation and documented args, it is nearly complete; the main omission is explicit sibling routing.

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 no enum and no descriptions – so the description must compensate, and it does: it enumerates the framework values (hipaa/pci_dss/soc2/gdpr) and defines since/until as ISO timestamps bounding the period. This meaningfully exceeds the bare 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: it surfaces controls with no/weak evidence and returns an honest reason plus remediation. This differentiates it from siblings like coverage_summary and control_evidence. It stops short of naming a sibling explicitly, keeping it at a strong 4 rather than 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 description implies usage (finding compliance gaps) but never states when to pick this over coverage_summary, control_evidence, or exceptions_report. No when-to-use or when-not guidance is given, so the agent must infer the routing itself.

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, so the safety profile is covered. The description adds genuinely new context: it reads audit DBs, writes only to a local artifact under ~/.compliance-aiops/bundles/, and touches no external system. It does not say what happens if out_path already exists (overwrite vs error) or what the destructive hint actually refers to, which is a mild gap for a tool annotated destructive.

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 [WRITE][risk=medium] tag, then a one-line summary, then the output/scope sentence, then a tight argument list. Every line adds information and nothing is repeated from the schema or annotations.

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 six-parameter write tool with no output schema and no schema descriptions, the definition covers purpose, scope, target location, parameter precedence rules, and side effects. The description even states where the resulting bundle .json lands, so an agent knows the return artifact without an output schema.

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

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

Schema description coverage is 0%, so the description carries the full burden and does so: framework lists all six valid values, period_start/period_end are specified as ISO timestamps, out_path documents its default directory, sign explains the HMAC-attachment condition, and period is documented as a convenience window that applies only when start/end are omitted. This is more than the bare schema could ever 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 ('Assemble + hash-chain-seal an evidence bundle for a framework') and immediately enumerates what the bundle aggregates: coverage, approval trail, exceptions, sealed evidence records. An agent can distinguish this from verify_bundle, export_bundle, and the individual report siblings 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?

The 'One-call happy path' phrase clearly signals this is the consolidated call that subsumes coverage_summary, approval_report, and exceptions_report, which is real usage context. However, no sibling tool is named explicitly and there is no 'do not use when' clause (e.g., when to prefer export_bundle or a single report), so it stops short of full routing 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?

readOnlyHint=true already covers the safety profile, and the description adds beyond it: it discloses that results include readability status and row counts, and reveals the underlying on-disk path pattern. It does not describe failure modes or error handling on unreadable DBs, keeping 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?

Two tight sentences with the [READ] tag and resource front-loaded, followed by the when-to-use directive. No redundant or filler content; every clause conveys actionable information.

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

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

For a zero-param, read-only discovery tool with no output schema, the description adequately covers purpose, output content (readability/row counts), and call ordering. It could note the output shape more concretely, but it is complete enough to invoke correctly.

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

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

The tool takes zero parameters and the schema is empty, so description-level parameter semantics are not applicable and the baseline of 4 applies. Nothing about arguments needs clarifying.

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 (List) plus resource (sibling audit DBs) and even names the concrete artifact path pattern (~/.<tool>-aiops/audit.db). It distinguishes itself from siblings like list_bundles and list_frameworks by scoping to audit DB sources, and the [READ] tag reinforces the action.

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

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

Explicitly says 'Call this first to see which governed AIops tools' trails are available as compliance evidence,' giving clear sequencing and intent. It does not name an explicit alternative or a when-not condition, so it falls short of the top tier, but the entry-point guidance is unambiguous.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds useful content beyond that by naming the returned fields (chain head and metadata). However, it says nothing about pagination, ordering, or whether the list can be filtered or is unbounded.

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

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

A single short sentence, front-loaded with the resource and return content, with no filler. The '[READ]' prefix is mildly redundant given readOnlyHint, but the whole description is efficient.

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

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

There is no output schema, so the description carries some burden for describing returns; it does name chain head and metadata, which is helpful. It still omits pagination behavior and result ordering, leaving the agent to guess at the shape and scale of the response.

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

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

The tool takes zero parameters, so there is no parameter semantics for the description to clarify. With no arguments to document, the baseline of 4 applies.

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

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

The description states a specific resource (bundles) and qualifies it as previously generated, with a listing verb implied by the tool name. It also names what is returned (chain head and metadata), which distinguishes it from sibling tools like verify_bundle or generate_evidence_bundle. It stops short of explicitly contrasting with 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?

There is no statement of when to use this tool versus alternatives such as verify_bundle, export_bundle, or list_audit_sources. The '[READ]' tag hints at the read-only nature but gives no selection criteria. An agent must infer usage entirely from the name.

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

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

The readOnlyHint annotation already establishes that this is a safe read, and the '[READ]' prefix merely restates it. The description does add useful content semantics (frameworks plus control counts), but says nothing about ordering, pagination, or whether the list is static or tenant-scoped. With annotations carrying the safety profile, the description is adequate but not rich.

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

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

A single sentence that front-loads the operation tag and the core content, with zero filler. The framework names and the '+ control counts' addendum each earn their place by telling the agent what the output contains.

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, so the description carries the return-value burden, and it does so adequately by naming the frameworks and noting the control counts. It is missing only minor details such as result ordering or how the counts are aggregated, which are unlikely to change the call decision.

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

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

The tool takes zero parameters, so the schema-side baseline is a 4 and the description has nothing it must compensate for. It correctly avoids restating parameter details and instead spends its words on what the call returns.

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?

Names the specific resource (supported compliance frameworks) and enumerates the concrete values (HIPAA / PCI-DSS / SOC 2 / GDPR) plus an extra return element (control counts), so the agent knows exactly what comes back. It does not explicitly differentiate itself from siblings like coverage_summary or gap_analysis, but the resource is distinctive enough to be unambiguous.

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

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

Usage is only implied: the agent can infer this is the discovery call for framework identifiers, and it is a zero-parameter listing so the invocation is self-evident. There is no explicit when-to-use, no prerequisites, and no routing to related siblings (e.g. coverage_summary, gap_analysis), leaving some guidance on the table.

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?

Reads far past the readOnlyHint annotation: it discloses how import-ap is represented when no assessment plan exists, that control ids are framework-native and unresolved against a catalog, how partial evidence is downgraded to 'satisfied' with an evidence-strength prop, and that deterministic v5 UUIDs make re-export byte-identical. It also warns that the partial-evidence count sits in `summary` specifically so it cannot be skimmed past.

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 the core purpose, then organized into the three OSCAL limitations and the args block. Dense but every sentence carries information; the trailing args note is slightly redundant given the schema already lists bundle_path.

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 carries the return shape itself: an inline document with a summary and an explicit limitations list. It also covers determinism and the 'sealed bundle' prerequisite, giving an agent enough to call this correctly without inspecting the implementation.

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% for the single bundle_path parameter, so the description must compensate. It does so usefully by specifying the file type (.json) and the source tool (list_bundles), but it adds no path format, absence-of-file, or validation behavior beyond that.

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 concrete verb+resource and target format: converts a sealed bundle into an OSCAL 1.2.3 Assessment Results document. It explicitly distinguishes itself from the nearest sibling by noting that writing a file is export_bundle's job, so an agent can route between the two 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?

Names the alternative (export_bundle) and the condition that selects it (inline return vs. file writing), which is strong routing guidance. It stops short of stating when to prefer this tool over, say, coverage_summary or control_evidence, and gives no explicit when-not-to-use condition.

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 goes well beyond that by disclosing the exact return payload (events, count, returned, limit, truncated, scanTruncated) and the non-obvious semantics of truncated/scanTruncated, plus a strong inference rule against characterising the trail from a truncated result. It omits auth requirements, rate limits, or default page size.

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, then a compact args block and a returns block; every line carries information given the 0% schema coverage. The Args list is slightly list-heavy but justifiable since the schema documents nothing.

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 ten undocumented parameters, the description compensates fully: it documents every filter, explains the return envelope, and warns about the truncated/null-truncated edge case that would otherwise cause a wrong conclusion. Nothing an agent needs to call and interpret 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 description coverage is 0%, so the description carries the full burden and does so: it defines source, skill/tool/status/risk_level as field filters, approved as a boolean approver-presence filter, selector as an evidence-class selector with enumerated values, since/until as ISO bounds, and limit as row cap. All ten parameters get meaning not present in the bare JSON 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 ('Cross-tool audit event query') and signals primacy with 'the workhorse', so an agent knows this is the general-purpose event query. It stops short of explicitly differentiating from siblings like activity_timeline, approval_report, or exceptions_report, which overlap in domain.

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 rather than stated: 'the workhorse' suggests default choice, and the truncation caveat tells the agent when a result is not trustworthy as a final count. There is no explicit when-to-use-this-vs-alternative guidance naming a sibling or a condition that routes elsewhere.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=true. The description goes beyond them by disclosing the dependency on the encrypted secret store, the prerequisite setup command, and the stated risk rationale ('reads the encrypted secret store'). It does not, however, explain what the destructive aspect actually does to the bundle.

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 tag prefix front-loads write status and risk level, and the body is short. There is minor redundancy between 'Requires a signing key in the encrypted store' and 'reads the encrypted secret store', but overall it is efficient.

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

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

For a single-parameter mutation with annotations covering the safety profile and no output schema, the description supplies the key missing context: the secret-store dependency and risk rationale. Return behavior is unaddressed, but that is a minor gap for a signing operation.

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. It does identify bundle_path and adds a format hint ('Path to a bundle .json'), which is more than the bare schema title, but it omits constraints such as whether the path must be absolute or how the seal is located.

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: 'Attach an HMAC signature over a bundle's seal'. This clearly distinguishes it from verify_bundle and generate_evidence_bundle by operation, though it does not name a sibling explicitly, keeping it just 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?

It states a prerequisite (a signing key must exist in the encrypted store, with the command to set one) but gives no explicit when-to-use or when-not-to-use guidance relative to alternatives like verify_bundle or export_bundle. Usage is only implied by the operation name.

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 supply readOnlyHint=true; the description goes well beyond that by disclosing the return shape, that truncation is *measured* via an extra-row fetch, and that effectVerified=false means the reversed change is only PROBABLE, with a caution to check live state and not over-report. This is meaningful operational context the 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 purpose and the sibling handoff, then structured paragraphs for return value and the effectVerified caveat. Every sentence carries information, though the emphasis on truncation being 'measured, not guessed from a length coincidence' is slightly verbose for the value it adds.

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 present, the description supplies the return JSON shape, the meaning of every field an agent must act on (returned, limit, truncated, effectVerified), and the follow-up behavior for truncation. Nothing needed to call or interpret 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 0% and no param has an enum, so the description must compensate, and it does fully: limit is documented as default 50 / capped at 500, and target is documented as ignored with the reason (host-local undo state, kept for CLI uniformity).

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'). The [READ] tag and the reference to undo_apply make it clearly distinguishable from the sibling that actually applies tokens.

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.' and tells it to re-run with a higher limit when truncated rather than reporting a partial list as complete. It lacks an explicit 'when not to use this' condition, so it falls 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 already declare readOnlyHint=true, and the [READ] tag restates this. The description adds the useful detail that verification covers three specific checks, but does not disclose what happens on failure (exception vs. result field) or whether it's cheap to re-run. Modest added value given the annotation already covers the safety profile.

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

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

Front-loaded with [READ] and the core action, then the specific checks, then the single arg. No wasted sentences. The literal 'Args:' block is slightly redundant with structured schema but does not bloat the entry.

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?

One-parameter read tool with an annotation already covering its safety profile, so the bar is moderate. It covers what is verified and what input it needs, but leaves out failure semantics and linkage to sign_bundle/verify_source_chain in the sibling set. Adequate but not thorough.

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% for the single parameter, so the description carries the burden. It correctly identifies bundle_path's meaning as the path to a bundle .json produced by generate_evidence_bundle, giving an agent the provenance expectation needed to supply a valid value.

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 (verify) and resource (a sealed evidence bundle) and enumerates the exact integrity aspects checked: chain integrity, seal head, signature. This distinguishes it from sign_bundle (which produces a seal) and verify_source_chain (which targets a source, not a bundle).

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 mention that the bundle comes from generate_evidence_bundle establishes the operating context and implicitly answers when to use it: after sealing. However, it does not explicitly state alternatives (e.g., verify_source_chain) or conditions under which verification should be skipped.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds interpretive behavior (row-id gaps may indicate deleted audit rows) and the re-run workflow, which is useful, but it does not describe the return payload structure or any 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?

Front-loaded with a [READ] tag and the core purpose, then a compact workflow note, then a clean Args list. No filler sentences; slightly terse but every line contributes.

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

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

For a read-only tool with no output schema and annotations covering safety, the description supplies purpose, param meaning, and result interpretation. It is close to complete; only a note on the response shape or pagination would round it out.

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 does so well: source is the tool name from list_audit_sources, and since/until are ISO timestamps bounding the range. All three parameters get clarifying meaning beyond their bare types.

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 action and resource: retrieving the chain head for a source's current events plus row-id gap detection. This is more than a restatement of the name. It doesn't explicitly contrast with siblings like verify_bundle or query_audit_events, but the purpose is clear enough for an agent to know what it does.

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

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

Provides genuine usage context: record chainHead out-of-band and re-run later to detect changes, and it routes the agent to list_audit_sources to obtain the source value. However, it never states when to use this versus verify_bundle or query_audit_events, so guidance is implied rather than explicit.

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