posterly_status

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

Goes well beyond the annotations: it discloses that customer-caused failures (expired connections, content limits) are excluded from the rates and surfaced separately as customer_side, that it admits when there is insufficient recent activity, and that it aggregates only with no post or user data. The readOnly/idempotent hints are already in annotations, so this added semantics is the real value. Minor gap: it does not describe cadence/latency of the health data beyond the 4-hour and 7-day windows.

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?

Front-loaded with the purpose, then usage, then a disambiguation clause; every sentence carries information. It is fairly dense at roughly five sentences for a zero-parameter tool, but no clause is filler, so it stops short of being padded.

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?

With no input parameters and no output schema, the description carries the full burden of explaining return shape, and it does: overall state, active incident, per-platform breakdown, and the separate customer_side bucket. An agent knows what it will get and what it will not.

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 tool takes no parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly signals it is a no-argument call by describing call conditions rather than inputs.

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?

States a specific verb and resource ('Check posterly's own publishing health') and enumerates the three things returned: overall 4-hour state, active incident, per-platform 7-day success rate and publish counts. It also explicitly differentiates itself from the whoami 'status' sibling, so an agent can pick the right tool without opening a schema.

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?

Gives concrete when-to-use triggers ('before scheduling a time-critical post', 'when a user asks whether posterly or a platform is down or why posts are failing') and names the alternative it is not (whoami view 'status', which only reports server/package version). That is an explicit use/do-not-confuse pairing.

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