workflowmoves_wordpress_schedule_post

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

Beyond the annotations (destructive, openWorld, non-idempotent, not read-only), the description discloses that the call is asynchronous and returns a retained background job that must be polled, which materially changes how an agent should use it. It also enumerates the effect classes (write, network, publication) and warns of conditional inference/download effects resolvable via danceflow_component. It stops short of saying what is mutated, whether scheduling is reversible, or what "operator-bound credentials" requires of the caller.

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?

Three sentences, no filler, and the follow-up action is stated up front. But the phrasing is dense internal jargon ("canonical guarded transport", "base effect flags") that spends words on vocabulary the agent already has in annotations rather than on the missing purpose statement.

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?

An output schema exists, so return values need not be described, and the async/polling behavior is covered. Missing for a destructive, non-idempotent, network-touching write are the essentials: what a "schedule" means here (when, to which site/post), that the manifest carries the payload, and what the receipt guarantees. Adequate to call, not adequate to call confidently.

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 only 50%, and the required nested fields manifest, receipt_out and expected_manifest_sha256 have no schema descriptions at all. The description hints at receipt_out ("a new receipt") and maps "Base effect flags: write, network, publication" onto the permissions object, but the two most consequential parameters, the manifest and its expected SHA-256, are left entirely unexplained, leaving the caller to guess what the manifest must contain (presumably the schedule itself).

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 says to "invoke the canonical guarded WordPress transport" but never states the actual outcome, which is scheduling a WordPress post. The verb is about internal transport machinery rather than the resource being acted on, so an agent must fall back on the tool name to infer purpose. It does name two relevant siblings (danceflow_job_status, danceflow_component), which keeps it above a pure tautology.

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?

"Returns a retained background job; poll danceflow_job_status" gives clear post-invocation guidance, and pointing at danceflow_component for conditional effects is useful routing. However, there is no guidance on when to pick this over the closely named siblings workflowmoves_wordpress_publish_post and workflowmoves_wordpress_create_draft, which is the main selection ambiguity an agent faces here.

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