set_post_status

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

Beyond the readOnly=false annotation, the description discloses non-obvious side effects: status=posted 'also marks the session published', scheduled records the time and text so later changes appear as an action, and the change is reversible ('ready to undo' – consistent with destructiveHint=false). This is meaningful behavioral context the annotations alone don't convey.

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 action is front-loaded, but the prose is dense with stacked parentheticals ('records the time and text you scheduled, so later changes show up as an action') and the phrase 'ready to undo' is ambiguous about what is actually undoable. Every clause carries information, but readability suffers mildly.

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 7-parameter mutation tool with no output schema, it covers the transitions, the 'at' fallback, the publish side effect, and reversibility. It omits mention of parameters like tz and first_comment_posted (schema covers those) and doesn't describe the response, but that is a minor gap given the schema's completeness.

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 100%, so the baseline is 3, but the description adds real signal by linking parameter choices to situations ('pass at, the time you picked on the platform', 'status=posted with url once it is live', platform=x). It stays consistent with the schema-stated defaults rather than restating them.

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 opens with a specific verb and resource ('Record what you did on LinkedIn or X for a session's post') and names the tool's role in the post lifecycle, distinguishing it from siblings like set_post and set_published. It is clear, though the framing is a bit colloquial and never states directly that this tool writes/updates a status field.

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?

It gives explicit conditional routing: use status=scheduled after scheduling, status=posted with url once live, and it explicitly says when NOT to act freely ('only set ready or draft when asked', 'the user marks posts ready in the app'). It also tells the agent to pass 'at' when a scheduled post has no time.

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