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

Goes well past the annotations: discloses runtime latency ('takes a few seconds'), a hard availability constraint (machine must exist), and concrete rate limits (burst of 10, then one every 6 seconds) with mitigation advice. This also coherently explains the idempotentHint=false annotation, since runtime logs are fetched live.

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-loads the capability, then splits into push and runtime paragraphs, then closes with the action to take. Dense but every sentence carries operational information; no filler or restatement of the title.

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 needn't be described. The description covers the things the schema can't: which kind to try first, why a log is empty/unavailable, latency, and rate limits. Nothing an agent needs to invoke it correctly is missing.

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 coverage is already 100%, but the description adds real meaning: push is 'the last deploy's combined output: upload, dependency install, and start' and is the default, while runtime is 'the last 200 lines of the app's own journal live from the machine'. That is substantially more than the schema text conveys.

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 (fetch) and resource (a spawnpoint project's logs) plus the intent (diagnose a failed deploy or misbehaving app). It then separates the two modes of the tool (kind=push vs kind=runtime, including the default) so the agent knows exactly what each call yields.

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?

Explicit ordering guidance — 'Read it first when a deploy errors' — plus a conditional on runtime ('works only while the machine exists') and an anti-polling instruction ('read it once per fix rather than polling'). The only gap is that it never names the sibling watch_deploy as an alternative for live deploy monitoring.

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