workflowmoves_wordpress_read_post

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false. The description adds real context beyond that: credentials are operator-bound, a new receipt is required, the result is retained asynchronously, and base effect flags are write + network with possible conditional inference/download effects resolved via danceflow_component. It still omits failure modes, retention duration, and why a 'read' tool carries a write effect flag.

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, reasonably front-loaded with the operational consequence (background job, poll status) placed early. But 'Invoke the canonical guarded WordPress transport' is jargon-heavy padding that conveys less than a plain statement of what is read, and 'Base effect flags' reads as internal vocabulary rather than agent-facing guidance.

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-shape explanation is not required, and the description correctly flags the asynchronous job pattern and the follow-up tool. Missing is the core semantic: which post is read and what data comes back, plus what the receipt_out contract means in practice for a tool whose annotations mark it non-read-only and non-idempotent.

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 50%, and only the permissions object carries a description. The mention of 'operator-bound credentials and a new receipt' implicitly explains why receipt_out is required and must be fresh, and the effect-flag sentence maps to the permissions fields. But post_id — the parameter that defines what is actually read — is never mentioned in the description, leaving a substantive gap.

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 never states that the tool reads a WordPress post; it describes the mechanics of invoking 'the canonical guarded WordPress transport' and returns a job handle. The only resource-level signal comes from the tool name, not the description. Against siblings like workflowmoves_wordpress_inventory or workflowmoves_wordpress_publish_post, an agent gets no help distinguishing this tool's actual function.

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?

There is one genuinely useful routing instruction: the call returns a background job, so poll danceflow_job_status. However, there is no guidance on when to choose this tool over the other WordPress siblings (inventory, create_draft, publish_post, schedule_post), nor prerequisites for obtaining operator-bound credentials or a fresh receipt.

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