datasentry

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), so the description's added value is the edge-case behavior: ok:true with comparison null when fewer than two runs exist. It also pins the spec version (V6, ADR-064), which is useful provenance but stops short of describing the comparison payload structure.

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

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

Three compact sentences, front-loaded with what the tool does and ending on the degenerate-result case. The V6/ADR-064 parenthetical is internal jargon that consumes space without helping an agent invoke the tool.

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

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

With no output schema, the description does partial duty by sketching the return content and the null-comparison case. Given only two obvious required params, that is close to sufficient, though the exact comparison object shape and the dataset_id semantics remain undocumented.

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 clarifies current_run_id ('use the current run id'), which is genuinely helpful, but says nothing about dataset_id or the relationship between the two identifiers.

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: a same-dataset historical run comparison returning per-run overall/dimension scores, issue counts, and deltas. It is clear what the tool produces, but it never names or contrasts the close sibling drift_compare, so the agent must infer the boundary itself.

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 by the phrase 'same-dataset historical run comparison' and the note to pass the current run id. There is no explicit when-to-use or when-not-to-use guidance versus drift_compare or trends_list, and no stated prerequisite that two prior runs must exist for a meaningful result.

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

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

Annotations already establish the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false). The description adds one useful behavioral fact beyond that: the tool returns either the structured contract or validation errors, i.e. a dual success/failure shape. It stops short of describing error structure or file-format expectations, so a 3 is appropriate.

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 front-loaded sentence with no filler; the action and result are stated immediately. It is appropriately sized, though it could pack one more clause of routing or format detail without becoming bloated.

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 is the only place return behavior can be conveyed, and it does signal a dual contract-or-errors return. However, it omits error format, validation strictness, and any prerequisites, leaving meaningful gaps for a validation 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% for the single 'path' parameter, so the description must carry the burden. It implies the path points at a YAML contract file, which gives partial meaning, but does not clarify path form (relative/absolute) or expected file extension. Marginal added value over 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: 'Validate a data contract YAML file'. An agent knows exactly what the tool does. It does not, however, distinguish itself from plausible siblings such as scan_file or repair_verify, 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?

There is no when-to-use or when-not-to-use guidance and no alternative named. The agent must infer from the name alone that this is the validation entry point rather than scan_file or repair_verify.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered by structured data. The description adds the return payload shape, but says nothing about ordering, pagination, or whether 'registered' implies user-configured vs built-in detectors — relevant for a tool that lists ALL entries.

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 with the verb and resource front-loaded and the payload fields following; there is no filler, hedging, or restatement of the tool name.

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

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

With no output schema, the description must carry the return-value burden, and it does list the key fields (id, dimension, capabilities, default thresholds). The remaining gap is completeness of the contract — pagination, ordering, and whether thresholds are unit-bearing — but the core is covered.

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 description bears no parameter burden; baseline for a 0-param schema is 4. The schema is empty and fully consistent with the description's 'list all' framing.

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) and resource (registered quality detectors) and enumerates the returned attributes (id, dimension, capabilities, default thresholds). It is clearly distinguishable from sibling list tools such as trends_list and jobs_list by the resource noun, though it never names a sibling 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?

There is no statement of when to call this versus alternatives like quality_score, profiles_get, or trends_list, and no mention of prerequisites. The 'registered detectors' framing implies a discovery step before configuring or interpreting quality results, but that is left entirely to inference.

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

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

Annotations already declare readOnly, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely new behavioral context: the threshold defaults (0.20/5.0) and their correspondence to the CLI flags, which are absent from the schema.

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

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

Two sentences, front-loaded with the core comparison scope and then the threshold details; little waste. The trailing 'D1-06' ticket reference adds noise without meaning for an agent.

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 four undocumented parameters, the description covers the drift dimensions and threshold defaults but omits the meaning of the two run-ID parameters and any hint at the response shape or how drift is reported.

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. It supplies defaults and CLI equivalents for row_ratio_threshold and score_threshold, but says nothing about the semantics of reference_run_id versus current_run_id beyond the phrase 'two historical scans'.

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 (compare) and resource (two historical scans of a dataset), and enumerates the four drift dimensions: schema, row-count, score, and issue-distribution. It implicitly distinguishes itself from drift_latest by requiring two run IDs, but never names a sibling to differentiate 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?

There is no statement of when to reach for this tool versus comparison_build or drift_latest, and no prerequisites or exclusions are given. The mention of CLI-equivalent thresholds describes behavior, not usage conditions.

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

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

Annotations already establish readOnly/non-destructive/closed-world, and the description adds real behavioral context on top: the failure mode when scan history is insufficient, and that thresholds default to the CLI values 0.20/5.0. It stops short of describing the response shape or what the thresholds actually gate.

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

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

Three dense sentences, front-loaded with purpose, then precondition, then defaults. The trailing '(D1-06)' is internal shorthand that costs a few tokens without informing the agent.

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 could reasonably say more about what a drift result contains and what units the thresholds use. Given it is a read-only analytical tool with three parameters at 0% schema coverage, the definition is adequate but leaves real gaps.

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

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

Schema coverage is 0%, so the description carries full burden and only partially compensates. It supplies default values (0.20/5.0) for the two thresholds but never names them, leaving the agent to guess which number maps to score_threshold versus row_ratio_threshold; dataset_id is unexplained.

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 with scope: drift computed between the two most recent scans of a dataset. The 'two most recent' qualifier implicitly distinguishes it from drift_compare, but the sibling is never named, so the agent must infer the boundary itself.

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 the precondition under which the tool fails (fewer than two completed scans), which is genuinely useful implicit usage guidance. It does not, however, say when to choose this over drift_compare, which is the most plausible alternative for the same task.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered by structured data. The description adds that results span multiple scans and can be narrowed, but says nothing about ordering, pagination, limits, or volume, which matters for a list endpoint.

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 well-formed sentence that front-loads the action and resource before listing the optional filters. Nothing superfluous.

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-only listing tool with no output schema, the definition is minimally adequate. It omits the shape of returned issues and, more importantly, any differentiation from the sibling list_issues, which an agent needs to choose correctly.

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

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

Schema coverage is 0%, so the description must carry the load, and it does partially: it enumerates the valid severity values (info/low/medium/high/critical) that the schema does not constrain, and clarifies scan_run_id as a scan id filter. It does not explain the 'at least' semantics of severity_at_least or the identifier format, so it stops short of full compensation.

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 clear verb and resource ('List quality issues across scans') and adds scope ('across scans'). However, it makes no attempt to differentiate itself from the near-identical sibling list_issues, leaving an agent to guess which one to 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?

It implies usage by describing the optional filters ('optionally filtered by minimum severity ... or a scan id'), so an agent can infer when filtering matters. But there is no explicit when-to-use guidance and no mention of when to prefer list_issues or quality_score instead.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds that the call returns the created job view, which is useful, but it omits the mandatory 'confirm' acknowledgement gate that governs whether anything is written — a meaningful behavioral detail the description could have 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?

One tight sentence, front-loaded with the action and followed by the notable inputs. The '(Step 51)' parenthetical is internal jargon that adds no value to an agent, a minor blemish on otherwise efficient writing.

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

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

For a mutation tool with no output schema and low schema coverage, the description covers the core fields and states the return value, but it never mentions the required confirm flag or the semantics of name/retry_attempts, leaving gaps an agent would have to infer.

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 only 22% (cron and confirm), so the description must compensate. It documents path, webhook_url and gate_quality_min with a 0-100 range, adding real meaning, but leaves name (required), dataset_id, table_name and retry_attempts entirely unexplained — over a third of the parameters undocumented anywhere.

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: 'Register a scheduled scan job', with the key inputs (cron, path, quality gate, webhook). It is clearly distinct from job_trigger/job_update/job_remove by the word 'Register', but it never explicitly differentiates itself from those siblings or from jobs_list.

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 when-to-use guidance, no prerequisites, and no mention of how this differs from job_trigger or job_update. The only implied context is that it creates a new job rather than acting on an existing one.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the destructive nature is covered by structured data. The description usefully adds the return shape ('Returns removed=true'), which matters because there is no output schema, but it omits the mandatory confirm acknowledgement and the irreversibility of deletion.

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 action front-loaded and the return value second; nothing is padded. The internal references '(Step 88, ADR-088)' are the only text that adds little for an invoking agent, keeping it just short of a 5.

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 mutation with no output schema, the description does supply the return value, and annotations cover the safety profile. However, it never states that confirm=true is required to actually mutate state or that deletion is permanent — the two facts an agent most needs before calling this.

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 50%: 'confirm' is documented in the schema, but 'job_id' has no description anywhere. The description contributes no parameter meaning at all, so it does not compensate for the undocumented job_id or clarify the confirm contract beyond what the schema already says.

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 — 'Delete a scheduled job' — which is unambiguous and clearly distinct from siblings like job_create, job_update, and job_trigger. It does not explicitly name an alternative, but the verb alone separates it from every sibling.

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 (e.g., job_update to disable a job, or job_trigger to run it now), and no mention of prerequisites or when deletion is inappropriate. The agent is left to infer that deletion is the terminal, irreversible option.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description goes further by listing the fields returned and the possible status values, which is genuinely useful since there is no output schema. It omits any note on pagination or result-size limits, keeping it out of 5 territory.

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 sentences, front-loaded with the primary action and the filtering behavior, with essentially no filler. Only the '(Step 51/52)' internal reference fails to earn its place.

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

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

For a simple, annotation-covered read tool with no output schema, the description covers purpose, the optional filter, and the shape of the returned data. Nothing critical is missing, though it could note ordering or volume expectations for the job list.

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

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

Schema description coverage is 0% and the schema declares no enum, so the description carries the full burden. It supplies the allowed values (idle/running/dead) for the single status parameter, which the schema does not, and marks the parameter as optional. That is meaningful compensation for the coverage gap.

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) and resource (scheduled scan jobs), then enumerates the returned fields (cron, enabled, status, next run time, last result). That clearly separates it from job_create/job_trigger/job_update/job_remove, though it never names those siblings explicitly. The '(Step 51/52)' parenthetical is internal jargon that adds no clarity.

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 says the status filter is optional and enumerates the accepted values, which implies the common usage pattern, but there is no explicit when-to-use or when-not guidance relative to job_create/job_update/job_trigger. An agent can infer this is the read path for jobs, but nothing confirms the boundary conditions.

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

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

Annotations already declare readOnly=false, destructive=false, openWorld=true, so the concurrency constraint ('409-style error if already running') and the return shape ('run id and outcome') are genuine value-adds beyond structured fields. It could say more about what happens to an in-flight run, but this is solid disclosure for a mutation 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-loaded with the action and kept to two tight clauses. The '(Step 51)' reference is internal noise that doesn't help an agent, but otherwise nothing is wasted.

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

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

With no output schema, the description correctly covers return values ('run id and outcome') and the concurrency failure mode. For a 2-parameter mutation tool this is largely complete, though the undocumented job_id and vague 'outcome' leave minor gaps.

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

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

Schema coverage is only 50%: 'confirm' is well documented in the schema itself, but 'job_id' is undocumented in both schema and description. The description does not compensate for that gap, adding no meaning about how job_id is obtained or formatted.

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: 'Immediately run a scheduled job once.' This is clearly distinct from jobs_list (read) and job_create/update/remove (lifecycle management). However, it never names a sibling or explicitly contrasts itself, so it stops short of full 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?

The word 'Immediately' and 'once' imply on-demand single execution versus scheduled recurrence, and the 409 mutual-exclusion note gives a precondition. But there is no explicit 'use this when / use X instead' guidance, so usage is only implied.

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

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

Annotations already flag this as a non-readOnly, destructive mutation, and the description adds genuinely useful behavior: updates are partial, and a cron change recomputes the next run time. It also notes the response is the updated view, though it says nothing about permissions or reversibility.

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?

One dense sentence that front-loads the verb and resource, then the field set, then the side effect and return value. The ADR/Step citation is arguably noise but small; no sentence is wasted.

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

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

For a 7-parameter destructive mutation with no output schema, the description covers scope, partial-update semantics, a key side effect, and the return shape. The remaining gap is auth/permission requirements and whether the mutation is reversible.

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 only 29%, so the description must compensate and it does partially by enumerating the five updatable fields (enabled/cron/retry_attempts/webhook_url/gate_quality_min). However, it adds no per-parameter semantics such as value ranges for gate_quality_min or expected webhook_url format, so it mostly restates property names.

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 (update) plus a specific resource (scheduled job), with the mutable field set enumerated. It is clearly distinguishable from siblings like job_create, job_trigger, and job_remove.

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?

States 'partial update' and lists which fields can be changed, which implies the editing context, but it names no alternatives and gives no when-not guidance (e.g. versus job_trigger for forcing a run or job_remove for deletion).

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds real context: the removal is irreversible, it does not require the encryption key, and it reports deleted=true or ok:false when the session is absent. That return-value disclosure is especially valuable since there is no output schema.

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

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

Three tightly written sentences that are front-loaded with the action and immediately followed by the irreversibility caveat and return contract. The '(Step 100, ADR-100)' reference is internal jargon of marginal value but costs little.

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 destructive tool with no output schema, the description covers irreversibility, key independence, and the return shape. It stops short of naming the confirm prerequisite explicitly and does not address permissions or effects on related sessions.

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 only 50%: confirm is documented in the schema, but session_id has no description anywhere. The description mentions no parameters at all, so it fails to compensate for the undocumented session_id or explain what a session ID refers to.

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 ('Delete a PII encryption session') and grounds it in an internal reference (Step 100, ADR-100). It does not, however, differentiate itself from the very similar sibling pii_purge_sessions, leaving the agent to infer which delete-like tool applies.

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 what the tool does and warns that the operation is irreversible, but never says when to choose it over pii_purge_sessions, pii_sessions, or pii_restore. There are no explicit preconditions beyond the schema-level confirm gate, and no alternatives are named.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds real context beyond that: age-only matching, no key requirement, and the ok:false failure mode for invalid input.

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

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

Three front-loaded sentences with the action first and no padding. The Step 103 / ADR-103 parentheticals are internal references that add mild noise but no real length.

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

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

With no output schema, the description correctly covers the return contract (purged count or ok:false on invalid input), which is what an agent most needs. It is largely complete, missing only pagination-style edge cases that don't apply to a purge.

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

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

Schema coverage is 100%, so both parameters are already documented, including the >= 1 constraint. The description only adds the consequence of an invalid olderThanDays and says nothing extra about confirm beyond what the schema already states, so the baseline 3 applies.

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

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

States a specific verb (Delete), resource (PII encryption sessions), and scope (older than N days). Against siblings like pii_delete_session and pii_sessions, this reads as a bulk, age-based purge, so an agent can distinguish it 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?

"Sessions are matched by creation time only; the encryption key is not required" clarifies the matching criterion, which hints at when it applies. But it never names alternatives (e.g., pii_delete_session for a single session) or says when not to use this bulk purge, leaving sibling selection to inference.

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

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

Annotations only declare readOnly=false, destructive=false, openWorld=false; the description adds genuinely new behavior: the authorization semantics of the call and three concrete failure modes (missing session, undecryptable mapping, no key configured) with an ok:false return. It stops short of describing the success payload or confirming that plaintext leaves the PII boundary, which would be valuable for a privacy-sensitive operation.

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

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

Well front-loaded: purpose first, then semantics, then error behavior. The parenthetical '(Step 100, ADR-100)' is internal design-doc noise that costs tokens without helping tool selection, and the error enumeration is slightly run-on.

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 carries the return-value burden for the failure path (ok:false plus reason). Combined with the annotations and a fully-described 3-param schema, an agent has enough to call it correctly; only the success return shape is left unstated.

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

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

Schema description coverage is 100%, and all three parameters already carry their own descriptions (including the mandatory confirm acknowledgement and its D5-08/D5-12 rationale). The description adds no parameter-level detail, so the baseline 3 applies.

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

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

States a precise verb+resource pair: restore plaintext by substituting {{REDACTED:...}} placeholders using a PII session's mapping. This is clearly distinguishable from the neighboring session-lifecycle tools (pii_sessions, pii_delete_session, pii_rotate_key, pii_purge_sessions), which manage the mapping rather than consume it.

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

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

The description gives a strong context cue — calling it is itself the authorization to view plaintext — which tells the agent this is the deliberate, audited path to plaintext. It does not, however, name alternatives or state when-not (e.g., 'do not call during automated pipelines'), so exclusions are left to inference.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description goes well beyond them: it discloses the concrete blast radius (all existing mappings re-encrypted, previous key invalid for existing sessions), the side effect (writes to the local key file), and the failure mode (ok:false with an error when no key is configured). That is exactly the added 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?

A single dense paragraph that front-loads the action and its consequence before the parameter and return notes. The parenthetical process references (Step 102, ADR-102, D5-08/D5-12) are mild noise, but every sentence still carries operational information.

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

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

With no output schema, the description usefully covers the success/failure contract (ok:false plus an error when no key is configured) and the confirm gating. It stops short of stating any permission or backup prerequisites for a destructive key-rotation, which would be the last piece an agent needs.

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

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

Schema coverage is 100%, so both parameters are already documented in the schema; the description's note that newKey is auto-generated when omitted and that it mirrors the CLI flag only re-states the schema. It adds no format, length, or encoding detail for the key material, so the baseline 3 is appropriate.

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

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

States a specific verb+resource (rotate the PII vault encryption key) plus the concrete effect (re-encrypts all existing mappings, writes the new key to the local key file). It is unambiguous and clearly distinct from the other pii_* siblings such as pii_restore and pii_delete_session.

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 agent can infer this is the key-rotation operation and that it mirrors the CLI 'rotate-key --new-key'. There is no explicit when-to-use/when-not guidance and no routing against the neighboring pii_* tools, so it lands at implied usage rather than a real decision rule.

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 the safe read profile (readOnly=true, destructive=false), so the bar is lower, yet the description still adds real value: it scopes the payload ('no ciphertext, no plaintext') and discloses the failure mode (ok:false when no encryption key is configured) with concrete remediation (DATASENTRY_ENCRYPTION_KEY or rotate-key).

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 sentences, no filler: the scope and returned fields come first, the error/edge case second. Every clause earns its place and the most important information is front-loaded.

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

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

With no output schema, the description carries the burden of describing returns and does so partially (key version, creation time, absence of ciphertext/plaintext) plus the error path. It omits ordering, volume or pagination behavior for a session listing, which is a minor remaining gap for a zero-parameter 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?

Zero parameters, so per the rubric the baseline is 4; the schema is empty and the description correctly refrains from inventing filter semantics, instead describing what the unfiltered result contains.

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 ('List PII encryption sessions') with the returned fields named ('key version and creation time'). It distinguishes itself from mutating siblings like pii_delete_session, pii_purge_sessions and pii_rotate_key by resource+action, though it never names an alternative 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?

Usage is implied rather than stated: an agent can infer this is the read path for inspecting encryption sessions, but there is no 'use this when / not when' guidance or routing to pii_rotate_key versus pii_purge_sessions. The remediation hint for the missing-key error is useful prerequisite context but not a usage rule.

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 this a safe, non-destructive read. The description does add a genuine behavioral fact beyond the annotations: it returns raw JSON and signals a missing profile via ok:false with an error. That error contract is valuable, but auth requirements, profile contents, and size/rate considerations are unstated.

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?

It is short and front-loads the resource description, which is good. The parenthetical '(V6, ADR-061)' is internal-reference noise that consumes space without helping an agent decide or invoke, and the second sentence, while useful, is not structured as explicit guidance.

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

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

For a single-parameter read with no output schema, the description does cover the return shape (raw JSON) and the not-found error behavior, so an agent knows what to expect. It still omits how scan_run_id is obtained and what the profile contains, leaving meaningful gaps for a tool that is otherwise simple.

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 single required parameter scan_run_id has 0% schema description coverage and the description never explains it – no format, no indication of where the ID comes from or that it must reference an existing scan run. The description only implies the profile is keyed by scan run, which is not enough for the one parameter that drives the call.

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

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

The description identifies the resource (a scan-time column profile sidecar for a given scan run) and its return format (raw JSON), which is more than a tautology. However, the core verb is only implied and the framing leans on internal jargon ('sidecar', 'V6, ADR-061') rather than a plain statement like 'retrieve the column profile for a scan run'. It is understandable to a domain-aware agent but not crisply distinguished.

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 guidance on when to use this tool versus alternatives such as scan_file, quality_score, or list_issues. No prerequisites, no conditions, and no sibling is named. The only usable cue is the implicit read of a profile by scan_run_id.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real business context beyond that — that the output has six dimensions and that values below 60 signal risk — but does not describe the return format or the individual dimensions.

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 compact sentences with the core purpose front-loaded and the prerequisite parenthetical attached where needed. Efficient, though the parenthetical slightly interrupts the main sentence.

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

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

For a simple single-parameter read tool with no output schema, the description covers what it returns (a six-dimension score), how to supply the required argument, and how to interpret results (below 60 = risk). Only the identity of the six dimensions is left unexplained, 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?

With one parameter at 0% schema description coverage, the description must carry the load and does so partially: it explains provenance of scan_run_id (issues_list or scan_file). It gives no format details for the ID itself, so the compensation is incomplete.

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 resource (a scan run's six-dimension quality score) and characterizes the operation clearly enough to distinguish it from siblings like repair_verify or contract_validate. The verb is nominalized ("score of a scan run") rather than an explicit action, which slightly blunts the clarity.

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 a prerequisite hint by naming issues_list and scan_file as the way to obtain scan_run_id, which is useful routing context. However, it never states when to reach for quality_score versus alternatives, nor any exclusions, so usage is only partially guided.

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 annotations: discloses exactly what is written (repaired copy plus before snapshot under .datasentry/repairs/), that the source file is never overwritten, and that issues without a proposal are skipped (no_proposal) rather than failing. This is rich behavioral context that the destructiveHint 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?

Front-loaded with purpose and the WRITES DATA warning, and every sentence carries information. Slightly dense with internal D5-08 references that are not self-explanatory, but there is no wasted filler.

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

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

For a mutating tool with no output schema, the description covers the write side effects, safety guarantees, alternative workflow, skip semantics, and return shape (applied runs and per-issue errors). Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 80%, so the schema already documents most parameters. The description adds real meaning for preview_only (true reviews without writing, false applies) and reinforces the confirm acknowledgement gate, going beyond the schema text.

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

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

States a specific verb (apply), resource (repair proposals), and scope (one or more issues of a scan run). It explicitly distinguishes itself from the sibling repair_propose_batch, so an agent can route correctly 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 says to prefer repair_propose_batch first (D5-08), naming the alternative and the ordering condition. It does not spell out a clear when-not to apply, but the preview_only guidance covers the dry-run path well.

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

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

The description claims the tool is "read-only, never writes data," but the annotations set readOnlyHint=false, which indicates the tool may modify state. This is a direct contradiction between the description and structured annotations.

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

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

The description is compact, front-loads the core purpose, and includes only relevant information: scope, read-only intent, issue_ids behavior, and return contents. 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?

The description covers the return shape in the absence of an output schema and explains the issue_ids default. However, it omits any comparison to sibling repair tools and contradicts the readOnly annotation, leaving important context incomplete.

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 67%, and the description mainly repeats the schema's own issue_ids default behavior. It adds no meaning for scan_run_id or source_path, leaving two parameters without descriptive semantics beyond the minimal schema entries.

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: "Generate repair proposals" for issues of a scan run. It distinguishes this from sibling tools like repair_apply_batch, repair_rollback_batch, and repair_verify by clarifying that it only proposes and never writes data.

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

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

The description gives guidance on the issue_ids parameter, including that omitting it covers all issues of the run. However, it does not explicitly say when to choose this tool over alternatives such as repair_apply_batch or repair_verify, leaving the workflow context implied rather than stated.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description reinforces this with "WRITES DATA" plus the specific effect (restores the pre-repair snapshot). It also discloses return shape (rolled-back runs and per-run errors), adding useful context beyond annotations.

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

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

Three tight sentences, front-loaded with the mutation warning ("WRITES DATA") before the effect and return values. Zero wasted words.

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

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

Covers mutation semantics, the confirm gate, effect, and return values for a 2-param tool with no output schema. Minor gap: no mention of irreversibility or idempotency behavior.

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

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

Schema description coverage is 100%, with both parameters—including the confirm gate—fully documented in the schema. The description adds only "by run id" and per-run errors, so the schema does the heavy lifting; baseline 3 fits.

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 ("Roll back") and resource ("applied repairs by run id"), clearly distinguishing it from siblings like repair_apply_batch and repair_propose_batch. An agent can tell exactly what this 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?

Implies usage after repairs have been applied ("Roll back applied repairs"), but offers no explicit when-to-use/when-not or named alternatives such as repair_apply_batch as the inverse operation.

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

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

The description declares 'Read-only', but the annotations set readOnlyHint=false, and the tool itself persists a new scan run (it returns a verify scan run id) — so the read-only claim directly contradicts the structured safety metadata. Beyond that contradiction, it does disclose the comparison categories (fixed/persistent/new) and the return payload, but the false safety claim is the kind of error that misroutes an agent.

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, front-loaded with the action before the comparison detail and return values, so an agent gets the gist from the opening clause. The standalone 'Read-only.' fragment is short but misleading, which keeps this from being flawless.

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 summarizes the return ('verify scan run id and comparison counts') and the issue categorization (fixed/persistent/new), which is what an agent needs to interpret results. The main gap is the unresolved read-only/readOnlyHint discrepancy and the absence of any prerequisite or failure behavior.

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?

One parameter (repair_run_id) with 0% schema description coverage, so the description must carry the burden. It only obliquely references it via 'a repair run' and never states the accepted identifier form, where to obtain it, or whether it must be a completed/apply run. The parameter name is self-explanatory enough to reach a baseline 3, but no real semantics are added.

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 ('Verify a repair run') plus the mechanism ('re-scan the repaired copy') and the output semantics ('remaining issues vs the original scan (fixed/persistent/new)'). This clearly separates it from the sibling repair_propose_batch / repair_apply_batch / repair_rollback_batch tools without needing to open 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?

Usage is implied by the name and the phrase 'Verify a repair run', which points at the post-apply step, but there is no explicit when-to-use, no prerequisite (e.g. a prior apply run), and no named alternative such as list_issues or scan_file for a plain scan. Adequate but leaves the agent to infer the workflow position.

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

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

Annotations already declare readOnlyHint/openWorldHint/destructiveHint, so the safety profile is covered. The description adds genuine context: the payload is the canonical JSON report and is byte-equivalent to the CLI and REST paths. It omits size/rate-limit or auth details, but that is a minor gap given annotation coverage.

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?

One dense front-loaded sentence plus a short 'Read-only.' clause; no filler. The trailing read-only note duplicates the annotation, costing a small amount of precision but not clarity.

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

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

There is no output schema, and the description adequately characterizes the return as the canonical JSON report with parity to the CLI/REST payloads. For a one-parameter export tool this is close to complete, with only the parameter format left unspecified.

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 scan_run_id parameter (no type/format note in the schema). The description partially compensates by indicating the report belongs to 'a scan run', implying the ID identifies a scan, but gives no format or source guidance for the 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 (Export) and resource (canonical JSON report of a scan run), plus anchors it to known equivalents (CLI `report export --as json`, REST `GET /scans/{id}/report`). No sibling tool produces a report, so the purpose is unambiguous and distinguishable.

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 the use case (fetching the canonical report payload) but never states when to choose this over siblings like list_issues, quality_score, or contract_validate, nor any prerequisites. Usage is inferable but not guided.

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=false, openWorldHint=true, destructiveHint=false. The description adds real behavioral context: it persists a quality report, returns scan id/status/row count/score/issue counts, and documents sampling defaults (reservoir, seed 42) and the detector whitelist/tags behavior. This goes meaningfully beyond the annotations.

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

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

Front-loaded with scan targets and returns, then optional parameters. However, internal references (Step 55/56/57/76, ADR-076) are noise to an agent and clutter the parentheticals without adding decision 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?

For a complex 10-parameter tool with no output schema and thin schema coverage, the description supplies return values, sampling defaults, and supported source types. The main gaps (seed, dataset_id, table_name) are minor relative to what is provided.

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 only 20% (10 params, most undocumented), so the description carries the burden. It does explain sampling_size/sampling_ratio, the sampling_method options and default, sampling_seed default, detectors and tags, but leaves seed, dataset_id and table_name semantics unaddressed. Partial compensation, not full.

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 (Scan) plus the resource scope (local data files, PostgreSQL/MySQL tables, cloud-storage files) and the persistence outcome. An agent can distinguish this from siblings like profiles_get or quality_score 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 accepted input formats and DSN schemes imply when the tool applies, but the description never states when to use it versus alternatives such as job_create or quality_score, nor any preconditions. Usage is inferable but not spelled out.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description still adds real value by disclosing the return contents (score/issues series with latest score, delta, direction), which matters because there is no output schema.

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

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

Two compact sentences with the data surface and return shape front-loaded; nothing is wasted. The parenthetical '(V7 data surface, ADR-065)' is internal provenance jargon that adds little for an agent but costs only a few words.

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

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

For a read-only list tool with one optional parameter and no output schema, the description covers scope and returned fields adequately. Gaps remain around ordering, time range, and whether results paginate, but these are minor for this tool shape.

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

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

Schema description coverage is 0% and the single dataset_id property has no description, so the description must compensate. It does partially by clarifying that the parameter narrows results to one dataset, but gives no format, ID source, or behavior when omitted.

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

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

States a specific resource and output shape: cross-scan quality trends per dataset, returning score/issues series with latest score, delta and direction. This implicitly separates it from quality_score (a point score) and drift_latest, but it never names or explicitly contrasts 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?

The only guidance is 'Optionally filter to one dataset,' which describes a parameter, not when to choose this tool. There is no statement of when to use trends_list versus quality_score, drift_latest, drift_compare or list_issues, and no prerequisites or exclusions.

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