Attest a dataset against its schema

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

Goes well beyond the annotations by naming exactly which files are written into dataset_dir (attestation.intoto.json, attestation.dsse.json, verify.py), which is the real side effect behind readOnlyHint=false. It also discloses interoperability (cosign, actions/attest) and the runtime dependency of the emitted verifier (duckdb only), and the idempotentHint=true claim is consistent with re-running against the same schema and seed.

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

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

Front-loaded with the purpose, then mechanics, then Args/Returns; every paragraph earns its place. Minor waste in the Returns block, which restates keys that the existing output schema already declares.

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 the full call contract for a 4-param tool with a nested, free-form schema object: provenance of each argument, the write side effects, and the interpretation of the PASSED/FAILED result. Since an output schema exists, the return-value coverage is more than sufficient.

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

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

Schema description coverage is 0%, so the description must carry the load, and it documents all four parameters in an Args block. It adds meaning the schema cannot: dataset_dir layout (one `<table>.csv`/`.parquet` per table, matching generate_from_schema's output_dir), that schema must be the same dict, that seed is recorded in the Statement, and that max_invariants caps the response payload.

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 schema-implied invariants with DuckDB against the files and pins each file by SHA-256, producing in-toto/DSSE attestations. The artifact list makes the output concrete. It never distinguishes itself from the close sibling `audit_dataset`, so an agent must infer the difference between auditing and attesting.

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 ("Use it after generate_from_schema with the same schema and seed") and tells the agent what to do with the result ("report `result` to the user: PASSED means every declared property holds"). No exclusion against `audit_dataset` or other validation siblings, but the precondition is clear.

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