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

The description adds meaningful behavior beyond annotations: records are tamper-evident, obligations are pinned to current version plus integrity hash at signing time, and the record captures the specific mapping as of that date. This complements the annotations without contradicting them, though it does not describe return values or post-signing behavior.

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?

Four sentences, each earning its place: the action and scope, the integrity-pinning behavior, the design-vs-operating distinction, and the subscription/auth requirement. It is compact and front-loaded, though slightly dense rather than minimal.

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

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

For a 9-parameter tool with no output schema, the description gives enough context on what the tool does, when to use it, why it is evidence, and what prerequisites exist. It does not explain response shape, but the schema and behavioral description make the call semantics clear.

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%, and each parameter already has a high-quality description. The tool description adds context around control, nodes, and api_key but does not need to compensate because the schema carries the full parameter semantics. This meets the baseline for a fully covered 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 action and object: 'Sign a tamper-evident record of one of YOUR OWN controls or policies and the Bidda obligation nodes it maps to.' It clearly scopes this as a design-side control attestation and distinguishes it from run receipts, so an agent can tell this tool apart from generic create or evidence 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?

Provides clear usage context: this is 'design-side evidence' versus operating-side evidence from 'run receipts.' It also gives an explicit prerequisite: an active Bidda subscription and api_key. It lacks explicit sibling tool names like 'use create_attestation instead,' but the context is sufficient to route the agent correctly.

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