amazon_jobs_search

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

With no annotations, the description carries the burden. It notes the tool is credential-free, which is a behavioral trait, and mentions results include full descriptions and qualifications inline. However, it does not disclose potential rate limits, pagination behavior beyond the page parameter, or error scenarios. It adds some transparency but not extensive context.

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?

The description is a single paragraph that front-loads the tool's purpose and then briefly explains key parameters. It is concise, with no redundant wording, and provides necessary details about sort and category without excessive verbosity. It could be slightly shorter, but it's appropriately sized.

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?

For a search tool with six parameters and no output schema, the description covers essential usage: what it searches, that results include inline descriptions, how to use q and category, and the sort options. It also provides a pointer to the categories tool. While it doesn't discuss every edge case, it is sufficiently complete for correct invocation.

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 schema covers all parameters (100% coverage), but the description adds meaning: it explains the two sort values (relevant and recent), clarifies that either q or category is required and both can be used, and notes that category can be used alone. It also directs to amazon_jobs_categories for valid values. This goes beyond the schema's plain descriptions.

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 states 'Amazon Jobs search' and explains it searches Amazon's public careers site via a credential-free JSON endpoint, clearly indicating a search operation. It also mentions that results include full descriptions and qualifications, which adds specificity. However, it does not explicitly differentiate from sibling tools like amazon_jobs_job, though it does reference amazon_jobs_categories for category values.

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 explicit usage conditions: either q or category must be given, explains that category works alone without a text query, and describes the sort options. It also points to amazon_jobs_categories for the valid category list, which is helpful. It does not explicitly state when to prefer this tool over other job search tools, but gives clear guidance on parameter usage.

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