Get Search Job Info

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

With no annotations provided, the description carries the full burden. It discloses that this is a non-destructive read operation by saying 'without re-running the search' and listing the data retrieved (status, properties, messages). It also implies it can be polled, but it doesn't explicitly state read-only or cover edge cases like job expiration or missing job errors. Still, it adds meaningful context beyond the tool name.

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 deliver the full purpose and usage context with zero fluff. The first sentence states the action and target, the second gives the trigger scenario. Perfectly front-loaded and efficient.

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 tool is simple (2 params, no output schema) and the description explains what it does, when to use it, and what it retrieves. It doesn't describe return format or error handling, but given the tool's simplicity and the clue that it returns 'status/properties/messages', it is sufficiently complete for an agent to use it correctly.

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 100%, with job_id described as 'Splunk search job id (sid)' and include_raw_content as 'Include raw job.content for debugging (default: False)'. The tool description adds no additional parameter-level detail beyond referencing 'job id' in the purpose, so it doesn't exceed the baseline for fully documented schemas.

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 'Get' and a resource 'status/properties/messages for a Splunk search job by job id (sid)', clearly distinguishing it from sibling tools like run_splunk_search or run_oneshot_search. It immediately clarifies that this is for retrieving info about an existing job, not for starting one.

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?

Explicitly states when to use: 'Use this after run_splunk_search returns a job_id when you want to poll progress or inspect errors without re-running the search.' This gives a clear trigger (after run_splunk_search) and purpose (poll/inspect errors), and implies not to use it for starting searches.

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