plainhub_post

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

With no annotations, the description carries the full load and does so: it discloses that only the local file is written, that sync is a separate step, that messages are never overwritten, and the exact rejection rules (secrets, summaries over 120 characters, bodies over 4KB). It even explains the return value and the degraded case when the repository is not on GitHub.

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 file location, then usage timing, then the sync caveat, then return value, then limits, then an example. Despite its length every sentence supplies a fact an agent needs to call this correctly; nothing is redundant padding.

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, and the description compensates by describing the returned link and the fallback message when the repo is not pushed. For a 6-parameter write tool with side effects and refusals, all decision-relevant information is present.

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 already 100%, so the baseline is 3, but the description adds real value on top: it restates the hard limits that govern body and summary, ties verdict/role to workflow moments ('reviewers post their verdict'), and closes with a complete worked example showing a valid combination of all required fields.

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 ('Add a message to a work thread in the ledger') and pins down where it lands (.agents/threads/<thread>/NN-<role>.md, next free number). That file-path detail cleanly separates it from ledger readers like plainhub_ledger_read and plainhub_ledger_thread.

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 trigger points: 'when you start (what you will do and what counts as done), after you commit, and when you finish; reviewers post their verdict.' It also routes the agent to the sibling that shares the file ('run plainhub_ledger_sync to share it'), so the write-vs-sync split is unambiguous.

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