get_job_result

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

With no annotations, the description discloses key behaviors: non-error 'still processing' return, result persistence, polling recommendation, and a security warning about untrusted data. It does not mention authentication or ownership, but the main behavioral traits are covered.

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, each essential: purpose, retry behavior with lookback, and security warning. Front-loaded core action. No redundancy or filler.

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?

Given no output schema and 5 parameters, the description covers the main behavior, retry, and safety. Missing output format and ownership/authorization context, but adequate for a check-result tool.

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?

The description adds meaning for job_event_id and lookback_secs (default, max range), but ignores provider_npub, kind_offset, and timeout_secs. With schema coverage at 20%, the description only partially compensates, leaving 3 parameters without explanation.

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 clearly states the tool's purpose: 'Check the result of a previously submitted job by its event ID.' It distinguishes from sibling tools like create_job (submission) and list_my_jobs (listing) by focusing on retrieving a specific job's result. The mention of retry and polling further clarifies its role.

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 provides usage context: use after job submission, default lookback 24h, polling strategy for long jobs. Although it does not explicitly compare to alternatives, it implies when to use (checking result vs. listing or fetching files). The retry advice guides agent behavior.

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