post_to_capability

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

No annotations are provided, so the description carries full responsibility for behavioral disclosure. It does well: explains exact-match lookup behavior, fan-out semantics (one row per owner with routed_capability stamp), fire-and-forget (NOT queued-until-owner, no owner → routed_to:[] and nothing stored), webhook firing, encryption-at-rest conditionality, the exclude_self default behavior, and the distinction from point-to-point triggering. It even discloses the return shape. The only minor gap is no explicit side-effect/airtable-style side effect discussion, but the fire-and-forget disclosure is thorough.

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 well-structured with clear labeled sections (When to use, Behavior, Returns, Errors) and front-loaded purpose. Despite covering considerable ground, every sentence earns its place — no filler. The section headers make it scannable for an agent parsing behavior quickly.

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?

Given the tool's moderate complexity (6 params, routing semantics, ambiguous lane behavior), the description is remarkably complete. It explains the return contract, error conditions, edge cases (no owner), auth resolution paths, encryption behavior, and how recipients read messages. Since there's no output schema, the explicit Returns section covers that gap well. No significant missing information for correct invocation.

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 baseline is 3. The description adds modest value: it clarifies the lane semantics for reading recipients (lane='capability'), explains exclude_self's default behavior, and references RELAY_ENCRYPTION_KEY/RELAY_MAX_PAYLOAD_BYTES context. However, most parameter meaning is already well-documented in the schema itself, so the description doesn't dramatically elevate beyond 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?

The description clearly states what the tool does: routes an FYI/coordination message to the current owner(s) of a capability. It uses a specific verb+resource construction ('Route... to the current owner(s)') and explicitly distinguishes it from send_message (point-to-point) and post_task_auto (task posting), showing clear sibling differentiation within the same messaging family.

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 excellent when-to-use guidance: 'surface a finding, status, or cross-cutting update to whoever owns a domain WITHOUT knowing their name.' It explicitly states what should NOT use this tool (action-required completions MUST stay point-to-point via send_message, noting the reliability trigger implication) and names the alternative (send_message). This is exemplary usage guidance with explicit exclusions.

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