postifys_get_post_status

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

With no annotations provided, the description carries the behavioral disclosure burden. It does reveal that this is a polling operation with terminal states, which is meaningful. But it does not mention whether repeated calls are expected, what happens on timeout/error, or whether there are side effects, leaving notable behavioral gaps.

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 front-loaded sentence with no filler, efficiently conveying the polling action and terminal condition. It could have added a brief clause about the platform parameter without much bloat, but it remains appropriately concise.

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 simple polling tool this is minimally viable: it names the core identifier, the action, and the terminal states, and the schema supplies the platform enum. However, with no output schema and no annotations, it does not explain the response payload, polling behavior details, or failure semantics, so it is not fully complete.

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 clarify the parameters. It explicitly explains that postId identifies the publish job, but it completely omits the optional platform parameter, including how platform affects the lookup. The enum values in the schema provide constraints, not semantic meaning.

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 identifies a clear verb ('Poll'), resource ('async publish status'), and key identifier ('postId'), and names the terminal states ('published/failed/partial'). It is specific enough that an agent can distinguish it from publishing tools, though it does not explicitly contrast it with the similar-sounding postifys_media_status.

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 phrase 'Poll async publish status' implies this should be used after an asynchronous publish to check progress until a terminal state, which is useful contextual guidance. However, it does not explicitly state when not to use it or when a sibling tool like postifys_media_status would be more appropriate.

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