Get JobZyn candidates

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds meaningful behavioral context: it mentions the read scope, clarifies that 'since takes priority over from', explains pagination via 'Use total to fetch remaining pages', and warns about personal information and that no files are downloaded. This goes well beyond the annotations and provides actionable operational insights.

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, front-loaded with the core purpose, followed by essential operational details. Every sentence adds value: the purpose, the supported options, and the pagination/data-sensitivity note. 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?

With six parameters but only one required, the schema covers all parameter meanings, and annotations cover safety. Since there is no output schema, the description provides some guidance on response usage ('Use total to fetch remaining pages') and alerts to personal information. It does not describe the candidate object structure, but for a paginated read tool that is likely sufficient for an agent to invoke correctly. Minor gap: no explicit mention of the response format beyond pagination.

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 100% – every parameter has a description. The tool description repeats some schema details (default pageSize, 1-based page, priority rules) but adds little new parameter-level meaning. It does introduce the concept of using 'total' for pagination, which is output-related, not parameter-specific. Since the schema already documents each parameter thoroughly, the description does not significantly enhance parameter understanding.

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 action: 'Retrieve one page of applications for an external job ID' – a specific verb, resource, and scope. It also names the HTTP endpoint and read scope, distinguishing it from sibling tools like jobzyn_create_job or jobzyn_unpublish_job, which are mutations. The purpose is unambiguous.

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 conveys when to use this tool (to fetch candidate applications) and provides operational details (pagination, date filters, priority rules). It does not explicitly contrast it with alternatives, but the sibling names (create, update, unpublish, link) make the read-only distinction obvious. There is no misleading guidance; the context is clear but lacks an explicit 'use this instead of X' statement.

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