get_public_post

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

Annotations already declare readOnlyHint=true, so the description adds extra value: it discloses a single upstream read, a 500000-byte cap on body_html, and that body_status is a heuristic rather than proof of access or completeness. These details go well beyond the annotation and materially change how an agent interprets results. No contradiction with annotations.

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?

Two sentences, front-loaded with the core action and then constraints. Every clause adds essential information (auth-free, one read, size cap, heuristic status). No redundancy, and the structure makes the tool's scope immediately clear.

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 simplicity (one parameter) and an existing output schema, the description covers all necessary context: what it reads, the URL type, the auth model, the response size limit, and the caveat on body_status. An agent has everything needed to call it correctly and interpret results aptly.

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 0% (no description in schema), but the tool description states the URL must be an 'allowlisted /p/ URL', giving semantic meaning beyond type and maxLength. This partially compensates for the missing schema description. It would be a 5 with examples or format details, but a 4 is appropriate given the single parameter.

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 and resource: 'Anonymous public post read'. It further specifies the mechanism ('allowlisted /p/ URL') and clarifies that no credentials are used, which distinguishes it from authenticated tools like get_post or get_draft. The purpose is unambiguous and easily differentiated from siblings.

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 clearly indicates this tool is for anonymous reads of public posts via /p/ URLs, which implies it should be used when no authentication is available or desired. It does not explicitly name alternatives or exclusion conditions, but the context (anonymous, allowlisted) strongly guides selection. A bit more direct routing to siblings would lift this to a 5.

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