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

Description adds 'Idempotent' but this is already declared in annotations via idempotentHint=true. No additional behavioral context like authentication requirements, side effects, or error conditions. With annotations present, the description adds minimal value.

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 fluff. Every word earns its place. Exceptionally concise and to the point.

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 tool with one parameter and no output schema, the description covers the essential purpose and idempotency. Could mention the return behavior (e.g., success/failure indicators) but not strictly necessary given the tool's simplicity.

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?

Single parameter with full schema coverage (description in schema). Description adds no extra meaning beyond what the schema provides. 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?

Clearly states the verb 'Mark' and resource 'job', and mentions idempotency. Could be more specific about the effect (e.g., creating an application) but overall clear. No differentiation from siblings like 'submit' or 'save'.

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. Does not explain prerequisites (e.g., must be authenticated) or when not to use (e.g., if already applied). The only behavioral note is idempotency, which is already annotated.

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?

Annotations already declare readOnlyHint=true; the description adds that the tool also returns open jobs beyond the company info. It does not mention pagination or data limits, but for a simple fetch this is acceptable.

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, front-loaded sentence that earns its place with no filler. Every word adds meaning.

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 retrieval tool with one parameter and no output schema, the description provides sufficient high-level information. It does not detail the output structure, but that is acceptable given the tool's simplicity.

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 parameter 'slug' is described in both schema and description. The description reiterates the role of slug ('by company slug'), adding no new semantic detail 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 ('Fetch'), the resource ('a company and its open jobs'), and the method ('by company slug'). It distinguishes from sibling tools like 'job' and 'search' by specifying the combined fetch.

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 company slug is available and one wants company details plus open jobs, but it does not explicitly compare with siblings or state when not to use it. Absence of usage guidance is a gap.

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 aligns with the readOnlyHint annotation, indicating a read-only operation. It adds behavioral context by specifying that the tool returns live values with counts, which is beyond the annotation. No contradiction.

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-loading the purpose and output, followed by usage guidance. 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?

Despite no output schema, the description sufficiently explains the return (facet values, counts, skills, ranges) and how to use the tool. For a parameter-rich tool, this context is complete enough for an agent to select and invoke it 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 100% with each parameter described adequately. The tool description does not add significant new meaning beyond the schema, but it contextualizes parameters as filter vocabulary. 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: listing filter vocabulary with live facet values, vacancy counts, skills list, and numeric ranges. It distinguishes itself from siblings like 'search' and 'market_fit' by positioning itself as the first call to discover real values.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly directs the agent to call this tool FIRST before 'search' and 'market_fit', and warns against inventing facet values. This provides clear usage guidance and context for 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?

Annotations already show readOnlyHint=true, so the agent knows this is a safe read. The description adds value by listing the fields returned (title, company, location, posting URL, description), providing behavioral specifics beyond annotations without contradiction.

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 sentence, 14 words, with the verb and key action front-loaded. Every word serves a purpose, and there is no redundant or filler 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?

With only one parameter and no output schema, the description adequately covers what the tool does and what it returns. It does not mention error handling or slug existence, but for a simple fetch-by-id tool, this is sufficient and not a significant gap.

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 already describes the slug parameter as 'The job's public slug (from search or facets results).' The description merely repeats 'by slug' without adding any new semantic detail, so 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 uses 'Fetch' as the verb, specifies the resource as 'a single job', and identifies the key identifier 'slug'. It also enumerates the returned content fields, distinguishing this from sibling tools like 'search' which return lists, and 'apply', 'save', etc. which perform other actions.

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 slug is available (e.g., from search or facets results) and provides clear context for retrieving full job details. However, it does not explicitly state when not to use this tool or name alternatives, leaving some room for inference.

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: URL as dedup key (idempotent update), description stored as HTML, and auth requirement. Annotations already indicate idempotentHint, but description adds how idempotency is achieved.

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 with front-loaded purpose. No redundancy, every sentence provides unique 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?

Lacks return value information despite no output schema. Otherwise covers purpose, behavior, and auth. Moderate complexity with 3 required params.

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?

With 75% schema coverage, description adds meaning for critical params: 'url' dedup key and 'description' HTML storage. Other params are sufficiently described in 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?

Description clearly states 'create a hand-curated job' with specific verb and resource. Distinguishes from sibling 'jobs_edit' and others via dedup key behavior and moderator 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?

Explicitly states 'Requires the moderator role (403 otherwise)' indicating when to use. No explicit alternatives mentioned, but the context of hand-curated and sibling list provides implicit 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?

Annotations show readOnlyHint=false and idempotentHint=true. The description adds critical context: partial update semantics and 403 error for non-moderators. This exceeds what annotations alone provide.

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, each adding unique value: purpose + constraint, then role requirement. No redundancy or fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 7 parameters and no output schema, the description is minimal. It explains partial updates and role requirement but omits side effects, success response, or distinction between manual and other jobs. Could be more 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 43%, so the description should compensate. It adds context for the slug parameter (not editable) and general partial update behavior, but does not elaborate on other parameters beyond schema descriptions. Adequate but not rich.

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 'Moderator: partially update a manual job by slug', specifying the action (update), resource (manual job), and identifier (slug), clearly distinguishing it from sibling tools like 'jobs_add'.

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 clarifies partial update behavior and role requirement ('Requires the moderator role'), but does not explicitly compare with alternatives (e.g., 'jobs_add' for creation). The implication is present but not explicit.

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 details the tool's behavior: computing headline coverage, identifying must-have and missing skills. This goes beyond the readOnlyHint annotation by explaining the analytical nature. It could mention data freshness or potential limitations, but overall it provides sufficient transparency.

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 informative sentences. It front-loads the main purpose and then adds critical usage nuance. No redundant or filler 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 the complexity (14 parameters, 1 required, no output schema), the description covers the tool's functionality well. It explains the conceptual output but could be more explicit about the exact return structure. Still adequate for a read-only analysis 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 description adds crucial semantics beyond the schema, such as clarifying that 'skills' is the measured set (not a filter) and that using a single skill probes demand. With 100% schema coverage, this extra context justifies a score above baseline 3.

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: 'Score a skill list against the live open-vacancy market for a filtered role' and lists specific output metrics (headline coverage, must-have skills, missing skills). It distinguishes itself from sibling tools by focusing on market fit analysis, not job search or CRUD operations.

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 that 'skills' is the measured set and that facet parameters define the role, providing clear guidance on how to use the tool. It also states that a single skill probes that skill's demand. However, it does not explicitly mention when not to use this tool or provide alternatives, slightly limiting completeness.

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?

Annotations already declare readOnlyHint=true, so the description adds limited behavioral context beyond that. It mentions that the tool returns stage and note, and that filter narrows results, but does not disclose pagination behavior (offset/limit) or authentication details. For a read-only operation, this is adequate but not extensive.

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 conveys the main purpose. It is appropriately front-loaded but could benefit from mentioning pagination or parameter details to improve completeness without sacrificing brevity.

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 list tool with readOnly annotations and no output schema, the description covers the key aspects: what is listed (caller's tracked jobs), what fields are included (stage, note), and how to filter. However, it lacks guidance on pagination (offset/limit) which is part of the input schema, slightly reducing 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?

Schema description coverage is only 33% (filter has a description), and the main description does not add meaning for limit or offset beyond what the schema provides. It mentions that filter narrows the set but does not elaborate, leaving two parameters undocumented in both schema and 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 lists the caller's tracked jobs (viewed/saved/applied) with stage and note, using a specific verb and resource. It is easily distinguished from sibling tools like 'my_submissions' which lists submissions.

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 tracked jobs but does not provide explicit guidance on when to use this tool versus alternatives like 'my_submissions' or 'search'. No exclusions or when-not-to-use information 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?

The description aligns with the 'readOnlyHint' annotation by stating 'List'. However, it adds no further behavioral details (e.g., pagination, sorting) beyond what the annotation already conveys.

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, efficient sentence with no extraneous words. It delivers maximum information in minimal space.

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 zero parameters, the readOnly annotation, and no output schema, the description sufficiently covers what the tool does and what it returns (moderation status). 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?

There are zero parameters, so the description has no parameter details to add. The description does not need to compensate for missing schema documentation. Baseline 4 applies.

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 ('List'), the resource ('the caller's own vacancy submissions'), and the specific information returned ('moderation status'). It distinguishes from siblings like 'submissions_pending' or 'submission_approve'.

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 the caller's own submissions, but it does not explicitly state when not to use it or mention alternative tools for different scopes (e.g., 'submissions_pending' for pending ones).

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?

Annotations already indicate idempotentHint=true and readOnlyHint=false, so the description does not need to reiterate safety. It adds value by explicitly stating the overwrite behavior, which is not in annotations. 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?

Single sentence, front-loaded with verb, no filler. Every word earns its place, making it efficient and easy to parse.

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 simplicity of the tool (2 parameters, no output schema), the description covers the core action and overwrite behavior well. Could mention note length limits, but overall sufficient for a small 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 100%, providing clear parameter descriptions for 'slug' and 'note'. The description reinforces these but does not add new constraints or format details beyond the schema, maintaining a baseline score.

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 attaches a free-text note to a tracked job, specifying the verb 'attach', the resource 'free-text note to a tracked job', and the distinguishing behavior 'overwrites the existing note'. This differentiates it from sibling tools like jobs_edit which modify broader job details.

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 adding or updating notes on tracked jobs, but provides no guidance on when to use this tool versus alternatives (e.g., jobs_edit) or when not to use it. It lacks explicit context on exclusions or 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?

The description mentions 'Idempotent', which is already declared via annotations. Other behavioral traits (e.g., side effects, auth needs) are not disclosed, but annotations cover the safety profile minimally.

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 short sentences with no wasted words. The key action and idempotency are front-loaded.

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 idempotent bookmark tool with one parameter and no output schema, the description is adequately complete. It could optionally mention reversal via 'unsave', but not essential.

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 describes the slug parameter well. The description adds no extra meaning about the parameter, so baseline 3 applies.

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 'Bookmark a job for later' uses a specific verb (bookmark) and resource (job), clearly distinguishing it from sibling tools like 'apply' or 'unsave'.

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 versus alternatives (e.g., 'apply' or 'unsave') is provided. The description only states the action without contextual 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?

The description adds context beyond the readOnlyHint annotation by specifying that it returns open jobs, the fields returned (title, company, location, public_slug), and the total match count. It does not contradict annotations and provides useful behavioral 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?

The description is two sentences, front-loaded with the main purpose, and contains 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?

Given the complexity (17 parameters, no output schema), the description covers the core functionality, return value, and integration with siblings. It does not explicitly mention pagination (limit/offset) but the schema covers that. Overall, it is fairly 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 description coverage is 100%, so baseline is 3. The description adds value by explaining how to use the returned slug and directing users to the `facets` tool for the `facets` parameter. This enhances understanding of 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 clearly states the verb 'Search', the resource 'open jobs', and what is returned (matching jobs with specific fields and total count). It also differentiates from sibling tools by explaining how the returned slug is used with other tools like `job`, `apply`, `save`.

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 context on when to use the tool (searching open jobs) and hints at using the returned slug with other tools. It also directs users to the `facets` tool for discovering valid facet values. However, it does not explicitly state when not to use this tool 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?

Annotations already indicate readOnlyHint=false (modifies) and idempotentHint=true (safe retry). The description adds the list of valid stages and mentions server validation, providing useful behavioral context beyond annotations. No contradiction.

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 sentence, 17 words, with no redundant information. Every word 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?

The description is adequate for a simple tool with two parameters and annotations, but lacks information about return values or prerequisites (e.g., application must exist). Could be more complete to guide the agent fully.

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%, but the description adds a list of valid stages not present in the schema (which has no enums). This adds significant value by enumerating allowed values.

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 'Set' and resource 'job's application stage', and lists all valid stages, making it clear what the tool does and distinguishing it from siblings like 'apply' or 'submit'.

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 updating an existing application's stage by listing valid values, but does not explicitly state when to use this tool versus siblings like 'apply' (new application) or 'submission_approve' (approve submission).

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?

Adds role requirement and error code beyond annotations (readOnlyHint=false). Describes write action and outcome.

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 with essential info. No filler. Front-loaded with role and 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?

Adequate for simple action. Lacks output info or side effects, but role requirement and outcome are clear.

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 covers 100% of parameter description. Description adds context by linking id to approval action, though no extra detail on format.

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?

Clear verb 'approve' and specific resource 'pending submission' with outcome 'minting a live job'. Distinguishes from siblings like submission_reject.

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 required moderator role and 403 error otherwise. Implicitly indicates when to use based on pending status and role.

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 indicates a mutation action ('reject') consistent with annotations (readOnlyHint=false), but does not disclose side effects (e.g., status change, notifications) beyond the role requirement.

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, front-loaded sentence that efficiently conveys purpose and usage without unnecessary 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?

With only two parameters and no output schema, the description covers purpose and role requirement adequately, but lacks details on return value or explicit state change.

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 merely restates the schema's parameter details (id, optional reason) without adding new semantic information.

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 'reject' and the resource 'pending submission', distinguishing it from sibling tools like 'submission_approve'.

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 the required moderator role and the error response (403) for unauthorized use, but does not explicitly mention when not to use or alternatives like 'submission_approve'.

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 adds critical behavioral context beyond the 'readOnlyHint' annotation by specifying the authentication requirement ('Requires the moderator role (403 otherwise)'). This informs the agent about authorization constraints and error behavior.

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 conveys both the purpose and the prerequisite role requirement. No extraneous information is present.

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 (0 parameters, readOnlyHint annotation, no output schema), the description adequately covers purpose and auth. However, it could be enhanced by hinting at the format or content of the returned list, but this is not critical.

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?

With 0 parameters and 100% schema description coverage, the description does not need to add parameter details. Based on the scoring rule, a baseline of 4 is appropriate since the schema already fully covers the 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 clearly states 'list the pending submission review queue' using a specific verb ('list') and resource ('pending submission review queue'). This purpose is distinct from sibling tools like 'submission_approve' and 'submission_reject', which perform actions, and 'my_submissions', which likely lists user's own submissions.

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 requirement for the moderator role and notes that 403 is returned otherwise, providing clear guidance on who should use this tool. However, it does not explicitly mention when not to use it or contrast it with alternatives like 'my_submissions' for non-moderators.

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 adds context beyond annotations by stating the server stores the submission as pending and returns it. Annotations already indicate write operation (readOnlyHint=false), so the description provides marginal additional 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 the core action, no filler. Every sentence is essential.

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 8 parameters and no output schema, the description lacks details on return values, error handling, or formatting requirements, making it incomplete for a submission 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 high (75%), so the description adds only minor value by noting 'dedup key' for URL. It does not significantly enhance understanding of parameters 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 tool submits a vacancy for moderation, with a specific verb and resource. However, it does not explicitly differentiate from sibling tools like 'jobs_add' or 'jobs_edit', so it's slightly below a 5.

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 mentions required fields but provides no guidance on when to use this tool over alternatives, nor any when-not-to-use scenarios.

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?

Annotations indicate idempotentHint=true; description reinforces this by stating it's a no-op if not saved. Adds value beyond 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?

Single sentence, front-loaded with action verb, no wasted words. Efficiently conveys purpose and behavior.

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 tool with one parameter and no output schema, the description covers purpose and idempotency. Lacks details on error handling (e.g., invalid slug), but overall 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 coverage is 100%, so baseline is 3. Description does not add any additional parameter information 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?

Description clearly states the verb 'remove' and the resource 'job's bookmark', and distinguishes from the sibling tool 'save'. The no-op note adds clarity for edge case.

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?

Context is clear: use to unsave a job. The no-op note implicitly advises it's safe to call even if not saved. However, it lacks explicit when-not-to-use or alternatives beyond the sibling context.

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?

Annotations already declare readOnlyHint=true, so the description's role is to add context. It adds value by specifying it returns user info and verifies the API key, with 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 sentences, front-loaded with purpose, no wasted words. 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?

For a simple tool with no parameters and no output schema, the description is complete: it states functionality and usage context.

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 0 parameters, so baseline is 4. No parameter information needed in 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 'return' and resource 'authenticated freehire user', and explicitly calls out it verifies the API key. It distinguishes itself from sibling tools by focusing on auth confirmation.

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 says 'Call this to confirm auth before other tools', providing clear usage context. While it doesn't mention when not to use it, the simplicity of the tool makes this sufficient.

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