blogs_get_blog_post

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is disclosed. The description adds no extra behavioral context, such as pagination, return format, or rate limits. It doesn't contradict the annotations, but it contributes minimal value beyond them.

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 a single concise sentence with no fluff or repetition. It front-loads the core verb and resource, although it omits necessary detail. For a simple read operation, brevity is acceptable, but it borders on under-specification.

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?

The description does not clarify the meaning of 'blogId' (whether it's a blog container ID or a post ID), nor does it mention pagination or filtering options beyond the schema. With no output schema, agents must infer return structure. The provided annotations reduce the need for safety disclaimers, but the description still leaves critical usage details unanswered.

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?

The schema covers only 33% of parameters with descriptions (locationId and searchTerm), and the description only mentions Blog ID. It does not explain limit, offset, or status beyond their types and the enum in the schema. With six parameters and low schema coverage, the description fails to compensate for missing semantics.

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: get blog posts filtered by a blog ID. It specifies the resource (blog posts) and the key parameter (blog ID), distinguishing it from siblings like blogs_get_blogs or blogs_get_all_categories. However, it doesn't fully clarify whether 'blogId' refers to a blog container or the post itself, leaving slight ambiguity.

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 provides no guidance on when to use this tool versus alternatives, such as blogs_get_blogs for fetching blog containers or blogs_create_blog_post for creating posts. It omits any context about prerequisites, typical scenarios, or exclusions.

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