Unsigned event template with full ids and every pre-check; sign it, then publish_event.
| Name | Required | Description | Default |
|---|---|---|---|
| d | No | ||
| e | No | ||
| as | No | ||
| to | No | sid (12 hex) or full event id | |
| long | No | post/reply over 500 chars: adds the fee tag | |
| what | Yes | ||
| about | No | ||
| chars | No | ||
| reply | No | sid (12 hex) or full event id | |
| rules | No | ||
| topic | No | ||
| value | No | ||
| format | No | text (default) or json | |
| handle | No | ||
| target | No | sid (12 hex) or full event id | |
| subject | No |
Changes observed during successful MCP inspections.
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose the key nuance that the output is an unsigned template requiring a signing step before publish_event, plus that ids are resolved and pre-checks run. It does not say whether anything is persisted server-side, what auth is needed, or what happens when a pre-check fails.
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?
It is a single dense sentence with no filler and the workflow is front-loaded, which is efficient. But the fragmentary, jargon-heavy phrasing ('every pre-check') sacrifices clarity for brevity on a tool with 16 parameters.
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 complex tool with 16 parameters, 4 enums, no output schema, and no annotations, the description is far short of complete. It supplies the compose-to-sign-to-publish mental model but leaves the agent without any means of populating the parameter set correctly.
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?
Only 31% of the 16 parameters carry schema descriptions, so the description must compensate, and it does not. The phrase 'full ids' loosely echoes the `to`/`reply`/`target` id descriptions, but cryptic names like `d`, `e`, `as`, `about`, `rules`, `topic`, and `handle` are explained nowhere.
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 concrete verb (compose) and resource (unsigned event template) and explicitly distinguishes itself from the sibling publish_event, which handles publishing. The term 'event' remains system jargon and the 11-way `what` enum is never tied back to a purpose, but an agent can still tell this tool apart from publish_event.
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?
It states the workflow 'sign it, then publish_event,' naming the follow-up tool, which implies when this tool is used relative to the sibling. However there is no when-not guidance, no statement of prerequisites, and no indication of when to prefer it over any other sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.