workorai

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

With no annotations, the description effectively discloses the behavioral trait of idempotency and the state transition, along with error cases. It adds value beyond the input schema by explaining the outcome for different scenarios.

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 concise with two focused sentences, front-loaded with the core action. Every sentence provides essential information without redundancy.

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 complexity (2 parameters, output schema exists), the description covers the state change, idempotency, and error conditions. The presence of an output schema means return value details are handled separately, so the description is complete for decision-making.

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 50% (apiKey has description), but the tool description does not explain either parameter. The mention of jobId in error scenarios implies its role, but direct parameter explanations are missing. Baseline 3 is appropriate.

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: accepting an employer's invitation to a job and transitioning the status from INVITED to APPLIED. It explicitly distinguishes from siblings like 'candidate.decline_invitation' and 'candidate.apply_to_job' by specifying the state change.

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 guidance on idempotency and error conditions (NOT_INVITED, NOT_FOUND), aiding correct usage. However, it does not explicitly state when to prefer this over 'candidate.apply_to_job' for direct applications.

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

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

No annotations provided, but the description fully covers behavioral traits: idempotency, required preconditions (completed interview, published job), and specific error states. This is comprehensive disclosure for a mutation tool.

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 well-structured sentences with no wasted words. The first sentence clearly states purpose, followed by behavior and error conditions. 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?

Given the tool's complexity (preconditions, idempotency, error handling), the description covers all essential aspects. It also notes idempotency and the reuse of interview evidence, which is critical context. Output schema exists but not needed in description.

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 50% (only apiKey described). Description adds context for jobId (must be published) but does not detail format or constraints. With moderate coverage, description partially compensates but leaves gaps for apiKey.

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 'Apply the candidate to a PUBLISHED job' and specifies the unique context of reusing an evaluated profile interview, distinguishing it from sibling tools like withdraw_application or accept_invitation.

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 describes when to use (published job, completed+ evaluated interview) and what happens otherwise (GATE_LOCKED, GATE_EVALUATING, GATE_FAILED, NOT_FOUND). Lacks an explicit 'when not to use' but context is sufficient.

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

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

With no annotations, the description fully discloses behavioral traits: it is terminal, blocks re-invites, is idempotent, and explains return values (NOT_INVITED, NOT_FOUND). No contradictions.

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 extremely concise with three short sentences. It front-loads the purpose and then adds essential usage notes. Every sentence earns its place with no redundancy.

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 tool's simplicity, the description covers state transition, terminality, idempotency, and error states. The output schema exists, so return value details are not needed. However, a note on apiKey authentication would improve completeness.

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 does not provide any additional meaning for the parameters beyond what is in the input schema. The schema has 50% coverage (only jobId documented), and the description fails to explain jobId or apiKey. The tool would benefit from a brief description of jobId.

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: 'Decline an employer's invitation to a job (INVITED -> DECLINED).' It uses a specific verb and resource, and the state transition distinguishes it from sibling tools like accept_invitation.

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 includes critical usage guidance: 'TERMINAL — a declined invite blocks any re-invite from the employer, so only decline when the candidate is sure.' It also mentions idempotency. While it does not explicitly compare to alternatives, the context is sufficient for a confident decision.

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

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

No annotations provided, so description carries full burden. It mentions ordering (newest first), restricted scope (caller's only), and fields returned. Could add more about error handling or rate limits, but sufficient.

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 front-loading the action and result, no redundant information. Every sentence earns its place.

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 presence of an output schema (not shown but indicated), the description covers return data, ordering, scope, and constraints. No missing context for an agent to use the tool 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?

Only one parameter (apiKey) with schema description coverage 100%. Description does not add additional semantic meaning beyond the schema's description for apiKey. Baseline 3 is appropriate.

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?

Description clearly states it lists the candidate's own job applications with specific fields (status, dates, interview score, job summary). It distinguishes from sibling tools like employer.list_applicants which lists for employers.

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 'Returns only the caller’s applications — no jobId input, so it is not an enumeration surface,' telling the agent when to use and when not to use this tool.

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

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

No annotations provided. Description only states a fetch operation without disclosing behavioral details such as authentication requirements, error handling (e.g., if job not found), rate limits, or side effects. The lack of annotations places the burden on the description, which does not compensate.

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?

Single sentence is very concise but at the expense of necessary information. It is not verbose but could be improved with a brief note about what the fetched job includes or any constraints.

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 tool that returns a job object (output schema exists but not shown), the description does not hint at the response structure or any relevant fields. Given low complexity, it is still incomplete for an agent to fully understand the tool's role.

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 50%: jobId lacks description in schema, apiKey has a description. The tool description adds no additional clarification for parameters. For example, it doesn't specify expected format of jobId or how to obtain it. Agent must infer from context.

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?

Description clearly states the action (fetch) and resource (single published job by id). It distinguishes from siblings like candidate.search_jobs which lists multiple jobs. However, it could explicitly note that it is for candidates, though the tool name implies it.

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?

No guidance on when to use this tool vs. alternatives (e.g., search_jobs for listing, employer.get_job for employer context). Does not mention prerequisites or conditions for use.

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

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 only PUBLISHED jobs are returned and that they are ordered newest first, which is important behavioral context. However, it could elaborate on authentication requirements or error handling.

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 two sentences, front-loaded with the action and resource. Every sentence serves a purpose with no fluff, making it highly concise and well-structured.

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 tool's simplicity (list operation with one optional parameter and an output schema), the description is mostly complete. It covers what is returned and ordering, but could mention pagination or limits if applicable. The presence of an output schema reduces the burden on description.

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 input schema has 100% description coverage for the single parameter apiKey. The tool description does not add additional meaning beyond what the schema provides, so baseline score of 3 is appropriate.

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 verb 'List' and the resource 'candidate's saved (bookmarked) jobs', with ordering 'newest first'. It also distinguishes from sibling tools by specifying that only currently PUBLISHED jobs are returned, which adds specificity.

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 implies when to use (to list saved jobs) but does not explicitly mention when not to use or provide alternatives like candidate.search_jobs or candidate.set_saved_job. The constraint about PUBLISHED jobs offers some guidance but lacks explicit exclusion.

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

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

With no annotations, the description fully carries the burden. It discloses the dual-mode behavior (ranking vs browse by recency), the optional tier narrowing, and the output fields (matchExplanation, fit score). It does not mention side effects or rate limits, but the behavioral scope is well 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?

The description is a single paragraph of five sentences, each adding essential information. It is front-loaded with the main purpose and concise, with no unnecessary words or repetition.

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 complexity (two modes, 8 parameters, and an output schema), the description covers all major scenarios: semantic ranking, browse fallback, tier cascade, and output details. It mentions reading tierCounts (presumably in output) and explains the absence of fit scores in browse mode. It does not detail pagination but that is standard.

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 description coverage is low (25%), but the description adds significant meaning for the key parameters: it explains the `tier` usage in detail and clarifies the effect of `q` on the mode. Other parameters (limit, offset, jobType, etc.) are standard and self-explanatory from enums or schema 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 clearly states the tool's purpose: semantically rank jobs against the authenticated candidate profile using embedding-based fit. It distinguishes itself from sibling tools by specifying the ranking mechanism and the browse fallback mode.

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 guidance on when to use each mode (ranked vs browse) and how to cascade tier parameters. It does not explicitly compare to other candidate tools, but the tool is the only search tool among siblings, and the guidance is clear for its own usage.

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

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

With no annotations, the description carries full transparency burden. It discloses idempotency, desired-state semantics, and error condition for missing/non-public jobs. It does not mention authentication or rate limits, but the simple state-setting behavior and output schema reduce the need for extensive disclosure.

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, well-structured sentence that is front-loaded with the core action. Every part is necessary: it states the target (published job), the operation (set saved state), key behavioral traits (idempotent desired-state), and an error condition. No 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 that an output schema exists, the description does not need to explain return values. It adequately covers the main behavior, parameter effects, and error case (NOT_FOUND). The tool is simple and the description, combined with the schema, provides full context for an agent.

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 67% of parameters with descriptions (saved and apiKey). The description adds value by explaining the saved parameter's idempotent, non-toggle behavior, which goes beyond the schema. For jobId, it is implied as the job identifier. This compensates for the missing schema description of jobId.

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 title 'Save / unsave job' and description clearly state the tool sets a job's saved status. It distinguishes itself as an idempotent desired-state operation rather than a toggle, providing specific verb and resource context. Among sibling tools like candidate.get_saved_jobs, its write nature is evident.

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 explicitly indicates usage for published jobs and warns about NOT_FOUND errors. It clarifies idempotency, which guides retries. While it doesn't compare to alternatives, the sibling tools are distinct operations, making the use case sufficiently clear.

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

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

No annotations provided, so description carries full burden. It discloses idempotency, state transition, and possible return values (NOT_APPLIED, NOT_FOUND). This is transparent for a simple mutation tool.

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 that are clear and to the point. No unnecessary words. Front-loaded with the core action and state effect.

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?

Covers the main functionality, edge cases, and error returns. Lacks parameter details, but given the tool's simplicity and output schema, it is mostly complete. Could be improved by listing when to use specific error handling.

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 50%, but description adds no context for parameters. jobId and apiKey are not explained; the agent must infer their meaning. A brief note on how to identify the job would improve usability.

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?

Description uses specific verb 'withdraw' and resource 'active application' with state transition (APPLIED -> WITHDRAWN). It clearly distinguishes from sibling tools like accept_invitation or apply_to_job, which deal with different states.

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?

States when to use: to withdraw an active application. Explains idempotency and edge cases (NOT_APPLIED, NOT_FOUND). However, does not explicitly list when not to use or compare to alternatives.

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

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

Discloses the transition action and error conditions. No annotations, so description is the sole source; lacks information on permissions or side effects beyond errors.

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 concise sentences: one for purpose, one for error conditions. No redundant 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?

Output schema exists, so return value not needed. Covers key aspects: input precondition (CLOSED), outcome (ARCHIVED), error cases. Slight gap on ownership requirement, but error condition implies it.

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 50% (apiKey has description, jobId does not). The description adds no parameter details beyond the schema, failing to compensate for the coverage gap.

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?

States specific action: 'Transition a CLOSED job to ARCHIVED.' Clearly distinguishes from siblings like close_job or delete_job.

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?

Indicates it is for jobs already closed, and lists error conditions (NOT_FOUND, CONFLICT) that guide proper usage. However, it doesn't explicitly mention alternative tools.

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

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

No annotations provided, so the description carries full burden. It discloses that the invitation record is deleted (destructive) and that re-invitation is later possible. Does not mention potential side effects like notifications to the candidate or authorization requirements.

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, no wasted words. Essential information is front-loaded: action, object, consequences.

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?

Description is fairly complete given the presence of an output schema. It explains the effect and re-invite possibility. Lacks edge cases or prerequisites, but sufficient for a targeted mutation 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?

Schema has 100% coverage with descriptions for all parameters. The description does not add any extra semantic meaning beyond what the schema already provides, so baseline score is appropriate.

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?

Clearly states the verb 'Cancel', the resource 'pending invitation', and specifies the scope 'sent to a candidate'. It distinguishes itself from sibling tools like 'invite_candidate' (create) and 'list_invitations' (read) by describing the deletion effect and re-invite possibility.

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?

Implied usage: only for pending invitations. However, no explicit guidance on when not to use this tool (e.g., if invitation is already accepted) or comparison to alternatives like 'candidate.decline_invitation'.

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

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

The description discloses the state transition and two specific error scenarios. With no annotations, it carries the full burden, but it lacks details on side effects (e.g., impact on applicants) or permission requirements beyond ownership.

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 with no redundancy. States the main action and error cases efficiently.

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 simple state transition tool, the description covers core behavior and errors. With an output schema assumed, the lack of return value description is acceptable, but could mention output structure.

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 does not mention any parameters. Schema coverage is 50% (apiKey has description, jobId does not). The description adds no meaning beyond the schema, leaving jobId undocumented.

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: transition a PUBLISHED job to CLOSED. It distinguishes from sibling tools like 'archive_job' and 'delete_job' by specifying the state transition and error conditions.

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 clear context (when the job is PUBLISHED) and error returns (NOT_FOUND, CONFLICT) that guide usage. However, it does not explicitly state when not to use or suggest alternative tools.

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

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

The description discloses synchronous execution, typical latency (5-30s), creation of a DRAFT status, and a recovery strategy for client-side timeouts. No annotations are provided, so the description carries the full burden and meets it comprehensively.

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 with no fluff. The first sentence states the core action, the second provides workflow guidance. Information is front-loaded and every sentence adds value.

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 description covers key aspects: purpose, latency, draft status, recovery, and next steps. An output schema exists, so return values are implied. Minor gap: no explicit mention of error handling for Gemini parse failures, but overall complete.

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 descriptions already cover both parameters in detail (e.g., rawText's role, latency, recovery). The description adds workflow context but not new parameter-specific semantics, so a baseline score of 3 is appropriate.

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 it parses raw text via Gemini AI and creates a DRAFT job. It distinguishes from sibling tools like employer.update_job and employer.publish_job, making the purpose 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?

It explicitly mentions the workflow: use this tool to create a draft, then refine with employer.update_job and publish with employer.publish_job. No exclusions are stated, but no alternative creation tool exists.

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

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

With no annotations provided, the description fully bears the burden of behavioral disclosure. It clearly states the action is permanent deletion, requires a DRAFT job that was never published, and specifies error cases (NOT_FOUND, CONFLICT). This is comprehensive for a destructive tool.

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 extremely concise: two sentences. The first sentence front-loads the core action and condition, and the second adds crucial error context. No extraneous words.

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 simple delete tool with an output schema (not shown) and no annotations, the description covers all necessary behavioral aspects: the action, the prerequisite (DRAFT, never published), and error conditions. It is complete without needing to describe return values.

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 50% (apiKey has a description, jobId does not). The description does not add semantic meaning to jobId beyond what the schema shows (just a string). It indirectly mentions jobId in error scenarios but provides no format, constraints, or usage hints. For the apiKey param, the schema already describes it, so no added value from the description.

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 permanently deletes a DRAFT job that was never published. It uses specific verb (delete) and resource (job) with a conditional scope, correctly distinguishing it from siblings like employer.archive_job or employer.close_job.

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 explicitly states the tool is for DRAFT jobs that were never published, which defines when to use it. It also explains error responses (NOT_FOUND for missing/non-owner jobs, CONFLICT for non-DRAFT), guiding the agent on when not to use it. However, it does not explicitly suggest alternative tools for other states.

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

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

No annotations present, so description carries full burden. Discloses important behavior: contact fields are blanked unless status is SHORTLISTED or HIRED, and transcript is separate. Does not address auth or rate limits, but provides meaningful behavioral insight.

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, front-loaded with main output, no wasted words. Efficiently conveys key 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?

Output schema exists but not shown; description lists major components and a critical behavior (contact field blanking). Missing parameter guidance and any mention of permissions, but overall adequately covers the tool's output for its complexity.

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?

Input schema has 2 parameters (apiKey, applicationId) with 0% schema description coverage. Description adds no explanation of what these parameters represent or how to use them, leaving the agent uninformed about required inputs.

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 returns a 'full applicant bundle' listing specific components (resume, interview light slice, GitHub, LinkedIn), distinguishing it from sibling tool employer.get_applicant_transcript. Verb 'get' with resource 'applicant detail' is explicit.

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?

Provides context by noting transcript is delivered by a specific sibling tool and contact field behavior based on status. However, does not explicitly state when to use this versus other detail tools like employer.get_candidate or employer.get_candidate_evidence.

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

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

Discloses ownership-only gate and empty array edge case. With no annotations, this provides essential behavioral context. Could mention rate limits or other side effects, but for a simple read operation, it is sufficient.

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, front-loaded with main purpose, no fluff. Every sentence adds value.

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 existence of output schema, description covers key behavioral traits (access restriction, empty array). The tool is simple and the description is complete enough for an agent to use 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 coverage is 0%, but description implies applicationId is the identifier. Does not explicitly describe apiKey or provide format details. Adequate but minimal extra meaning.

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?

Clearly states it returns a verbatim interview transcript for one applicant, with access restriction (ownership-only gate) and an edge case (empty array). Distinguishes from siblings like get_applicant_detail.

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?

Tells when to use (get transcript for one applicant) and access condition (no SHORTLISTED/HIRED required). Does not explicitly mention alternatives or when not to use, but the context is clear.

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

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

No annotations provided, so description carries full burden. It details return shape (search-entry, interview slice, existingApplications) and explicitly states what is excluded and where to find it.

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, front-loaded with main purpose. Second sentence is dense but efficient. Could be slightly more concise but overall well-structured.

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?

Description is complete for a fetch tool with output schema. Explains returned fields, distinguishes from more detailed tools, and includes decision-relevant context (existingApplications for re-invite).

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 has 0% description coverage. Description only mentions 'user id' but does not explain the apiKey parameter or provide format/constraints for either parameter.

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?

Clearly states verb 'Fetch' and resource 'discoverable candidate by user id'. Explicitly distinguishes from sibling employer.get_applicant_detail by specifying that heavy artefacts are behind that tool.

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?

Provides explicit guidance on when to use: to check existing applications for re-invitation decisions, and what is not included (heavy artefacts) with reference to alternative tool.

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

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

No annotations are provided, so the description must fully convey behavior. It describes the returned evidence structure and error conditions (NOT_FOUND for missing/unauthorized), implying a read operation. However, it does not discuss what happens when no interview exists for a valid candidate or whether any side effects occur. Still, coverage is high.

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, each necessary. It fronts the core purpose, then elaborates on usage and failure cases. No redundancy, and the structure is logical.

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 presence of an output schema and moderate parameter count, the description covers the main workflow, returned content, and error scenarios. It lacks only a mention of what occurs if no interview evidence exists for an eligible candidate, which is a minor omission for an otherwise thorough definition.

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 67% (jobId and userId described in schema). The description adds value by clarifying jobId must be a published vacancy and userId must be a candidate from the same job's search results. Parameter 'apiKey' remains undescribed in both schema and description, which is a minor gap.

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 the tool fetches interview evidence for one candidate against one published job, listing specific components (facts, Q&A, summary, signals). It differentiates from siblings like 'search_candidates_for_job' by positioning itself as a post-search deep dive for ranking explanation.

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 instructs to use after 'search_candidates_for_job': shortlist first, then fetch evidence for chosen candidates. This provides a clear workflow and criterion for selection, effectively distinguishing from alternative actions.

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

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

With no annotations provided, the description must cover behavioral traits. It discloses that missing or employer-mismatched jobs return NOT_FOUND and explicitly states 'no existence leak', providing important security context beyond the input schema.

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 two sentences, front-loaded with the purpose, and contains no unnecessary words. Every part earns its place.

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 that an output schema exists (so return values are documented elsewhere), the description covers key aspects: what the tool does, error behavior, and security implications. It is complete for a single-fetch-by-ID 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?

Schema description coverage is 50% (apiKey has a description, jobId does not). The description adds 'by id' for jobId but no further detail. For the apiKey parameter, the schema already provides a description, so the description adds minimal value. Baseline of 3 is appropriate given partial coverage.

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 'Fetch a single employer job record by id', specifying both the verb and the resource. It distinguishes itself from sibling tools like 'candidate.get_job' (different actor) and 'employer.list_jobs' (list vs single).

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 implies usage for fetching a specific employer job but does not explicitly state when to use this tool over alternatives like 'employer.list_jobs' for listing or 'candidate.get_job' for candidate context. No explicit 'when not to use' or mentions of prerequisites.

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

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

The description fully discloses behavioral traits: it creates or updates a JobApplication, returns specific error sub-reasons, and explains the anti-enumeration behavior for JOB_NOT_FOUND. Since no annotations are provided, the description carries the full burden and does so comprehensively.

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 front-loaded with the main action and then covers edge cases. It is dense with useful information but is slightly long; however, every sentence adds value, so it earns a high score.

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 complexity (no annotations, 0% schema coverage) and the existence of an output schema, the description provides sufficient context for correct tool usage. It explains return values for error cases and preconditions, making it complete for an agent to decide when to call this 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 input schema has 3 parameters with 0% schema description coverage. The description implicitly clarifies jobId and candidateUserId but does not mention apiKey. While the context makes the parameters somewhat clear, the description fails to explicitly describe each parameter, relying on inference.

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: inviting a discoverable candidate to a published job, creating a JobApplication with status INVITED. It distinguishes itself from sibling tools like candidate.decline_invitation or employer.cancel_invitation by specifying the exact action and conditions.

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 guidance on when to use the tool, including checking existingApplications via employer.get_candidate beforehand. It explains when re-invite is allowed (after candidate withdrew) and when it's blocked (INVITED, APPLIED, DECLINED), and mentions anti-enumeration for error reasons.

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

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

Discloses conditional inclusion of contact fields based on status, which is useful. However, with no annotations, it should also mention error cases, pagination, ordering, or what happens with no applicants. Adequate but not thorough.

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, front-loaded with the core purpose, no wasted words.

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?

Output schema exists so return value description is optional, but the description lacks parameter details, usage guidelines, and any mention of pagination or error handling. Partially complete.

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 0%, yet the description fails to explain either parameter (jobId or apiKey). The description mentions 'one of the employer's jobs' but does not describe format or purpose of apiKey.

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 lists live (APPLIED) applicants for a specific job, and distinguishes from siblings like get_applicant_detail and search_candidates_for_job by specifying the returned fields and conditions.

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?

No explicit guidance on when to use this tool vs alternatives. The agent is left to infer from context, but the description does not mention when not to use it or direct to siblings.

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

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

The description clearly indicates this is a read-only list operation with no side effects. It explains the exact status of the listed items. Without annotations, the description adequately conveys the safe and non-destructive nature of the tool.

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, concise sentence that is front-loaded with the action and resource. No wasted words, and it provides essential clarification in the second part.

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 presence of an output schema, the description does not need to explain return values. The description is sufficient for a simple list operation, though it omits details like pagination or ordering, which are not critical for basic understanding.

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%, and the description does not add additional meaning beyond what the schema already provides for the parameters. The baseline score of 3 is appropriate.

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 verb 'list' and the resource 'pending candidates on one of the employer's jobs', and it explains the status (INVITED). It distinguishes the tool from siblings like list_applicants and invite_candidate by specifying the exact state of the candidates.

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 implies usage when wanting to see invited candidates who have not responded, but it does not explicitly state when to use this tool versus alternatives (e.g., list_applicants). No when-not or exclusion criteria are provided.

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

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

The description implies a read-only operation but does not disclose pagination behavior, authentication requirements, or other traits beyond the basic action.

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?

A single, straightforward sentence with no unnecessary information, though it could be expanded slightly for clarity.

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 tool has 4 parameters and no annotations, the description is too minimal to guide an agent on pagination, filtering, or expected output structure.

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 no meaning to the parameters (limit, offset, status, apiKey); schema coverage is only 25% and the description does not compensate.

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 lists jobs owned by the current employer account, distinguishing it from candidate-facing tools and the singular employer.get_job.

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?

No guidance is provided on when to use this tool versus alternatives like employer.get_job for a single job or candidate.search_jobs for candidate searches.

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

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

Despite no annotations, the description discloses two specific error conditions (NOT_FOUND for missing/non-owner jobs, CONFLICT for non-draft jobs), revealing ownership and state requirements. This adds useful behavioral 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 extremely concise—two short sentences front-loading the core action and error conditions. Every sentence is informative with no redundancy.

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 simple state-transition tool with an output schema, the description covers the action, key errors, and implications (ownership, draft state). It lacks usage comparisons to siblings but is otherwise adequate.

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 50% (only apiKey documented). The tool description does not explain the 'jobId' parameter beyond its name, failing to add semantic value. The description should clarify the role of jobId.

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 explicitly states the action ('Transition a DRAFT job to PUBLISHED'), providing a specific verb and resource. It clearly conveys the tool's function without ambiguity.

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?

No guidance is given on when to use this tool versus alternatives like 'employer.update_job' or 'employer.close_job'. The description does not mention prerequisites or scenarios for appropriate use.

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

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

Discloses semantic ranking and lack of per-vacancy fit score, but with no annotations, it misses pagination, authentication, and rate limit details.

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 concise sentences with no redundancy, front-loading key 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?

Adequate for purpose and differentiation, but lacks parameter details and output format; output schema exists but description doesn't leverage it.

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?

No parameter descriptions in schema (0% coverage) and description adds no detail about page, pageSize, or apiKey; only query is implied.

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 performs free-form semantic search across discoverable candidates without job context, distinguishing it from the sibling search_candidates_for_job.

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 (no job context) and when to use an alternative (search_candidates_for_job for scored ranking).

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

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

No annotations exist, so the description carries the full burden. It discloses ranking behavior (based on proven skills), white-box explanation, error states (NOT_FOUND, NOT_INDEXED, NO_CATEGORIES), pagination behavior (page.hasMore vs page.total), and tier behavior. It is comprehensive without contradictions.

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 long but well-structured: purpose first, then WORKFLOW steps, then error cases. It is front-loaded with the core purpose. Slightly verbose but every sentence adds value.

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 complexity (6 params, no annotations, output schema exists but not shown), the description covers all necessary aspects: workflow, pagination, tier cascade, error handling, and references related tool for deeper evidence. It enables correct invocation without ambiguity.

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 low (17%), but the description compensates by richly describing the 'tier' parameter's workflow and behavior. Other parameters (jobId, apiKey, pageSize) are not explicitly described but are implied in context. The description adds significant meaning beyond the schema.

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 'Semantically rank discoverable (interviewed) candidates against one of the employer's own jobs, with a per-candidate fit score AND a white-box explanation', which is a specific verb+resource+outputs. This clearly distinguishes it from the sibling 'employer.search_candidates_by_query' which does free-text search.

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 a detailed WORKFLOW: start with tier:'best', cascade to 'good'/'weak', paginate using page.hasMore, use matchExplanation, then call employer.get_candidate_evidence. It also explains when to omit tier and how to handle errors. This is explicit guidance.

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

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

With no annotations provided, the description carries full burden. It discloses side effects (unlocking contact info, conflict handling), which adds significant behavioral context. However, it does not mention permissions, idempotency, or what happens if the same status is set again.

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, no redundancy, all information is relevant and front-loaded. Efficiently conveys key facts.

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 3 parameters, 0% schema coverage, no annotations, and an output schema that exists but is not described, the description covers status behavior but leaves gaps in parameter documentation and output expectations. Adequate but incomplete.

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 0%, so description must compensate. It adds meaning to the reviewStatus enum by explaining consequences of specific values, but fails to describe apiKey or applicationId parameters. Thus partial compensation.

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 updates the employer review state on an application, listing all possible statuses. This distinguishes it from sibling tools that perform different actions, though it does not explicitly differentiate from similar status-update tools if any existed.

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 implied usage by stating the effect of specific statuses (SHORTLISTED/HIRED unlock contact info, WITHDRAWN surfaces as CONFLICT), but it does not explicitly state when to use this tool versus alternatives or provide any exclusion criteria.

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

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

No annotations provided, so the description must cover behavior. It reveals non-editable fields, auto-flip of dataSource, and non-owner return NOT_FOUND. However, it omits side effects, atomicity, and permission requirements beyond ownership.

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, front-loaded with purpose, no redundant information. Every sentence adds value.

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?

Covers purpose, partial update behavior, non-editable fields, and auth constraints. Output schema exists separately, so return values are not needed here. Could mention that additional unknown fields are rejected (implied by schema). Solid for a mutation 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?

Schema coverage is 33% (only apiKey described in schema). The description adds context about partial updates and non-editable internal fields, but does not explain all fields within the nested 'fields' object. The schema's enum constraints provide some self-documentation.

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 verb 'Update' and the resource 'existing employer job', distinguishing it from sibling tools like create_job, delete_job, and archive_job.

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?

It specifies that the tool accepts a partial whitelist and that rawInput and dataSource are not editable, but does not explicitly state when to use vs. alternatives; context is adequate for the existing sibling set.

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

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

No annotations are provided, so the description bears full responsibility for behavioral disclosure. It mentions 'explains role-specific onboarding' and 'MCP key location' but does not specify if this is a read-only operation, if it mutates state, or what side effects occur. The tool could display information or trigger an onboarding process, but the description is vague on these behavioral aspects.

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, front-loaded with usage context. Every sentence adds value with no redundancy. Efficient and well-structured.

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 description adequately covers purpose and when to use, but given the lack of annotations and 100% of behavioral burden on the description, it lacks detail on what happens when the tool is invoked (e.g., does it return information, trigger a workflow?). An output schema exists, so return values are covered, but behavioral completeness is still somewhat lacking.

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 0%, so the description must add meaning. It mentions 'role' implicitly by discussing candidate and employer onboarding, but does not explicitly state that the 'role' parameter selects which flow to present. The enum values are clear from the schema, but the description adds minimal additional context beyond the schema.

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 verb ('request access') and the resource (access to job-related functionality for candidates or employers). It specifies the exact scenario: when authenticated role tools are not usable yet. This distinguishes it from the many sibling tools that require authentication.

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 ('when authenticated role tools are not usable yet'), implying when not to use (after authentication). No explicit alternatives listed, but the context of sibling tools makes it clear these are the post-authentication alternatives.

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