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

Beyond the annotations, the description discloses the default-approve semantics for unlisted metrics, the rejection of unknown metric names, and the consequence that rejected metrics and their derivatives are not published. It also flags the authorization requirement. These are exactly the behavioral facts an agent needs before invoking a non-idempotent mutation.

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 action and authorization in the first two sentences, then details the two parameters that carry the real semantics. Dense but every clause adds information; no filler or restatement of the 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?

For a mutation tool with an output schema (so return values need no explanation), the description covers the critical decision semantics and side effects. The remaining gap is the unexplained run_id, comment, and bundle_decision parameters, which leaves the argument surface partly opaque.

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, and it does well for two of five parameters: subject_hash (binds approval to the exact packet under review) and metric_decisions (map of metric -> approve|reject, with rejection cascade). run_id, comment, and bundle_decision (default 'approve') are never explained, so coverage remains partial.

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 ('certify the generated bundle and its metrics') and adds an authorization scope ('Reviewer principals only'). An agent can distinguish it from most siblings, though it never explicitly contrasts with publish_run, which is the nearest neighbor semantically.

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 'reviewer principals only' clause is a real eligibility constraint, and the metric_decisions paragraph implies usage context (acting on pending certification items). However, there is no explicit when-to-use/when-not guidance and no routing to publish_run or list_pending_reviews, leaving the workflow position 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 the generic write profile (readOnlyHint=false, idempotentHint=false); the description goes further by disclosing the server-side gate: the approval must exist, be unrevoked, unexpired, scoped to this run, and content-bound. It does not say what files/artifacts get written, where, or whether existing output is overwritten, which is the main remaining behavioral gap.

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

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

Front-loaded: the action and its output are stated first, then the precondition. The second sentence is dense but every clause is load-bearing; the parenthetical '(no boolean flags)' is slightly cryptic but adds an anti-pattern warning.

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?

A write tool with a real prerequisite is documented adequately, and an output schema exists so return values need not be explained. The only missing pieces are artifact destination/overwrite behavior, which are minor given annotations and output 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% and the two params have only titles, so the description must carry the load. It substantially defines approval_id (provenance and the four validation checks it must pass) but says nothing about run_id beyond the implicit; the coverage of one of two parameters is rich, so this lands above baseline.

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

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

States a specific verb (Generate) and two concrete artifacts (dbt project and semantic layer) plus the input they derive from (the reviewed mapping). An agent can distinguish this from propose_canonical_mapping, submit_mapping_review, or publish_run without opening the schema.

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

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

Gives a clear precondition and names the upstream sibling that produces it: approval_id comes from submit_mapping_review. It does not state when NOT to use the tool (e.g., versus publish_run or run_sandbox_tests as a next step), 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds no behavioral context beyond that — nothing about how fresh the status is, whether it should be polled, or any access constraints — and the returned fields it names are already captured by the 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?

A single short fragment with zero filler, and the most important element (current status) is front-loaded. It is efficient, though it reads as a noun phrase rather than a complete statement.

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 an output schema describing the return shape and annotations covering safety, the description does not need to explain returns or side effects. However, it omits any usage routing and any explanation of the one required identifier, leaving gaps an agent must guess at.

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?

There is one required parameter, run_id, with 0% schema description coverage, and the description does not explain what a run_id is, where it comes from, or how to obtain it. Referencing "a run" is the only implicit connection, which is a weak substitute for real parameter guidance.

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 run) and enumerates the exact contents returned: current status, step history, gate, and pending review items. It clearly reads as a retrieval tool, though it never explicitly differentiates itself from the overlapping sibling list_pending_reviews.

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 guidance, no prerequisites, and no mention of alternatives such as list_pending_reviews for review items or resume_run/certify_run for run lifecycle actions. The agent must infer all routing from the name and the sibling list.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds little behavioral detail beyond the return purpose and does not mention auth, rate limits, or return format. It does not contradict annotations, but it mostly restates the obvious.

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 no filler, and the core action is front-loaded. It is appropriately sized for a zero-parameter health check.

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

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

For a simple read-only diagnostic with no inputs and an output schema, the description is largely sufficient. Annotations cover behavior and the output schema can describe return values, though adding auth or usage prerequisites would make it complete.

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

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

The tool takes zero parameters, so the schema baseline is 4. There are no parameter semantics for the description to clarify, and schema coverage is already 100%.

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: 'Return service health.' It is clear what the tool does and is implicitly distinct from the workflow-oriented siblings. It does not explicitly name an alternative, but no sibling overlaps with its diagnostic purpose.

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 phrase 'for diagnostics' gives an implied usage context, suggesting it should be called when checking service health. However, it does not state when-not to use it, prerequisites, or alternatives, so guidance 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?

The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description does add domain context — these are approval/decision items that block run progression — which is genuinely useful beyond the annotations, but it discloses nothing about ordering, counts, or what happens after a decision.

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, which is structurally fine. However, brevity here comes at the cost of under-specification rather than economy — there is no wasted wording, but not enough wording either.

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?

An output schema exists, so return values need no explanation, and the annotations cover the safety profile. Even so, for a run-scoped read tool the description omits the run_id scoping and any usage cue, leaving it minimally adequate but with clear 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 description coverage is 0% and the only parameter is required (run_id), documented solely by its title. The description never mentions run_id or explains that the listing is scoped to one run, so it fails to compensate for the schema 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?

The description conveys what the items are — human decisions that gate the run — but never states the action the tool performs (list/return pending review items). It is inferable from the name list_pending_reviews, yet the sentence alone could be read as describing a review workflow rather than a retrieval call. It also never ties the items to a specific run, so differentiation from siblings like get_run_status is only partial.

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 guidance, no prerequisites, and no mention of alternatives such as get_run_status or submit_mapping_review. The phrase 'before the run can continue' hints at the blocking context but stops short of saying when an agent should call 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?

Adds real behavioral context beyond the annotations: aggregates only, sample_rows=0 by construction, and values never leaving the source adapter — important data-governance behavior. It also discloses the run-state side effect (pauses after profiling). The only friction is the word "read-only", which sits in mild tension with readOnlyHint=false; the description resolves this by explicitly stating it starts a run, but the phrasing could momentarily mislead.

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 lines, front-loaded with the purpose, then privacy behavior, then workflow — order is sensible and there is no filler. Minor deduction because `sample_rows=0` references a parameter that does not exist in the input schema, which adds a small decoding cost for 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?

An output schema exists, so return values need not be described. The description covers purpose, data-handling constraints, and the required next step for a run-based tool, which is most of what an agent needs. The remaining gap is the undocumented `schemas` parameter, which is the one thing a caller needs in order to control scope.

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 neither of the two parameters (connection_id, schemas) is explained in the description. In particular the optional `schemas` scoping parameter — which lets the caller narrow profiling to specific schemas — is never mentioned, so an agent could miss that it can limit scope.

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 ("Profile a source") and enumerates the exact outputs computed — row counts, null rates, distinct counts, patterns, PII classes. It also positions itself in the pipeline by naming propose_canonical_mapping as the follow-up step, which distinguishes it from siblings like generate_dbt_artifacts or run_sandbox_tests.

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

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

Clearly says the tool "starts a run that pauses after profiling" and that the agent must "continue it with propose_canonical_mapping", which is actionable sequencing guidance. However, it never states when NOT to use it or what prerequisites exist (e.g., whether an onboarding run must be started first), so it stops short of full when/when-not guidance.

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

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

Annotations establish this is a non-read-only, non-idempotent, non-destructive write, so the safety bar is partly met. The description adds real value beyond that: deterministic scoring, routing of uncertain/PII-bearing/metric-bearing/conflicting cases to human review instead of guessing, and halting at the mapping-review 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?

Front-loaded with the core action, followed by two focused clauses on scoring behavior and the stopping point. Slightly padded by line-break formatting, but every 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?

An output schema exists, so return values need no explanation, and the description covers the action, its determinism policy, and its terminal gate. The remaining gap is the run_id contract and any prerequisite that the run be profiled first, which is only hinted at.

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% and the single run_id parameter has no schema description, so the description must carry the burden. 'For a profiled run' adds a useful constraint (the run must already be profiled), but format, source, or expected value of run_id is never explained.

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

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

States specific verbs (infer, propose) and resources (entities, joins, canonical mappings) tied to a profiled run. The 'stops at the mapping-review gate' clause distinguishes it from the downstream submit_mapping_review, though that routing is implied rather than named as a 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?

Usage is implied rather than stated: the tool operates on a profiled run and hands off at the mapping-review gate, so the agent can infer it precedes submit_mapping_review. However, there is no explicit when-to-use, when-not, or named alternative, leaving pipeline positioning 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, idempotentHint=true, and the title notes the certification requirement, so the bar is lower. The description still adds a genuinely new behavioral trait beyond the structured fields: fail-closed behavior on missing/invalid certification. It does not elaborate on what 'destructive' means here (e.g., what prior published state is overwritten), which caps it below 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 short sentences, purpose first, precondition second, with zero filler. Every clause carries information an agent needs.

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

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

With an output schema present, return values need not be described, and annotations cover safety/idempotency. The description covers purpose, precondition, and failure mode adequately for a two-parameter tool, though it leaves the destructive effect of publishing 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 0% for two required parameters, so the description must compensate. It clarifies that certification_id must reference a valid certification bound to the bundle, which adds real semantics for that parameter, but run_id is never explained and no format/typing detail is given.

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 (publish certified artifacts) and adds a scope qualifier (certified only). It is discernible from the sibling certify_run by framing this as the downstream publish step, but it never names or contrasts that 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?

The precondition 'without a valid certification bound to the bundle' implies the tool cannot be used until certify_run has produced a certification, which is useful gating context. However, it never explicitly says when to use this versus certify_run, generate_dbt_artifacts, or the other publishing-adjacent siblings, leaving the 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?

Annotations cover the safety profile (not read-only, not idempotent, non-destructive), and the description adds real behavior beyond them: gates re-check approvals and completed steps are reused rather than recomputed. It still omits auth/permission requirements and what happens to already-failed steps.

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 and followed by the key behavioral guarantee. Every clause earns its place with no filler.

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

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

An output schema exists, so return values need no explanation, and the description conveys the resume semantics well for a simple one-parameter tool. The only material gap is that the run_id parameter is left entirely 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?

There is one parameter with 0% schema description coverage, and the description says nothing about run_id at all. Although the name is fairly self-explanatory, the low-coverage rule requires the description to compensate and it does not.

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

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

States a specific verb (continue/resume) and resource (a run) plus the qualifying state (paused or failed). It implicitly separates itself from start_onboarding_run and get_run_status, but never names a sibling to make the distinction explicit.

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

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

Gives a clear trigger condition: use it for a run that is paused or failed, which contrasts with starting a new run. No explicit when-not guidance or named alternatives are provided, so it stops short of a 5.

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

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

Annotations already declare the safety profile (not read-only, not destructive, not idempotent, closed-world), so the bar is lower. The description adds real value beyond them: it runs in a disposable sandbox and pauses at a specific gate depending on outcome, which is meaningful state-transition context for a non-idempotent 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?

Two tightly worded sentences with zero filler. The core action is front-loaded and the outcome-gate behavior follows as supporting detail.

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?

An output schema exists, so return values need not be explained, and annotations cover safety. The description conveys the sandbox behavior and gate outcomes, but omits prerequisites (e.g. whether dbt artifacts must be generated first), leaving a small gap for a stateful pipeline step.

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 description says nothing about run_id. However, it is a single, self-explanatory identifier, so the practical risk of misuse is low. The description adds no parameter meaning, which caps this below the baseline-4 case for zero-parameter tools.

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

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

The description states a specific verb+resource combination: 'Build the generated project with dbt in a disposable sandbox and reconcile metrics.' This clearly separates it from siblings like generate_dbt_artifacts and certify_run. It stops short of explicitly naming which sibling it is not, so a 5 isn't warranted.

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 mention of the certification gate (success) and test-failures gate (failure), which places the tool in a pipeline, but it never states when to call it versus alternatives or what prerequisites must exist first. No explicit when/when-not guidance.

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

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

Annotations already declare the safety profile (not read-only, not destructive, not idempotent, closed world), so the description's added value is the workflow disclosure: which phases run, where execution halts, and what is returned. The phrase 'read-only onboarding' sits in tension with readOnlyHint=false, though it reads as describing source-side non-mutation (consistent with destructiveHint=false) rather than the tool's own side effects.

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

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

Three short lines, front-loaded with the action and followed by execution scope and return behavior; no filler. Slightly marred by the ambiguous 'read-only' qualifier, which is the one phrase that could mislead.

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 stateful pipeline-start tool in an eleven-tool suite, the description covers execution and terminal state well, and an output schema exists so return details needn't be repeated. However it omits prerequisites, permission requirements, and how it relates to resume_run / list_pending_reviews, which an agent needs to sequence calls correctly.

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

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

Schema description coverage is 0% for both parameters, so the description carries the full burden, yet only 'connection_id' is implied via the 'registered source (e.g. fixture:portco_a)' example. The optional 'company_id' parameter is never mentioned or explained, leaving its scoping role undocumented.

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 ('Start ... onboarding of a registered source') and enumerates the pipeline phases it executes (validation, profiling, entity/join inference, canonical mapping). It also distinguishes itself from the sibling 'resume_run' by framing this as the initial start that halts at the first human review gate.

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 stopping condition ('stops at the first human review gate') implies the natural follow-up (list_pending_reviews / resume_run), but no explicit when-to-use or when-not-to-use guidance is given and no alternative is named. An agent must infer the relationship to the ten sibling tools.

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

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

Annotations cover the safety profile (non-read-only, non-idempotent, non-destructive), and the description adds genuinely new context: reviewer-principal authorization and the fact that approval is bound to the content hash of items under review (implying stale approvals are rejected). It stops short of describing retry/idempotency behavior or what happens to prior decisions.

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?

Short and front-loaded: purpose sentence first, then eligibility and decision vocabulary. The embedded line breaks and indentation are slightly noisy but 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?

Output schema exists, so return values need no explanation, and annotations carry the mutation safety profile. For a 3-param mutation tool the description covers the essential decision vocabulary and the content-hash binding, leaving only minor gaps around run state prerequisites and array completeness.

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 does document the decision values (approve | reject | approve_with_override) and the override keys, which mirrors the sparse schema description. But run_id and comment semantics, and whether the decisions array must cover every pending item, remain undocumented.

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: 'Record a human reviewer's decisions for the run's current gate', with a clear scope (current gate of a run). It is distinguishable from list_pending_reviews and certify_run by its reviewer-decision focus, though it does not name 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?

'Reviewer principals only' gives an eligibility constraint, and the enumerated decisions imply what the call is for. However, there is no explicit when-to-use guidance versus adjacent tools such as certify_run or resume_run, nor an indication of what state the run must be in before submission.

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