workorai

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

Discloses idempotency and specific error conditions (NOT_INVITED, NOT_FOUND). No annotations, so description carries burden well. Could mention authentication needs more explicitly.

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, efficient, no wasted words. Front-loaded with action and state transition.

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?

Comprehensive for a simple tool: explains state transition, idempotency, and edge cases. Output schema exists, so return values are covered.

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?

Description does not add meaning to parameters beyond schema. jobId has no schema description and is not mentioned; apiKey has schema description. No compensation for missing 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?

Clearly states the tool accepts an employer's invitation, transitioning status from INVITED to APPLIED. Differentiates from sibling decline_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?

Implies use for accepting invitations, with return states (NOT_INVITED, NOT_FOUND) providing context on when it's not applicable. Lacks explicit when-to-use vs 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?

With no annotations provided, the description carries the full burden. It discloses idempotency, the requirement of an evaluated interview, and various error conditions (gate statuses, NOT_FOUND). This goes beyond just stating the action and provides useful 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?

The description consists of three concise sentences that cover purpose, preconditions, idempotency, and error behaviors. Every sentence earns its place; there is no redundant or vague phrasing.

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 noted), the description appropriately avoids explaining return values. It covers preconditions, idempotency, and all relevant error cases, making it fully adequate for an agent to determine when and how to use the tool. The tool's complexity is low, and the description leaves no gaps.

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 has only 2 parameters with 50% description coverage (only apiKey has a description). The description adds meaning to 'jobId' by specifying it must correspond to a published job. It also implies the context of reusing an evaluated interview, which relates to the apiKey for authentication. This adds value beyond what the schema alone conveys.

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, reusing their evaluated profile interview as evidence.' This is a specific verb+resource combination that uniquely identifies the tool among siblings like 'candidate.withdraw_application' or 'employer.invite_candidate'.

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 lists preconditions (published job, completed and evaluated interview) and the resulting error codes (GATE_LOCKED, GATE_EVALUATING, GATE_FAILED). It also notes idempotency and the reuse of existing applications. While it doesn't explicitly say when not to use it or compare with alternatives, the context is clear enough for the agent to understand when it is appropriate.

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 the terminal nature, idempotency, and error scenarios. The behavioral traits are clearly communicated.

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 that front-load the action and state transition. Every sentence adds essential information with 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?

Given the presence of an output schema, the description covers all necessary aspects: purpose, state change, terminal consequence, idempotency, and error returns. It is complete for an agent to decide when and how to invoke.

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 50% of parameters (apiKey has description, jobId does not). The description does not explicitly describe jobId but adds semantic context about state change and terminal behavior that helps agents understand parameter usage.

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 ('Decline') and clearly indicates the state transition (INVITED -> DECLINED). It distinguishes from siblings like 'accept_invitation' by focusing on the decline action.

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 warns that declining is terminal and blocks re-invites, advising to only decline when sure. Also notes idempotency and describes typical error returns, guiding 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?

No annotations provided, so description carries full burden. It discloses that the tool is read-only, returns only caller's applications, orders by newest first, and includes status, dates, interview score, and job summary. Minor omission: no explicit mention of no side effects, but it's implied.

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 wasted words; the first sentence front-loads purpose and key details; the second adds an important constraint.

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 and the presence of an output schema (not shown but provided), the description covers all necessary aspects: purpose, output contents, ordering, and caller restriction.

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% with only one optional apiKey parameter. The description adds no additional meaning about the parameter beyond the schema, 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 states a specific verb ('List') and resource ('candidate's own job applications'), includes ordering ('newest first'), and explicitly differentiates from sibling tools by noting it is not an enumeration surface and returns only the caller's applications.

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 clearly states when to use (to list the candidate's own applications) and when not (no jobId input, not an enumeration surface), implicitly contrasting with employer.list_applicants.

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 disclose behavioral traits. It only states 'fetch a single published job by id,' omitting details like error handling (e.g., invalid ID, non-published job), authentication requirements, or rate limits.

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 (one sentence, 6 words) and front-loaded. For a simple fetch operation, this is acceptable, though it lacks structural elements like bullet points or sections.

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 (fetch by ID) and the presence of an output schema (explaining return values), the description is minimally adequate. However, it fails to cover behavioral aspects like error states or access permissions, which are not addressed elsewhere.

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 parameter details beyond the method 'by id.' The input schema has 50% coverage (apiKey described, jobId not), and the description does not clarify the format or constraints of jobId or the 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 action ('Fetch'), the resource ('a single published job'), and the method ('by id'). It distinguishes from sibling tools like 'candidate.search_jobs' (multiple jobs) and 'employer.get_job' (different role).

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 a specific job ID is known, but lacks explicit guidance on when to prefer this over alternatives, prerequisites (e.g., authentication), or when not to use it.

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?

Reveals key behavior (only published jobs returned). However, without annotations, does not disclose read-only nature, auth requirements, or pagination.

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 purpose, no wasted words. Efficient and clear.

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 core behavior well. With low complexity and output schema present, additional details like return structure are not necessary.

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% with a clear description for the only parameter 'apiKey'. The tool description adds no additional parameter meaning, meeting baseline.

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 'List', resource 'saved jobs', and specifics like 'newest first' and filtering to only PUBLISHED jobs. Distinguishes from sibling tools like 'candidate.get_applications'.

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?

Implies usage for viewing bookmarked jobs but does not explicitly mention when to use or avoid this tool compared to alternatives like 'candidate.search_jobs'.

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 the full burden and excels: it discloses the semantic ranking mechanism, the optional tier behavior, the fallback browse mode with null matchScore, and the content of matchExplanation. This gives the agent a clear model of what to expect.

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 dense but every sentence adds unique value: main purpose, tier usage, fallback behavior, and row composition. It is front-loaded and avoids filler, making it appropriately sized for the tool's complexity.

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 an output schema exists and the tool has 8 parameters, the description covers the two most crucial behavioral nuances: the ranked vs. browse distinction and the matchExplanation payload. It fully equips an agent for correct invocation without needing to infer hidden behavior.

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 only 25%, so the description must compensate. It does for q and tier in detail, but leaves limit, offset, jobType, seniority, and workModel undocumented—though their names and enums make them somewhat self-explanatory, the dual-mode interaction with these filters is not addressed.

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 a specific verb ('rank') and resource ('published jobs against authenticated candidate profile') with a distinctive method ('embedding-based fit'). It clearly distinguishes from siblings like employer.search_candidates_by_query and candidate.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?

Explicitly instructs to start with tier:'best' and read tierCounts, and to omit tier for full ranking. It also explains when the tool degrades to a recency-based browse (free-text q or no completed interview) and warns not to treat those rows as a 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, but description fully discloses behavior: idempotent, NOT a toggle, works only on PUBLISHED jobs, returns NOT_FOUND for missing/non-public. 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?

Two concise sentences, front-loaded with key point. Every sentence provides essential info 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?

Covers all critical aspects: purpose, usage conditions, parameter behavior, error scenarios. Output schema exists, so return values are assumed handled. Complete for a simple set 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?

Adds meaning beyond schema: explains 'saved' as desired state with idempotence, clarifies 'jobId' must be published, and contextualizes 'apiKey' for authentication. Schema covers 67% of parameters, description compensates well.

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 verb 'set', resource 'saved job status', and scope 'PUBLISHED jobs', distinguishing it from siblings like 'candidate.get_saved_jobs' and 'candidate.apply_to_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 idempotent desired-state, not a toggle; specifies conditions (only PUBLISHED jobs) and error response (NOT_FOUND for missing/non-public). Guides correct usage and warns against common misunderstandings.

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 adequately discloses the idempotent nature, state transition, and specific error conditions (NOT_APPLIED, NOT_FOUND). It does not mention side effects like notifications or authorization requirements, but covers the core behavioral traits.

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, using two sentences plus clear condition statements. Every sentence adds value 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 an output schema exists, the description covers the main action and edge cases well. It lacks explanation of the jobId parameter, but overall provides sufficient context for selecting and invoking 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?

The description adds no additional meaning to the parameters; the jobId parameter is not explained, and the apiKey already has a schema description. With 50% schema coverage, the description should compensate but does not.

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 (withdraw), the resource (active application), and the state transition (APPLIED -> WITHDRAWN). It distinguishes from siblings by specifying the action and error conditions that relate to other states (e.g., NOT_APPLIED for invitations).

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 by explaining idempotency and return cases, which implicitly guide when to use the tool (e.g., for active applications only). However, it does not explicitly name alternative tools for other scenarios (e.g., declining an 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?

With no annotations, description carries full burden. It discloses key error conditions (NOT_FOUND for missing/non-owner, CONFLICT if not CLOSED), but does not mention side effects, reversibility, authentication needs, or rate limits. Partial disclosure but insufficient 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?

Description is one concise sentence with a second sentence for error cases. It is front-loaded and efficient, though a more structured format could improve readability.

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), description need not detail return values. However, for a 2-parameter mutation tool, it lacks information on idempotency, reversibility, and the exact meaning of 'non-owner'. Moderately complete but could be enhanced.

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 has description). Description adds no parameter-level detail beyond what schema provides; jobId is not described, and error messages only indirectly reference it. No compensation for the 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?

Description clearly states the action ('Transition a CLOSED job to ARCHIVED'), specifies the resource (job), and distinguishes from other job lifecycle tools like close_job or delete_job by explicitly naming the target state and precondition.

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?

Description implies when to use (when a job is CLOSED and you want to archive it), but does not explicitely exclude alternatives or provide comparison with sibling tools like close_job or delete_job. The 'not in CLOSED' conflict error gives some guidance, but no direct when-not-to-use advice.

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 must fully disclose behavior. It states the record is deleted and re-invitation is possible, covering key side effects. However, it does not mention potential notifications or other consequences.

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 contains no superfluous 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?

The description adequately covers the tool's purpose and effect, especially given the presence of an output schema for return values. It lacks prerequisites or further context about the operation's scope.

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 each parameter having a basic description. The tool description adds no additional parameter meaning beyond what the schema already provides.

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 'Cancel' and the resource 'pending invitation'. It distinguishes from sibling 'employer.invite_candidate' by specifying cancellation of a pending invitation and allowing re-invitation later.

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 indicates usage for pending invitations but does not explicitly state when not to use it or suggest alternatives. It implies only pending invitations are valid but lacks explicit guidance on exclusions.

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 describe behavior. It discloses the state transition and error conditions, but lacks details on side effects (e.g., impact on applications, reversibility) or prerequisites like authentication.

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 main action, no wasted words. Efficient and clear.

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 evaluated), the description covers the core purpose and error states. It lacks mention of prerequisites or side effects but is mostly complete for a simple state transition 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%; the description adds no parameter-specific information beyond the schema. The jobId parameter's purpose is obvious, but the description does not clarify how to obtain it or any constraints (e.g., ownership verification).

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 specifies the verb (transition) and resource (job) with the exact state change, distinguishing it from siblings like archive_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?

The description explains error conditions: NOT_FOUND for missing/non-owner jobs, CONFLICT for non-PUBLISHED status. This implicitly tells the agent when to use it (only for owned, published jobs). However, it does not explicitly list alternatives or when not to use it.

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 key behaviors: synchronous operation, 5-30s latency, creates a DRAFT, uses Gemini AI, and offers a recovery workflow. Lacks details on authorization or failure modes beyond timeout, but overall strong for no annotations.

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: first defines purpose and behavior, second gives usage guidance. Front-loaded with key info, 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?

Covers purpose, behavior, recovery, and next steps. Existence of output schema reduces need for return value explanation. Minor gap: no mention of error handling for Gemini parsing failure, but acceptable.

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?

Adds meaningful context beyond the schema: rawText is free-form up to 10000 chars parsed by Gemini with recovery on timeout; apiKey is for optional in-session authentication. With 100% schema coverage, the baseline is 3, and this description adds value.

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 action: parse raw text via Gemini AI and create a DRAFT job under the current employer. Distinguishes from sibling tools by mentioning the DRAFT status and referencing employer.update_job and employer.publish_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?

Provides explicit guidance on when to use this tool (to create a draft) and when to use alternatives (update_job to refine, publish_job to make live). Also includes recovery instructions for client-side timeout.

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 burden. It discloses permanent deletion, DRAFT-only constraint, and error states, but omits details on apiKey usage and rate limits.

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?

One sentence with error clarification; no redundant words. Front-loaded with the core action.

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 an output schema, the description adequately covers purpose, constraints, and errors. Minor gap: no mention of successful return value, but not required due to output schema.

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 documented in schema). The description does not add semantics for jobId or apiKey beyond what schema provides, leaving half of parameters with no added 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?

The description clearly states the verb 'delete' and the resource 'DRAFT job that was never published', and distinguishes from siblings like archive_job and close_job by specifying the DRAFT-only constraint.

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 (DRAFT jobs) and error conditions (NOT_FOUND, CONFLICT), but does not explicitly mention alternatives for published jobs.

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 carries the full burden. It discloses that resume contact fields are blanked unless the application status is SHORTLISTED or HIRED, which is a key behavioral detail. However, it does not mention authentication requirements, rate limits, or side effects.

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 that front-load the main purpose and then add a specific condition and a pointer to a sibling tool. 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?

Given the presence of an output schema (assumed to cover return values) and the description's coverage of bundle components and a specific condition, it is moderately complete. However, the lack of documentation for the apiKey parameter and no guidance on error handling or response size make it less than fully comprehensive.

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 compensate. It only implicitly references 'applicationId' but does not describe the parameter itself or any format expectations. The 'apiKey' parameter is entirely undocumented in the description, leaving a significant gap for the AI agent.

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' and lists specific components (resume, interview light slice, GitHub, LinkedIn analysis). It distinguishes from the sibling tool employer.get_applicant_transcript by noting that the transcript is handled separately.

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 indicates that for verbatim transcripts, the sibling tool employer.get_applicant_transcript should be used, providing a clear alternative. It also notes conditions for contact field redaction, giving context on when full data is available. However, it does not explicitly address other potential alternatives like employer.get_candidate.

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 carries the full burden. It discloses a key behavioral trait: returns an empty array when the source interview never produced turns. This adds useful edge-case information but does not cover other aspects like rate limits or idempotency.

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 with no redundant or filler content. Every sentence adds meaningful information: what the tool does, permissions, and edge-case behavior. It is 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 simplicity (two parameters, one required) and the existence of an output schema (not shown but present), the description is complete. It covers the return value, permissions, and a specific edge case. The output schema handles return-value details per rubric rules.

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 0%, yet the description only implicitly mentions the applicationId parameter ('for one applicant') and provides no explanation for the apiKey parameter. The schema gives parameter names, but the description adds minimal semantic value beyond what the names imply.

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 retrieves a 'verbatim interview transcript for one applicant,' specifying the verb (get) and resource (transcript). It distinguishes from sibling tools like employer.get_applicant_detail, which returns broader applicant info, and employer.get_candidate_evidence for evidence data.

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 explains the 'ownership-only gate' permission requirement and notes that it behaves like the UI Download button with no SHORTLISTED/HIRED requirement. This provides context on when the tool is accessible but does not explicitly list alternatives or when to avoid using it.

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, so description carries full burden. Discloses return shape (search-entry shape, interview slice, existingApplications), what is not included (heavy artefacts), and purpose of data. Adequately transparent.

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?

Description is fairly concise given the information it conveys. Front-loaded with main action. Every sentence adds value, though slightly long.

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 here) and the description's rich behavioral context (return shape, what's excluded, how to get more), it is complete for the tool's 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?

Schema description coverage is 0%. Description only mentions userId implicitly and does not describe apiKey. While the description adds rich behavioral context, it adds minimal value for parameter semantics specifically.

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 'Fetch a discoverable candidate by user id', specifying verb (fetch), resource (candidate), and scope (by user id). It distinguishes from sibling tools like employer.get_applicant_detail by noting heavy artefacts are elsewhere.

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 context on when to use this vs. get_applicant_detail (for heavy artefacts). Mentions that existingApplications helps decide re-invitation feasibility, implying a use case. Clear but could more explicitly state 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?

With no annotations, the description carries full burden. It discloses NOT_FOUND conditions and the content of evidence. It could mention more about idempotency or rate limits, but sufficiently covers behavioral traits.

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 front-loads the main action. It is efficient but slightly verbose in listing evidence components; could be slightly more concise.

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 output schema exists, the description need not explain return values. It covers preconditions, workflow, error conditions, and the purpose thoroughly. Complete for 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?

Schema coverage is 67%, but description adds meaning by explaining jobId must be a published vacancy and userId must come from search results. It also describes the returned evidence components, compensating for the missing apiKey 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 it fetches interview evidence for one candidate against one job, and distinguishes it from siblings by referencing search_candidates_for_job and the white-box basis for ranking.

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 says when to use (after search_candidates_for_job) and describes the workflow. However, it does not explicitly state when not to use this tool, so it's slightly less comprehensive.

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 for behavioral transparency. It discloses critical behavior: returns NOT_FOUND for missing jobs and for jobs owned by another employer, preventing existence leaks. This goes beyond a simple fetch description. However, it doesn't cover authentication requirements or rate limits, which are less critical for a read operation.

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 unnecessary words. The first sentence states the core purpose, and the second adds important behavioral context about error handling. 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 that there is an output schema (mentioned but not provided), the description is likely sufficient for a simple fetch tool. It explains the return value behavior for errors. However, it could be more complete by noting that the output schema will contain the job details, but since output schema exists, it's not necessary. The tool is simple enough that this description is 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?

The schema has 50% parameter description coverage (apiKey has a description, jobId does not). The tool description mentions 'by id' but does not add any specific details about jobId's format, constraints, or how it relates to the employer context. It relies on the schema for the apiKey parameter. While acceptable, it doesn't fully compensate for the missing jobId 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 verb 'Fetch', the resource 'single employer job record', and the identifier 'by id'. It also distinguishes from sibling tools like employer.list_jobs by specifying it retrieves a single record, and addresses error handling with 'Returns NOT_FOUND for missing jobs and for jobs owned by another employer (no existence leak)', which adds clarity.

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 retrieving a specific job record, and the error handling notes help the agent understand when to expect NOT_FOUND. However, it does not explicitly mention when to use this versus employer.list_jobs or candidate.get_job, but the context of sibling tools makes it clear enough.

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 behaviors: creates/updates JobApplication, blocks on certain statuses, returns specific error sub-reasons, and anti-enumeration for missing jobs. This is comprehensive.

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 coherent paragraph that front-loads the main action and includes necessary details. It is concise without being overly lengthy.

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 of edge cases, no annotations, and 0% schema coverage, the description covers return values, prerequisites, and error conditions thoroughly. It provides sufficient context for an AI 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?

Schema coverage is 0%, and the description only implicitly references jobId and candidateUserId in context. It does not explain the apiKey parameter or provide detailed semantics beyond parameter names.

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 action: inviting a discoverable candidate to a published job and creating a JobApplication with INVITED status. It is specific and covers the main purpose, though it does not explicitly differentiate from sibling tools.

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 advises inspecting existingApplications before calling, and lists conditions that block the invite. It provides guidance on when to use the tool, including re-invite behavior, though it does not compare directly with sibling 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?

With no annotations, the description carries the full burden. It discloses that the candidate showcase and interview scores are always returned, and that contact fields are conditional on SHORTLISTED/HIRED status. However, it does not disclose pagination, rate limits, or potential errors, leaving some behavioral aspects unspecified.

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 primary action, and every clause adds behavioral context. No filler or 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?

The tool is simple (2 params, no enums, output schema present), and the description covers the key conditional return behavior. However, it omits any mention of pagination, result limits, or how jobId is specified, leaving minor gaps.

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 has 0% description coverage, but the description does not explain apiKey or the jobId format; it only references 'one of the employer's jobs'. This fails to compensate for missing parameter 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 specifies a clear action ('List') and target ('live (APPLIED) applicants on one of the employer's jobs'), distinguishing it from sibling tools like employer.get_applicant_detail (single applicant) and employer.list_invitations (invitations).

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 provides context by explicitly scoping to 'live (APPLIED)' applicants, but does not name alternative tools for other statuses or mention when to avoid this tool. The conditional field behavior implies the tool is appropriate for APPLIED applications, but no explicit exclusion is given.

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 clarifies that only pending invitations are returned. It adds context beyond the name by specifying 'INVITED' status. No mention of permissions or limitations, but the main behavior is clear.

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, clear sentence with no filler. Efficiently communicates purpose and scope.

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 output schema exists and the tool is simple, the description is adequate. It could mention expected return format or alternatives, but is sufficient for a list operation.

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%, so baseline is 3. The description does not add meaning beyond the schema; the jobId parameter is obvious, and apiKey is not explained. Satisfactory but not improved.

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 pending (INVITED) candidates for a specific job. It distinguishes from siblings like candidate.accept_invitation and employer.cancel_invitation by specifying it only retrieves pending invitations.

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 when-to-use or when-not-to-use guidance. However, the description implies it's for viewing pending invitations, and sibling names indicate alternatives for accepting, declining, or canceling.

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 carries the full burden. It states ownership context but does not disclose expected behaviors such as pagination defaults, ordering, or any side effects. As a listing tool, it is assumed read-only, but this is not explicitly stated.

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 gets straight to the point. It is front-loaded and contains no unnecessary words, though it could benefit from a slightly more structured format.

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 four parameters and no annotations, the description is too brief. It does not cover how parameters affect the listing or any behavioral details. While an output schema exists, the lack of parameter context reduces 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 adds no meaning to the input parameters. Despite 25% schema description coverage (only apiKey has a description), the description does not explain limit, offset, or status. The tool has four parameters with no param info in the description, which is insufficient.

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 'List' and resource 'jobs' with ownership context 'owned by the current employer account', which clearly distinguishes it from sibling tools like 'employer.get_job' that retrieves a single 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 implies usage for listing all jobs of the current employer but provides no explicit guidance on when to use this tool versus alternatives like 'candidate.search_jobs' or 'employer.list_applicants'. No exclusions or context for when not to use it.

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 core behavior (state transition) and specific error outcomes, but with no annotations, it omits details on side effects, permissions, or reversibility.

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, direct sentence plus essential error information—no extraneous content, perfectly concise.

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 output schema exists and the tool is simple, the description covers functionality and errors fairly well, but lacks parameter details.

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 elaborate on the 'jobId' parameter beyond implicit mention in error cases, and the schema already covers 'apiKey'. With only 50% schema description coverage, the description fails to add 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?

The description explicitly states the action ('Transition a DRAFT job to PUBLISHED') using a clear verb and resource, distinguishing it from sibling tools 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 includes error conditions (NOT_FOUND, CONFLICT) that clarify when the tool is applicable, but it does not explicitly state when to use it versus alternatives like 'employer.update_job'.

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 carries full burden. It discloses key behaviors: semantic search, embedding, ranking by similarity, and absence of job context. However, it omits details on pagination, apiKey usage, and result format, but output schema reduces some burden.

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 long, front-loaded with the main action, and every word adds value. No extraneous content.

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 4 parameters and no annotations, the description lacks depth on parameter behavior and authentication, but provides good high-level context about search type and differentiation. Output schema partially supplements return value info.

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 0%, and the description does not explain any of the 4 parameters (page, query, apiKey, pageSize). This is a critical gap; the description adds no meaning beyond the schema structure.

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 tool performs free-form semantic search across discoverable candidates with no job context, and clearly differentiates from the sibling tool employer.search_candidates_for_job by specifying it has no per-vacancy fit score.

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 when-to-use context (preliminary search) and directs to an alternative (employer.search_candidates_for_job) for scored ranking, offering clear usage 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, the description carries full burden. It discloses pagination semantics (page.hasMore vs page.total), error conditions with meanings (NOT_FOUND for missing/owned job, NOT_INDEXED/NO_CATEGORIES for unindexed jobs), and behavior nuances like sort:"newest" ignoring tier. This goes well beyond basic expectations.

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 front-loaded with purpose and structured into numbered workflow steps. Every sentence adds value (workflow, error handling, back-compat). It could be slightly more concise, but the density is justified by the tool's complexity.

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 (tiers, pagination, white-box explanations, error cases) and the presence of an output schema, the description is exceptionally complete. It covers not only the search behavior but also post-processing steps and error recovery, making it a self-contained guide for the 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?

Schema description coverage is only 17% (only tier has a schema description), so the description must compensate. It explains tier in depth, mentions page.hasMore, and references matchExplanation. However, pageSize and apiKey are not elaborated, though their roles are fairly standard. The description adds significant meaning for the key parameters.

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 verb+resource: 'Semantically rank discoverable (interviewed) candidates against one of the employer's own jobs, with a per-candidate fit score AND a white-box explanation.' This clearly distinguishes it from sibling tools like search_candidates_by_query and candidate.search_jobs by focusing on ranking against a specific 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?

Provides a multi-step workflow: start with tier:'best', cascade to 'good'/'weak' based on tierCounts and page.hasMore, use matchExplanation for explainability, and call employer.get_candidate_evidence for deeper review. It also clarifies when to omit tier for back-compat, making usage guidance explicit and actionable.

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 important side effects: SHORTLISTED and HIRED statuses unlock candidate contact info in subsequent calls, and WITHDRAWN applications surface as CONFLICT. This adds behavioral context beyond the input schema. However, it does not mention authorization requirements or potential destructive outcomes.

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 consists of two concise sentences that front-load the purpose and immediately deliver key behavioral details. Every sentence adds value with 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 the tool has an output schema and is a mutation with clear side effects, the description covers the core functionality and consequences. It lacks information on error cases or authentication, but for a simple update tool this is acceptable.

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 lists the enum values for reviewStatus, adding meaning beyond the schema. However, it provides no explanation for apiKey or applicationId parameters, and schema description coverage is 0%. For a tool with three parameters, this partial coverage is adequate but not exceptional.

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 updates the employer review state on an application and lists all five allowed statuses. It is specific about the verb and resource, and the side effects distinguish it from sibling tools like employer.get_applicant_detail or employer.update_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 provides no guidance on when to use this tool versus alternatives such as employer.update_job or employer.invite_candidate. It does not explain prerequisites or scenarios where this tool is appropriate.

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, description carries full burden. Discloses non-editable fields (rawInput, dataSource), auto-flipping of dataSource, and access control (non-owner returns NOT_FOUND). Adequate 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?

Two sentences, front-loaded with purpose. Every sentence adds value 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?

Output schema exists so return values need not be explained. Covers editable scope, immutable fields, and ownership behavior. Minor gap: no mention of required jobId (but schema indicates).

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 only 33% (only apiKey has description). Description adds context on partial update and which fields are immutable, but does not explain each parameter. Partially compensates.

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 'Update', resource 'existing employer job', and scope 'fields'. Distinguishes from siblings like create_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?

Provides context on partial whitelist, non-editable fields, and ownership behavior. Lacks explicit when-to-use vs alternatives but sufficient for typical 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?

No annotations provided, so description carries full burden. It explains that the tool provides role-specific onboarding, MCP key location, and next steps, which is good transparency for a request tool. Does not describe side effects, but likely none.

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 use case, no wasted words. Efficiently conveys purpose and context.

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 simple tool with one parameter and an output schema (not shown but mentioned), the description fully covers what the tool does and its return value (onboarding steps, key location, next steps). No gaps.

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 implicitly refers to the role parameter by mentioning candidate and employer, but does not explicitly describe the parameter or its values. However, the enum in schema is clear, and description adds context about role-specific behavior, so baseline with some added value.

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: for candidates wanting to find jobs or employers wanting to hire when authenticated tools are not usable. It differentiates from sibling tools by specifying it's for pre-authentication onboarding.

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... but the authenticated role tools are not usable yet'). Context implies it's for initial access, but does not explicitly list when not to use or alternatives, though siblings cover post-authentication actions.

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