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

With no annotations, the description carries the full burden and does well: it discloses the destructive pruning of older packets beyond the retention count, the Kubernetes-mode refusal, and explicitly that no API token is needed. It stops short of describing failure behavior (e.g. disk-space or pg_dump errors) or how success is reported, so it is strong but not exhaustive.

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

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

The purpose is front-loaded in the first clause and three sentences stay tight with no filler. The packing of mechanism, pruning, CLI equivalence, k8s refusal and token behavior into single clauses is dense but each clause carries real information.

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

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

For a no-annotation, no-output-schema mutation tool this covers purpose, timing, destructive side effect, auth, and environment constraint well. The remaining holes are the undocumented dry_run parameter and any indication of what a successful run returns or where the packet path 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 coverage is 67% – file and retain are documented in the schema, but dry_run has no description anywhere. The description contextualizes two of the three params ('under backups/' for file, 'pruning older packets beyond the retention count' for retain) but never mentions the dry-run capability, which an agent would need to discover a non-destructive preview mode.

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

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

Names a specific verb+resource (creates a compressed backup packet of the database), the underlying mechanism (pg_dump via the database-tools Compose service), and the destination (backups/). This is unambiguous and, unlike the sibling tools which are all doctor/module/schema utilities, leaves no doubt about what it produces.

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

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

Explicitly says when to reach for it: 'before a risky operation or as part of a backup routine.' It also identifies the equivalent CLI path (copalibre backup) and a hard constraint (Kubernetes-mode refusal), which functions as a when-not condition. No true alternative tool exists among the siblings, so the lack of a named alternative is not a real gap.

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

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

With no annotations the description carries full burden, and it does well: it discloses the output is byte-identical to what validation and installation enforce (a meaningful consistency guarantee) and that no API token is required (auth requirement). It does not state read-only/non-mutating behavior or caching, but 'Returns' plus the zero-param schema make that clear.

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 sentences, front-loaded with the return value, then the routing instruction, then the auth note. Every sentence carries distinct information and nothing is padded.

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

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

For a zero-param, read-only schema introspection tool with no output schema, the description covers what is returned (JSON Schema plus field-level explanation), when to call it, and the auth situation. Nothing an agent needs to invoke it correctly is missing.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to add or explain. No misleading parameter claims are made.

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

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

States a specific verb and resource ('Returns the discipline descriptor's machine-readable JSON Schema') plus the added payload ('field-by-field explanation of what each declaration governs'). It also distinguishes itself from siblings by naming copalibre_descriptor_validate and positioning itself against copalibre_profile_schema's domain.

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

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

Gives explicit sequencing guidance: 'Use this first when authoring a new discipline module, before writing any JSON.' That tells the agent when to pick this over writing JSON blind, and the mention of descriptor_validate implies the validation counterpart. It stops short of naming the profile_schema sibling as the alternative for profile authoring.

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

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

No annotations, so the description carries the burden, and it does disclose real behavioral traits: it runs 'the same validator the installation path applies', so acceptance here equals installation acceptance, and it needs no API token. It stops short of describing the output/failure shape or how errors are reported, which is the remaining gap for an unannotated 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 core action, followed by differentiation, usage ordering, and a token note. The parenthetical example list is slightly dense but each clause adds selection value; no filler sentences.

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

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

For a one-parameter validator with a generic object schema and no output schema, the description supplies the needed workflow position, equivalence to install-time validation, and no-auth note. It could better state what a validation result looks like, but an agent has enough to invoke it correctly.

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

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

Schema description coverage is 0% and the single parameter is an undetailed nested object, so the description is the only source of meaning. It characterizes the parameter as a candidate descriptor and enumerates example cross-field constraints (odd best-of series span, resolution class vs. resolution script exclusivity), which conveys the semantic shape the input must satisfy.

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 ('Validates a candidate discipline descriptor document') and immediately distinguishes itself from siblings: it 'never authors a descriptor, only judges one already drafted', contrasting with copalibre_descriptor_schema. An agent can tell what it does and what it does not do without any other context.

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

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

Gives explicit sequencing and named alternatives: 'Use it after copalibre_descriptor_schema, iteratively, before copalibre_module_scaffold/_validate_local.' The iteration guidance and position in the workflow leave nothing to inference.

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

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

With no annotations, the description carries the full burden and does disclose real behavioral traits: no API token required, it inspects local configuration, and it connects directly to the database rather than through apps/api. It leaves open whether the writability check mutates anything and does not describe what a failing run returns, which keeps it from a 5.

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

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

Three tightly packed sentences: what it checks, when to run it, and how it operates. The check list is front-loaded in the first sentence and every clause adds 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?

Complexity is low and the enumerated check categories effectively stand in for output content. With no output schema, however, the description never says what a result or failure report looks like, which is the one remaining gap for a diagnostic 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?

The tool takes zero parameters, so the baseline is 4 and there is no parameter semantics to add or omit. The description correctly signals that all behavior is environment-derived rather than argument-driven.

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 (checks) and resource (this CopaLibre installation's configuration) and then enumerates exactly what is verified: secrets, database reachability, JWKS, object storage, and path writability. No sibling among the module_*/descriptor_*/profile_* tools performs installation health diagnosis, so an agent can route to it unambiguously.

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

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

Explicitly gives two usage contexts: before starting an installation, and diagnosing an installation that is failing. That is clear positive guidance, but there is no explicit when-not or named alternative tool, so it stops short of a full 5.

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

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

With no annotations, the description carries the full burden and does disclose non-obvious behavior: it runs the same direct-database install as the CLI, needs no API token, and writes to the local database and object storage rather than apps/api. It still omits idempotency, failure behavior, and permission requirements, so it falls short of full transparency.

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 resource, followed by version/source qualification and then the runtime context. Three dense sentences with no filler, each adding distinct 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?

No output schema or annotations exist, so the description must stand alone; it covers what gets installed, from where, and the direct-DB/no-token install path. It leaves gaps around re-run safety and the effect of allow_unsatisfied_capabilities, which keeps it from a 5.

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%: range and source are documented in the schema and reinforced by the description (latest by default, source must be allow-listed). However, required alias and the boolean allow_unsatisfied_capabilities are unexplained in both places, and the latter sounds consequential; the description does not compensate for that 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 (installs) and resource (discipline or tournament-profile module), plus scope qualifiers: latest version or a semver range. It clearly occupies a different niche from siblings like copalibre_module_list, copalibre_module_remove, and copalibre_module_verify.

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 concrete trigger: use it to add a module an installation needs before creating a tournament with it. There are no explicit exclusions (e.g., when to prefer submit/scaffold), but the use context is clear enough to route an agent.

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

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

With no annotations, the description carries the full burden and delivers useful non-obvious context: it requires no API token and reads directly from the database rather than through apps/api. It does not explicitly state read-only/no-side-effects or any result-size limits, but the disclosed data path is substantive.

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: purpose first, then when to use it, then the auth/data-source caveat. Every sentence adds information and none is redundant.

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

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

For a zero-param, no-annotation, no-output-schema tool this is nearly sufficient — it names the returned fields and the data source. It could be slightly richer about result shape or ordering, but nothing essential for calling 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool applies.

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

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

States a specific verb and resource ('Lists every installed discipline and tournament-profile module') and even enumerates the returned fields (alias, version, kind, source, attribution). It is clearly distinct from add/remove/verify siblings in intent, 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?

Gives two concrete situations for use: checking what an installation can run before creating a tournament, and confirming an expected module is installed. No when-not-to-use or named alternative is provided, so it falls short of the 5 bar.

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

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

With no annotations, the description carries the full burden and does well: it discloses the all-versions scope, the atomic refusal ('removing nothing') tied to a concrete precondition, that it writes directly to the database, and that no API token is needed. It does not state irreversibility, required permissions, or response shape, which keeps 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?

Three sentences that front-load the destructive action and its guard condition before the usage hint. Minor redundancy between 'Use it to uninstall a module no longer needed' and the opening removal statement, but nothing is padded.

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

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

For a single-parameter mutation tool with no annotations and no output schema, the definition covers behavior, precondition, backend mechanism, and auth requirements. The remaining gaps are alias value format and what the caller gets back on success, which are modest but real.

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 required parameter at 0% schema description coverage, so the description must compensate. 'By alias' identifies the key and its role, but never defines the alias format (path vs. name, discipline vs. profile disambiguation) or validation rules, leaving the agent to guess what a valid value looks like.

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 ('removes') plus resource ('discipline or tournament-profile module') plus scope ('every installed version ... by alias'). An agent can immediately distinguish this from siblings like copalibre_module_add, copalibre_module_verify, or copalibre_module_list 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?

'Use it to uninstall a module no longer needed' gives clear context for invocation, and the refusal precondition ('if any started tournament still references it') tells the agent when the call will fail. It stops short of naming an alternative tool or describing recovery paths, but the when-to-use is unambiguous.

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

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

With no annotations, the description carries the full burden and does well: it discloses that no API token is required, that the output is a tagged local Git repository (a filesystem side effect), and that content is seeded from valid catalogue documents rather than guessed. It omits overwrite behavior when output_directory or alias already exists, which is the main remaining gap for a generator 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?

The purpose is front-loaded in the first clause, and the two sentences stay on task with no filler. It is somewhat dense with parenthetical asides (segments/events/statistics, stages/points/tiebreak), which adds length but earns most of it by clarifying the seeded output.

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 and no annotations, so the description is the only source of behavioral context, and it covers the artifact and auth well. However, for a 7-parameter generator it should explain at least how alias and output_directory affect the created repository, which it entirely omits.

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% across 7 parameters, so the description must compensate and largely does not. It explains the content differences between the two 'kind' enum values (discipline vs tournament-profile), but name, alias, author, licence, source_url, and output_directory are never mentioned, leaving most 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 artifact ('Generates a structurally-valid discipline or tournament-profile module package ... as a tagged local Git repository'), and the seeding mechanism (from CopaLibre's own catalogue documents) clearly separates it from siblings like copalibre_module_add or copalibre_module_list. An agent can identify the tool from the first sentence alone.

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?

'Use this first when authoring a new module' gives an explicit ordering cue in the authoring workflow, and 'ready to edit, validate, and submit' outlines the downstream stages. It stops short of naming the specific sibling tools (e.g. copalibre_module_validate_local, copalibre_module_submit) that follow, so alternatives are 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?

With no annotations present, the description carries the full burden and meets it: it discloses the side effects (fork, branch creation, push, PR open), the hard limit (never merges), the auth model (no API token required), and the external prerequisite (`gh` authenticated with fork permission). This is exactly the operational context an agent needs before invoking an irreversible remote action.

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 sentences, front-loaded with the action, then the usage condition, then the auth requirements. No filler and no repetition of structured fields.

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

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

There is no output schema, so nothing is owed on return values, and the description fully covers behavior, sequencing, and auth. The only meaningful gap is the undocumented parameters, which is the sole reason this is not a 5.

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% across three parameters (path, base_branch, upstream_repository), so the description must compensate and largely does not. It gestures at the concepts — local module package, new branch, target repository — but never maps them to parameter names, formats, or defaults, leaving all three effectively 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 multi-step verb chain (forks, copies, pushes, opens a pull request) on a named resource (copalibre-modules), and explicitly frames its position in the workflow relative to copalibre_module_scaffold and copalibre_module_validate_local. An agent can distinguish this from the other module_* siblings without opening any schema.

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

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

Gives an explicit trigger ('once a scaffolded module has been edited and passes copalibre_module_validate_local') and an explicit boundary ('this is the last step, handing the module to a human reviewer; it never merges anything itself'). The when-to-use and when-not-to-use are both stated rather than inferred.

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

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

With no annotations present, the description carries the burden and does well: it discloses that nothing is fetched or installed, that no API token is required, and that the check is identical to the one baked into copalibre module add/verify. That establishes a side-effect-free, offline, unauthenticated operation. It stops short of describing failure output or what is reported when validation fails, and no output schema exists to cover that.

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

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

Two sentences, purpose front-loaded, then usage. Every clause earns its place: scope, non-fetching behavior, equivalence to existing commands, and the auth-free property. No filler.

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

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

For a one-parameter, no-annotation, no-output-schema validation tool, the description covers what is checked, when to run it, and that it has no network or auth side effects. The main residual gap is what the tool reports on success/failure, which is not documented anywhere given the absence of an output schema.

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

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

Schema coverage is 0% and the single 'path' parameter is completely undocumented in the schema, so the description must compensate. It does add real meaning by specifying that the path is a local module package directory expected to contain manifest.json and artifact.json, which is more than the bare 'string' type conveys. It does not clarify relative vs absolute paths or the error when the directory is malformed.

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 (validates) and a precisely scoped resource (a LOCAL module package directory containing manifest.json + artifact.json), and immediately marks it as distinct from the remote install/verify siblings by saying it fetches and installs nothing. An agent can distinguish it from copalibre_module_verify and copalibre_descriptor_validate 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?

Gives explicit timing: 'Use it after editing a scaffolded module, before trying to install it locally or submit it,' which effectively routes the agent relative to module_add/module_verify/module_submit. It also equates the check to what those two commands apply, so the agent knows when it is redundant. No explicit negative case (e.g., what to use for remote packages) is stated, keeping it just short of a 5.

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

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

With no annotations, the description carries the full burden, and it does meaningful work: it discloses the authentication posture ('needs no API token'), the execution mechanism (direct-database checks, not API calls), and the reporting behavior (per-module PASS/FAIL with failure detail). It never states explicitly that nothing is mutated, though 're-validates' and 'check' strongly imply a read-only 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?

Three tight sentences with the core action front-loaded, followed by the situational cue and then the implementation/auth footnote. Each sentence adds distinct information and none is redundant with the schema.

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

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

For a zero-parameter, no-output-schema verification tool with no annotations, the description covers purpose, when to use it, output semantics, and auth requirements. It leaves open whether a FAIL result is reported in-band only or also raises an error, and says nothing about cost/latency when many modules are installed.

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, which sets the baseline at 4, and there is nothing parameter-related for the description to clarify or compensate for.

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 precise verb plus resource and scope: 'Re-validates every installed module's stored document and assets against the running CopaLibre core version,' and even states the output shape (PASS/FAIL per module with failure details). It does not, however, explicitly contrast itself with the nearby sibling copalibre_module_validate_local, which an agent could plausibly confuse it with.

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

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

'Use it to check installation integrity, especially after an upgrade' gives a clear triggering context, and the mention of running the same checks as `copalibre module verify` anchors it to a known workflow. No when-not conditions or named alternatives (e.g. copalibre_doctor) are offered, 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?

With no annotations, the description carries the full burden and does well: it discloses the no-token auth requirement and, more valuably, that the returned schema is byte-identical to what validation and installation check against — a consistency guarantee an agent cannot infer from the schema. It does not describe response size or whether the field explanations are inline or a separate section, but for a read-only tool the safety profile is adequately clear.

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 return value and then the usage trigger; nothing is repeated from the title or the schema. The 'not just its shape' clause earns its place by telling the agent the output is richer than a bare schema.

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

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

No output schema exists, so the description must characterize what comes back, and it does: the JSON Schema plus field-by-field semantics, plus the auth posture. For a zero-parameter read tool this is enough for an agent to call it correctly without opening anything else.

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 input schema is empty with zero parameters, so the baseline is 4 and there is no parameter behavior the description could or should add. It correctly omits per-argument detail.

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

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

Names a specific verb and resource (returns the tournament profile's JSON Schema) and pins down the deliverable precisely: the schema plus a field-by-field explanation of what each declaration governs. It also implicitly distinguishes itself from copalibre_profile_validate by naming that sibling as a consumer of the same artifact.

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

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

Explicitly states the trigger — 'Use this first when authoring a new tournament-profile module, before writing any JSON' — which is exactly the decision point an agent needs. It stops short of naming when not to use it or pointing at the neighboring copalibre_descriptor_schema for descriptor work, so no exclusions are given.

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

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

With no annotations, the description carries the full burden and does well: it discloses that the tool calls the same validator as the installation path, so acceptance is exactly installation acceptance, and that it never authors profiles and requires no auth token. It doesn't cover how failures are surfaced, but the core behavioral contract is clear.

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 core action and immediately followed by the distinguishing constraint and the workflow position. No filler.

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

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

For a validator with no output schema and no annotations, the description establishes what is validated against and where it sits in the pipeline, which is what an agent needs to invoke it. The main gap is how the pass/fail result or errors are returned, which 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 coverage is 0% and the single parameter is an opaque nested object with no documented structure. The description compensates only indirectly by pointing at copalibre_profile_schema as the producer of a valid profile, but adds no internal shape or format detail.

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

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

States a specific verb+resource ('Validates a candidate tournament-profile document') and clarifies the scope precisely: it judges an existing draft rather than authoring one. This distinguishes it cleanly from siblings like copalibre_profile_schema and the module scaffold/submit tools.

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

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

Explicitly places the tool in the workflow: use after copalibre_profile_schema, iteratively, and before copalibre_module_scaffold/_validate_local. It also notes it needs no API token, removing a common invocation blocker.

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

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

With no annotations provided, the description carries the full burden and does substantial work: it declares the operation idempotent and safe to re-run, discloses that it writes directly against the database rather than the API, and confirms no API token is required. It omits runtime cost, locking/blocking behavior, and required permissions, which is why it stops short of a 5.

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

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

Three sentences, front-loaded with what it does, then when to use it, then the implementation/safety note. Every clause carries distinct information with no redundancy or 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 zero-annotation, no-output-schema repair operation, the description covers purpose, scope, triggers, safety, and auth requirements. Minor gaps remain — success/failure reporting, permissions, and expected duration — but nothing essential for correct invocation 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 50%: tournament_alias is already documented ('omit for all') in the schema, while organization_alias has no schema description. The description clarifies the relationship between the two (one tournament *within* an organization) but never explains what form an organization_alias takes, so it only partially compensates 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 and resource ('Recomputes every folded statistic total from source match facts') plus the exact scope options (organization or one tournament within it). No sibling tool touches statistics, and the description names both the domain object and the source of truth, so the agent can distinguish it immediately.

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

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

Gives concrete trigger conditions: after a data backfill, a statistics-engine fix, or to repair drift. It does not state when NOT to use it or name an alternative maintenance tool, but the sibling list contains no overlapping tool, so the routing guidance is effectively complete.

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

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

With no annotations, the description must carry the behavioral load, and it does: it declares the operation is non-mutating ('without applying any migration or altering any installed data') and notes 'Needs no API token', both valuable safety/auth facts. It still omits how results are surfaced (format, exit semantics), leaving a minor 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?

Purpose is front-loaded in the first clause, and each subsequent sentence (non-mutation guarantee, no-token note) earns its place. The opening sentence is dense with a mid-sentence clause, which slightly hurts scannability but the content is not padded.

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

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

For a single-parameter, no-output-schema check tool, the description covers intent, precondition, side-effect profile, and the two categories of results (incompatibilities and pending migrations). Only the exact result structure is unspecified, which is acceptable given there is no output schema to lean on.

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

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

Schema description coverage is 100%, so the single parameter target_version is already documented as 'CopaLibre semver to check'. The description refers to 'a target version' but adds no format or constraint detail beyond the schema, 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 (checks) and resource (installed modules against a target CopaLibre version) and adds the secondary output (database migrations that would run). This is clearly distinguishable from siblings like copalibre_doctor or copalibre_module_validate, which check other things.

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

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

Explicitly frames usage as a 'pre-flight gate before switching an installation to a new CopaLibre version', which tells the agent the triggering condition. It does not name a sibling alternative or state exclusions, so it stops short of the top mark.

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