Poll a Leanpub job's status at regular intervals until it completes or the timeout expires, so you know when to proceed after previewing or publishing.
Poll get_job_status every 5s (configurable) until the job completes or the timeout elapses. Use right after preview_book/publish_book.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | ||
| timeoutSeconds | No | Default 120 | |
| intervalSeconds | No | Default 5, minimum 5 per Leanpub's rate limit guidance |
Changes observed during successful MCP inspections.
v0.1.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the full behavioral burden. It discloses the polling loop, the configurable interval, and the timeout condition, which are core behaviors. However, it does not clarify whether the tool is read-only, what happens on timeout (error vs. last status), or that it may issue many HTTP requests. It stops short of full transparency.
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?
Two sentences, front-loaded with the action, and every word earns its place. No filler, no repetition of schema details, and the usage hint is efficient. Perfectly concise for the tool's simplicity.
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?
The description covers the polling trigger and duration, but not the return value (what the tool ultimately gives the agent) or failure semantics on timeout. It also assumes the agent knows that 'slug' refers to the job identifier produced by preview_book/publish_book, which is only implied by 'right after.' For a 3-parameter tool with no output schema, these gaps are noticeable.
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 67%, with slug undocumented and timeoutSeconds/intervalSeconds having descriptions. The description adds meaning by linking 'every 5s (configurable)' to intervalSeconds and 'timeout elapses' to timeoutSeconds, reinforcing schema info. It doesn't explain slug's purpose, but the timing context is somewhat enriched. This is adequate but not exceptional given the schema already covers most parameters.
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 uses a specific verb ('poll') and resource ('get_job_status') and clearly describes the looping behavior until completion or timeout. It distinguishes itself from the single-shot get_job_status sibling by framing this as the waiting/polling wrapper, and it even names the trigger context ('right after preview_book/publish_book').
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 description explicitly states when to use the tool: 'Use right after preview_book/publish_book.' This gives clear context and differentiates it from a standalone status check. It doesn't list exclusions or alternative scenarios, but the primary use case is well directed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.