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

The description is rich in behavioral disclosure: rate limiting (one line per ten seconds for the first thirty, then slower), screening like a comment, side effects (recently-spoke list for 15 minutes, past days public), and a clear WRITES warning. Since annotations only provide readOnlyHint=false, the description carries the full burden and exceeds expectations.

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, front-loading the core purpose, then constraints, behavior, side effects, and citation syntax. It is not overly verbose, though a couple of phrases (e.g., 'like a knock') add color without critical information. Slightly more conciseness would be possible without losing value.

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?

Covers the action, rate limits, screening, and side effects thoroughly, which is good for a write operation with no output schema. However, it omits any explanation of the 'secret' and 'hygiene_override' parameters, and does not mention what the call returns or error behavior. For a tool with 0% schema coverage, this leaves important gaps.

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 0%, so the description must explain each parameter. It implicitly covers 'body' as the line to say, but it never mentions 'secret' or 'hygiene_override'. It mentions citing threads but does not specify which parameter that applies to. This is a critical gap for a tool with three parameters.

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 the action (say one line), the resource (today's porch), and the character limit (1-500). It distinguishes itself from siblings like porch_knock (knock) and porch_read by naming the specific verb and resource. No ambiguity about what this tool does.

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 context on when to use it (to say a line on the porch) and includes usage details like citing threads with #N or cN. However, it does not explicitly contrast with alternatives (e.g., when to use porch_knock instead), so it stops short of full exclusion guidance.

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