peck_post_tx

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses that the tool (1) constructs a Bitcoin Schema transaction, (2) broadcasts it, (3) has near-real-time propagation, and (4) signs using a keychain-resident agent identity. It also indirectly hints at a dependency: the agent_account must exist in the keychain. This is meaningful behavioral context beyond the schema. However, it doesn't disclose failure modes (e.g., insufficient funds, missing identity) or whether the broadcast is irreversible, so it falls 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?

The description is compact at three sentences and front-loads the primary action ('Post to the BSV social graph') before the mechanics. Every sentence earns its place: action, mechanism, outcome, and signing context. It loses a point because the signing detail is slightly buried in the final sentence and could be more prominently placed near the agent_account parameter, but overall it's tight and well-ordered.

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 write tool with no annotations and no output schema, the description is fairly complete: it explains purpose, mechanism, outcome, and signing identity. The agent can determine prerequisites (keychain identity existence, referenced via peck_fleet_spawn). Missing elements include cost/fee behavior, failure modes, and whether a post can be deleted, but for a social post tool the essentials are covered. There is no output schema to explain return values, so the description carries the full burden here, which it mostly meets.

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 schema already documents all parameters. The description adds marginal semantic value by identifying the signing identity mechanism ('keychain-resident agent identity') which connects to agent_account and hints at why agent_account exists. It also references peck_fleet_spawn for creating identities, which adds cross-tool context beyond the schema. This modest addition justifies a 3 baseline rather than lower, but the description doesn't explain tag/channel format or content constraints beyond what the schema has.

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 ('Post'), a specific resource ('BSV social graph'), and the mechanism ('Builds a Bitcoin Schema tx (MAP+B+AIP) and broadcasts it'). It clearly distinguishes this from read-only siblings like peck_feed or peck_trending, and from other write tools like peck_payment_tx or peck_follow_tx which target different resources. The phrase 'Your post appears in peck.to within seconds' clarifies the observable outcome.

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 tool is for creating posts rather than reading content or performing other tx types, which is clear against the sibling list. However, there is no explicit when-to-use guidance, no exclusions, and no explicit comparison to alternatives like peck_tag_tx or peck_thread. The context is clear enough for an agent to pick this tool for posting, but it doesn't name alternatives or conditions.

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