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

Annotations already establish read-only, idempotent, and non-destructive behavior. The description adds meaningful behavioral context: results are ordered by semantic similarity, are compact, and never include full job descriptions. This helps set expectations about output shape beyond what annotations cover.

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 three sentences with no filler. It front-loads the primary purpose, then gives the most important usage nuance, and ends with a concise behavioral caveat. Every sentence contributes useful information.

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 the rich input schema, annotations, and an output schema, the description covers the core behavioral contract: what is searched, how incremental search works, and what results will look like. Nothing essential for invoking the tool 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?

The schema already documents all parameters with 100% coverage, so this is near a baseline of 3. The description adds extra value by explaining the incremental-search contract around `since` and `searched_until`, which is not fully derivable from the schema alone.

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 opens with a specific action and resource: 'Find remote jobs ordered by semantic similarity to an ideal job description.' This clearly conveys what the tool does and its core behavior. It is distinguishable from the sibling tools like get_job_details, since the scope is job search rather than detail retrieval.

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 gives explicit usage guidance for the `since` parameter: omit it for the full corpus and pass `searched_until` for incremental searches. It stops short of explicitly naming sibling alternatives and the conditions for choosing them, though the note that results never include full job descriptions implies when get_job_details would be relevant.

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