Server Quality Checklist

Tool Scores

• reminder_deleteA
  4/5.0
  Behavior4/5

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

  Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation is known. The description adds the specific effect: 'reminderAt cleared' and 'Returns the updated tracked job', giving concrete behavioral context beyond the annotations. There is no contradiction with annotations.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is two compact sections plus a one-sentence summary. It front-loads the purpose, then details input and output in a structured list. Every sentence is necessary and no redundancy is present.

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

  Completeness4/5

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

  For a one-parameter destructive tool with a clear output schema and existing annotations, the description covers the essential input nuance (ID distinction) and the result (updated tracked job). Minor omissions such as idempotency or error behavior are acceptable given the richness of the output schema and annotations.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The single parameter's description in the schema is identical to the tool description's input section, so no extra meaning is added beyond the schema. With 100% schema description coverage, the baseline is 3 and no bonus is warranted.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The opening sentence 'Deletes a reminder from a tracked job' clearly identifies the action (delete) and resource (reminder from a tracked job). This distinguishes it from siblings such as reminder_set (which presumably creates/updates) and tracker_remove (which would remove the entire tracked job).

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

  Usage Guidelines3/5

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

  The description provides no explicit when-to-use guidance or alternatives. It does clarify which ID to use ('tracked_job_id... distinct from trackable.id and job.id'), but that is parameter-level, not usage guidance. The intended usage is only implied by the verb 'deletes' and sibling tool names.

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

• reminder_listA
  4/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds behavioral detail by specifying that results are ordered by reminder time and that only active reminders are included. This goes beyond the basic read-only annotation.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is extremely concise, with a single opening sentence stating the purpose, followed by clearly labeled Input and Output sections. Every word contributes to understanding the tool's behavior, 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.

  Completeness4/5

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

  For a simple tool with one optional parameter, the description covers the core behavior, ordering, and output. It does not mention edge cases such as empty results or what happens when no reminders exist, but given the schema and annotations, the description is sufficiently complete for an agent to select and invoke the tool correctly.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The input schema already documents the 'limit' parameter with default and max values. The description repeats the exact same wording in its Input section, adding no new semantic value. Since schema coverage is 100%, the baseline of 3 is appropriate.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description uses a specific verb 'Lists' and identifies the exact resource 'tracked jobs that have reminders set', with a clear ordering detail ('ordered by reminder time (soonest first)'). This clearly distinguishes it from sibling tools like tracker_list or reminder_set.

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

  Usage Guidelines3/5

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

  No explicit usage guidance or alternatives are mentioned. The intent is implied from the name and purpose, but there is no contrast with sibling tools such as tracker_list or job_alert_list. The description focuses only on what the tool does, not when to prefer it.

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

• tracker_removeA
  4/5.0
  Behavior3/5

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

  Annotations already declare destructiveHint=true, so the safety profile is known. The description adds that the output 'Confirms the job was removed from tracking', which is useful but not extensive. It does not mention side effects or reversibility beyond this.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness4/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is front-loaded with the main purpose and is appropriately concise. However, the Input section duplicates the schema's parameter description, which adds redundancy and slightly reduces efficiency.

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

  Completeness5/5

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

  For a simple tool with one required parameter, the description covers the purpose, the tricky ID distinction, and the expected output. Given the annotations and output schema, this is complete for an agent to invoke the tool correctly.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100%, and the description's Input section repeats the same parameter text verbatim. The description adds no new semantic meaning beyond what the schema already provides, so the baseline score of 3 applies.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states 'Removes a job from the user's job tracker', using a specific verb and resource. This distinguishes it from sibling tools like tracker_add, tracker_list, and tracker_update that perform different actions on the same resource.

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

  Usage Guidelines4/5

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

  The description provides clear usage context by specifying that tracked_job_id must be `trackedJobs[].id` from tracker_list output and distinct from other IDs. However, it does not explicitly state when to use this over alternatives or include exclusion criteria, so it falls short of a 5.

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

• job_alert_unsubscribeA
  4.1/5.0
  Behavior4/5

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

  Annotations already mark this as destructive (destructiveHint=true) and not read-only. The description adds valuable behavioral context beyond annotations: it states the operation is idempotent ('returns success even when the user was not subscribed or is already unsubscribed') and confirms the output ('Confirms the alert has been unsubscribed'). This gives the agent a clear safety profile beyond the binary hint.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is compact and well-structured: a one-sentence purpose, then clearly labeled Input and Output sections, followed by a one-line behavioral note. Every sentence earns its place with no filler or repetition.

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

  Completeness5/5

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

  For a single-parameter tool with annotations and an output schema, the description fully covers the input format, the output confirmation, and the idempotent behavior. No missing context is apparent for an agent to invoke this tool correctly.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The schema already describes the parameter with 100% coverage, and the description essentially repeats the same information (job search UUID or composite job ID from jobs_search/jobs_details). No new meaning is added beyond the schema, so with high schema coverage the baseline of 3 is appropriate.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description opens with a specific verb+resource: 'Unsubscribes the authenticated user from job alerts for a specific job search.' This clearly distinguishes the tool from siblings like job_alert_subscribe, job_alert_list, and job_alert_unsubscribe_all by targeting a single job search.

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

  Usage Guidelines3/5

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

  The description implies usage context ('for a specific job search') and the input requirements, but it does not explicitly state when to choose this tool over alternatives (e.g., 'use unsubscribe_all for all alerts') or mention any exclusions. The sibling tool names provide some context, but the description itself lacks direct usage guidance.

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

• job_alert_listA
  4.3/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds value by detailing the output includes pagination info, a summary of the underlying job search, and a system_instruction for presenting results, which goes beyond simple read-only semantics.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is well-structured with clear Input/Output sections, each sentence providing essential information without redundancy. It is appropriately sized and leaves no unnecessary words.

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

  Completeness5/5

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

  Given the simple parameter set (3 optional params, no nested objects), the presence of an output schema, and annotations, the description sufficiently covers the tool's behavior. It even mentions the system_instruction and summary info, making it complete for an agent to use effectively.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 100%, and the description's Input section merely restates the parameter names, defaults, and ranges already present in the schema. The description adds no extra semantic value beyond what the schema provides, so the baseline of 3 applies.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool lists the authenticated user's job alerts across all subscription sources, using a specific verb (Lists) and resource (job alerts). It distinguishes itself from sibling tools like job_alert_unsubscribe by focusing on read-only listing.

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

  Usage Guidelines4/5

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

  The description implies usage context by specifying it returns alerts for the authenticated user and covers all subscription sources, but it does not explicitly mention when to choose this over alternatives like job_alert_unsubscribe. There are no exclusions, but no explicit alternative guidance is provided.

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

• job_alert_subscribeA
  4.3/5.0
  Behavior5/5

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

  The description expands on the idempotentHint annotation by explaining that an existing subscription is updated without duplication. It also states the output shape (id, status, frequency) and notes the auth requirement. No contradiction with annotations.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is compact and well-structured with Input/Output sections. Each sentence contributes value, and it is 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.

  Completeness5/5

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

  With an output schema present and annotations covering safety and idempotency, the description provides output details and behavioral context. It is sufficiently complete for a simple two-parameter tool.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The input schema already covers 100% of parameters with equivalent descriptions, including accepted formats and default for frequency. The description repeats these details without adding significant new semantics beyond the schema.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description opens with 'Subscribes the authenticated user to job alerts for a specific saved job search,' using a specific verb and resource. This clearly distinguishes the tool from siblings like job_alert_unsubscribe and job_alert_list.

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

  Usage Guidelines3/5

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

  It provides context such as being for an authenticated user, targeting a saved job search, and being idempotent. However, it does not explicitly compare with sibling tools or state when not to use it, making usage guidance implied rather than explicit.

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

• jobs_detailsA
  4.3/5.0
  Behavior4/5

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

  Annotations provide limited safety signals (readOnlyHint=false), but the description clarifies the operation is a fetch and adds behavioral context: output contains personalized fields tied to authenticated user entitlements. It does not overpromise or contradict the annotations.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is well-structured with clear Input/Output sections, uses bold labels effectively, and packs all necessary information into a compact block. No filler or redundant content.

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

  Completeness5/5

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

  With a single parameter, an output schema, and clear relationship to jobs_search, the description fully covers the tool's purpose, input provenance, and output scope. It does not need to explain return fields since an output schema is present.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 100% and already describes job_id as the unique identifier from jobs_search. The description reinforces that it must be the exact `id` string from a search result, which adds marginal precision but no new semantics beyond the schema.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  Description uses a specific verb ('Fetches'), names the resource ('full details for one job'), and ties it to the ID from jobs_search. It clearly distinguishes itself from sibling search tools as the 'deeper view behind a search result'.

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

  Usage Guidelines4/5

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

  It explicitly states when to use it: with a job ID returned from jobs_search. It implies the complementary relationship to jobs_search but does not explicitly name alternative tools 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.

• jobs_searchA
  4.3/5.0
  Behavior4/5

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

  With no meaningful annotation hints (readOnlyHint false does not indicate side effects), the description carries the burden and does well: it reveals that only passed parameters are enforced, that Pro accounts receive a screened list while others get the full list, and that responses include a system_instruction. This goes beyond the schema and annotations, though it omits potential error scenarios 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.

  Conciseness3/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is well-structured but verbose, with multiple paragraphs covering job details, account tiers, and response instructions that may extend beyond the search action itself. While each sentence adds some context, the length could be trimmed without losing core meaning, making it less concise that ideal.

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

  Completeness5/5

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

  Given the tool's complexity (10 parameters, output schema, heterogeneous behaviors), the description is remarkably complete: it covers pagination via `nextCursor`, authentication-based resume data, Pro vs. non-Pro filtering behavior, and the presence of `system_instruction` in responses. The existing output schema handles return structure, so no further detail is needed.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 100%, giving a baseline of 3. The description adds value by explaining the query parameter format ('full job title or role'), explicitly listing the advanced filters and how they map to parameters, and clarifying that omitted constraints are not applied. This enhances semantics beyond the schema descriptions.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description opens with a clear, specific statement: 'Searches a database for real-time job listings matching the user's criteria.' It distinguishes itself from sibling tools by explicitly mentioning jobs_details for fetching full job descriptions using the `id` from search results, and it implies a search-specific role relative to recommendation tools.

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

  Usage Guidelines4/5

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

  The description provides clear context on how to use the search (e.g., use full job titles, not bare keywords) and directs to jobs_details for full descriptions. However, it does not explicitly state when not to use this tool or mention alternatives such as jobs_recommendations, though the query guidance and mention of jobs_details offer partial differentiation.

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

• tracker_updateA
  4.3/5.0
  Behavior3/5

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

  Annotations already indicate destructiveHint=true, and the description adds that the operation returns the updated tracked job and that reminder_at must be in the future. However, it does not disclose whether updates are partial or full overwrites, nor does it explain any irreversibility or side effects beyond the annotation.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is well-structured with a clear lead sentence, a compact input list, and an output note. Every sentence serves a purpose, and the formatting enhances readability for an agent.

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

  Completeness5/5

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

  The tool has 7 parameters with complete schema documentation and an output schema. The description fills the remaining gaps by specifying the correct ID to use, flagging potential ID confusion, and providing formatting examples, making it fully actionable.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 100%, so the baseline is 3. The description adds genuine value by clarifying the tracked_job_id provenance (distinct from trackable.id and job.id), giving a concrete example for tags, and stressing the future-date requirement for reminder_at, which goes beyond the schema text.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description states a specific verb ('Updates details') with a clear resource ('tracked job') and enumerates the affected fields (notes, deadline, salary, tags). This clearly distinguishes it from sibling tools like tracker_update_status, which presumably handles status changes.

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

  Usage Guidelines4/5

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

  The description provides clear context on what this tool updates and emphasizes the correct ID source (trackedJobs[].id from tracker_list) while cautioning against confusing it with other IDs. It doesn't explicitly mention when not to use it or name alternatives like tracker_update_status, but the field scope strongly implies the intended use.

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

• tracker_update_statusA
  4.3/5.0
  Behavior4/5

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

  The annotations already indicate destructive behavior (destructiveHint=true), and the description adds context by explaining the return value and the distinction between tracked_job_id and other IDs. This helps the agent anticipate 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.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is structured with headers and bullet points, making it easy to scan. It contains no redundant phrasing; the sub-status enumeration is necessary because it depends on the chosen status.

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

  Completeness5/5

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

  Given the tool's simplicity (3 parameters with strong schema coverage, output schema exists), the description fully addresses input requirements, output, and a critical ID disambiguation. It leaves no critical gaps.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The input schema provides 100% coverage of parameter descriptions, including the same enum lists and ID guidance. The description restates the schema content without adding new semantic meaning beyond formatting.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool's function with a specific verb ('Updates') and resource ('tracked job'), and the focus on 'status' distinguishes it from sibling tools like tracker_update or tracker_add. No ambiguity.

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

  Usage Guidelines4/5

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

  It implies usage for changing a job's status, and the detailed enum of statuses clarifies the exact scenarios. It does not explicitly contrast with tracker_update, but the specific purpose is clear enough for an agent to select it.

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

• reminder_setA
  4.4/5.0
  Behavior4/5

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

  The description discloses a notable side effect beyond annotations: it sends a confirmation email with an .ics attachment. It also states the output (updated tracked job with reminderAt field). While it doesn't elaborate on the destructiveHint behavior (e.g., whether an existing reminder is overwritten), the additional email side effect and output description add meaningful transparency beyond the annotations.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is concise and well-structured: it opens with a clear one-sentence purpose, then uses bullet points for input parameters, and closes with an output note. Every sentence contributes useful information, and the structure makes it easy to scan.

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

  Completeness4/5

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

  For a tool with two parameters and an output schema (not shown here), the description covers the essential aspects: purpose, input requirements, side effects (email), and return value. It could have addressed the destructive behavior (e.g., what happens if a reminder already exists), which is hinted by the annotation, but overall it is sufficiently 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.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 100%, so parameters are already documented. The description adds extra value by clarifying that `tracked_job_id` must be `trackedJobs[].id` from tracker_list output, and explicitly distinguishes it from `trackable.id` and `job.id`. It also reiterates the future-date requirement for `remind_at`, reinforcing schema guidance.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool's action: "Sets a reminder for a tracked job." This is a specific verb+resource combination. It also adds a distinguishing side effect: "Sends a confirmation email with .ics calendar attachment." This differentiates it from other reminder tools like reminder_delete and reminder_list, and from generic job update tools.

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

  Usage Guidelines4/5

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

  The description provides clear context for when to use the tool: it is for tracked jobs, requires a future date, and specifies that `tracked_job_id` comes from `tracker_list` output. It does not explicitly mention alternatives or exclusions, but the context is sufficient for an agent to understand its applicability relative to siblings.

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

• job_alert_unsubscribe_allA
  4.5/5.0
  Behavior5/5

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

  The description adds significant behavioral context beyond annotations: the confirm parameter must be true (with rejection otherwise), it reports the number unsubscribed, and it is idempotent (returns success even with no active alerts). This complements the idempotentHint and destructiveHint annotations without contradicting them.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is concise and well-structured: a clear purpose sentence, then Input/Output sections, and an idempotency note. Every sentence adds useful information with no wasted words or repetition of structured fields.

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

  Completeness5/5

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

  The tool is simple (one parameter) and the description covers what it does, the confirmation guard, the output behavior, and idempotency. With annotations and an output schema present, the description is complete enough for an agent to use the tool correctly without further context.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 100% for the single parameter, so the schema already documents the confirmation requirement. The description repeats this and adds the rationale about guarding against unintended bulk unsubscribe, but this is marginal extra value. The baseline of 3 is appropriate when the schema carries the parameter details.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool unsubscribes the authenticated user from ALL job alerts across every subscription source (regular, company page, MCP). It uses a specific verb+resource+scope and inherently distinguishes itself from the sibling 'job_alert_unsubscribe' by emphasizing 'ALL' and 'at once'.

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

  Usage Guidelines4/5

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

  The description indicates this is a bulk operation for all alerts, implying it should be used when the intent is to unsubscribe from everything at once. It does not explicitly name alternatives or state when not to use it, but the scope is clear enough that an agent would not confuse it with a single-alert unsubscribe.

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

• jobs_recommendationsA
  4.5/5.0
  Behavior4/5

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

  The description adds valuable behavioral details beyond annotations: the processing status page, eventual completion on later calls, and pagination from the same feed. It also discloses that results carry specific insight payloads. Annotations already cover idempotency and non-destructiveness, and the description does not contradict them.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is two short paragraphs, front-loaded with the core purpose, then adding behavior notes. Every sentence provides useful information—ranking, related roles, payload, processing status, and pagination—without redundancy or fluff.

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

  Completeness5/5

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

  Despite having an output schema (not shown) and two optional params, the description covers the key aspects: what is returned, how it's ranked, what payload to expect, handling of processing status, and pagination behavior. It is complete enough for an agent to select and invoke the tool correctly, especially with the sibling context of jobs_search.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 100%, so the baseline is 3. The description enhances understanding of the 'page' parameter by explaining that page numbers fetch additional recommendations from the same feed, and it clarifies that 'location' is optional and affects the feed. This adds meaning beyond the raw schema descriptions.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool returns personalized job recommendations built from user-specific inputs (resume, skills, target roles, location). It distinguishes this from sibling tools like jobs_search by emphasizing personalization and ranking, making the purpose unambiguous.

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

  Usage Guidelines4/5

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

  The description provides clear context for when to use this tool (personalized feed, ranked results, same payload as job search) and even covers pagination and processing status. It does not explicitly name alternative tools or say 'when not to use', but the context is strong enough to guide correct usage.

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

• tracker_listA
  4.5/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context: results are 'grouped by status' and each response includes a 'system_instruction' for presenting results. This goes beyond the schema and annotations, disclosing output structure and client-specific presentation behavior.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is well-structured with a clear opening sentence, an Input section, and an Output section. Every line serves a purpose, and it avoids unnecessary fluff. The format is easy to scan and front-loaded with the core purpose.

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

  Completeness5/5

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

  Given that the tool is a read-only list operation, has a detailed schema (100% param coverage), an output schema, and strong annotations, the description is complete. It covers the purpose, input parameters, and output format, including the notable system_instruction. No critical information is missing.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100%, and the description's Input section simply duplicates the parameter descriptions already present in the schema. It does not add new meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool's function: 'Lists the user's tracked jobs'. The verb 'Lists' and resource 'tracked jobs' are specific, and it distinguishes itself from sibling tools like tracker_add, tracker_remove, and jobs_search by focusing solely on listing tracked jobs with optional filtering/pagination.

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

  Usage Guidelines4/5

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

  The description clearly implies when to use this tool (when you need to view a user's tracked jobs) and mentions its optional filtering/pagination, providing context. However, it does not explicitly mention when not to use it or name alternative tools, so it falls short of a 5 but has clear context.

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

• tracker_add_externalA
  4.6/5.0
  Behavior5/5

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

  The description discloses key behaviors beyond the annotations: 'Repeated saves return the existing tracked job' (idempotency), 'A save never waits on facts the source did not provide,' and that FoundRole's extractors derive missing fields from the description. It also explains the validation and separate storage of client_extraction labels. The annotations provide only false hints, so the description carries the full burden and meets it well.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness2/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is overly verbose, largely because the 'Fields:' bullet list duplicates the input schema's property descriptions almost verbatim, including all enum values and constraints. The first two paragraphs are valuable, but the lengthy list adds little beyond the schema and bloats the description. It is structured but not appropriately sized.

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

  Completeness5/5

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

  The description covers purpose, sibling differentiation, parameter semantics, extraction behavior, and return behavior. It states that the tool returns the tracked job and that repeated saves return the existing one. For a complex tool with 19 parameters and an output schema, this is sufficient for an agent to select and invoke it correctly without significant gaps.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The input schema has 100% description coverage, but the tool description adds important semantics. It clarifies that all non-required fields are optional and that 'a fact the source does not state is simply omitted (or null)' and explains that FoundRole's extractors derive missing facts like salary and skills from the description. It also clarifies that a short summary is acceptable for the description field and that client_extraction contains evidence-backed labels.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool's function: 'Saves a job posting found anywhere on the open web into the user's tracker.' It also distinguishes from sibling tracker_add by noting that tracker_add 'takes a job_id' and is for jobs from jobs_search results. This specific verb+resource+scope and differentiation earns a top score.

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

  Usage Guidelines5/5

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

  Explicit guidance is provided: 'For jobs that came from jobs_search results, tracker_add (which takes a job_id) is the right tool instead.' It also explains that a job seen elsewhere needs no prior jobs_search call, and that fields not stated by the source can be omitted. This clearly defines when to use the tool and names the alternative.

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

• knowledge_topicsA
  4.7/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, openWorldHint=false, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: the tool takes no parameters and 'reflects the live published corpus,' which implies real-time consistency. No contradiction with annotations.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is three sentences, front-loaded with the action and scope, followed by usage guidance and an explicit alternative. Every sentence contributes value: what it lists, when to use, and a contrast with knowledge_search. No redundancy or filler.

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

  Completeness5/5

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

  For a zero-parameter tool, the description covers the purpose, output content (categories, tags, counts, url, total), usage context, and an explicit alternative tool. An output schema exists, so return values need not be spelled out. The description is sufficiently complete 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.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The tool has zero parameters, and the schema coverage is 100% (empty properties object). The description explicitly says 'It takes no parameters,' which confirms the absence of any inputs. Baseline for 0 params is 4, and the description adds no further parameter explanation needed.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description uses the specific verb 'Lists' and names the resource ('FoundRole's published career-guidance blog') with concrete deliverables (categories, tags, counts, url, total count). It distinguishes from sibling tool knowledge_search by explicitly stating what it does not do ('does not retrieve articles for a specific question; knowledge_search does that').

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

  Usage Guidelines5/5

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

  The description states when to use this tool ('factual source for questions about the blog's topics or overall coverage') and provides an explicit exclusion with the alternative ('It does not retrieve articles for a specific question; knowledge_search does that'). This gives clear guidance on choosing between sibling tools.

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

• knowledge_searchA
  4.8/5.0
  Behavior5/5

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

  Annotations already mark the operation read-only and non-destructive, but the description adds meaningful behavior: returns empty groups rather than padding with off-topic content, returns closest matches rather than a full index, and includes a system_instruction in each response. No contradiction exists.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness4/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is longer than typical, but each sentence contributes meaning: core purpose, facet semantics, exclusions, behavioral guarantees, and response instructions. It is front-loaded with the main purpose before optional details, and no unnecessary repetition detracts from the value.

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

  Completeness5/5

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

  Given the tool's five parameters, multiple sibling tools, and rich output schema, the description covers the full context needed for correct invocation: what it searches, what facets mean, what it deliberately does not search, and how results behave. The agent is well-equipped to select and call this tool.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 100%, so the baseline is 3. The description goes beyond schema by explaining when each facet should be supplied and what it returns, e.g., company returns employer profile pages and job_title/location return job-listing landing pages.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description opens with a specific verb and resource: 'Searches FoundRole's published content by semantic similarity.' It clearly distinguishes from siblings by explicitly noting that knowledge_topics covers topic coverage and jobs_search covers live roles.

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

  Usage Guidelines5/5

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

  Provides explicit when-to-use guidance, such as 'a company mentioned only in passing does not need the company facet' and names alternatives for topic coverage and live job listings. This prevents the agent from misusing the tool for out-of-scope queries.

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

• tracker_addA
  4.8/5.0
  Behavior5/5

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

  The annotations indicate this is a non-read-only, non-destructive mutation, but the description adds crucial behavioral details: repeated saves return the existing tracked job, and previously removed jobs are restored with their earlier status and notes. This goes beyond the structured metadata and provides clear behavioral transparency.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness4/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is well-structured with a purpose statement, alternative guidance, and field details. However, it repeats the full sub_status enumeration that is already in the schema, which adds unnecessary length. The front-loaded purpose and behavior summary are concise, but the field list could have referenced the schema instead of duplicating it.

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

  Completeness5/5

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

  For a tool with four parameters and an output schema, the description covers purpose, alternatives, parameter semantics, default behavior, return value, idempotency, and restoration. It is complete enough for an agent to correctly invoke the tool without ambiguity or missing context.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The schema already provides 100% description coverage for all parameters, so the baseline is 3. The description adds valuable context by noting job_id is required, specifying the default for status ("saved"), and clarifying the source of job_id (from jobs_search results). These additions enhance understanding beyond the schema.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool tracks a job from jobs_search results using its job_id, which is a specific verb+resource+identifier. It explicitly distinguishes itself from tracker_add_external, which is for jobs found elsewhere on the open web. This provides strong differentiation 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.

  Usage Guidelines5/5

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

  The description gives explicit when-to-use guidance: use this tool for jobs from jobs_search, and tracker_add_external for jobs with a URL but no jobs_search job_id. It also describes behavior on repeated saves and restoration of removed jobs, which informs usage expectations.

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

• jobs_analyze_externalA
  4.9/5.0
  Behavior5/5

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

  Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses that FoundRole validates evidence, stores the client extraction separately, derives missing deterministic facts, and reports which values were provided, derived, accepted, rejected, or unknown. It also warns that the analysis is a decision aid, not a guarantee about sponsorship, legitimacy, compensation, or hiring outcome.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is organized into three focused paragraphs: purpose, input semantics, and output/limitations. It is dense but every sentence contributes essential context—no filler or repeated schema content—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.

  Completeness5/5

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

  Given the tool's 16 parameters, nested client_extraction object, and existing output schema, the description covers all critical aspects: what the tool does, required vs optional input, the evidence-backed nature of client_extraction, the comparisonRef need for later jobs_compare calls, and the decision-aid disclaimer. It is complete enough for an agent to select and invoke the tool correctly.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100%, so the baseline is 3, but the description adds meaningful context by explaining that the five text identity fields are required, all structured fact fields are optional, and fields absent from the source are simply omitted or null. It also clarifies that client_extraction must contain evidence-backed facts rather than inferences, which is not fully captured by the schema.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description opens with 'Analyzes one job found outside FoundRole using the authenticated user's FoundRole profile and the same signals used for FoundRole jobs,' which clearly specifies the verb, resource, and scope. It also distinguishes itself from sibling tracker_add_external by explicitly noting the save-without-analysis alternative.

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

  Usage Guidelines5/5

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

  The description provides explicit when-to-use guidance: 'Use tracker_add_external only when the user asks to save without analysis.' It also clarifies that the input must be the direct posting URL and all job content already available in the conversation, and that the five text identity fields are required while structured fact fields are optional.

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

• jobs_compareA
  5/5.0
  Behavior5/5

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

  Beyond the readOnlyHint and destructiveHint annotations, the description discloses important non-obvious behaviors: external jobs must be analyzed first because FoundRole does not have posting facts otherwise, references must be exact, order must be preserved, and duplicates are not allowed. These are operational constraints that materially affect invocation, and they are clearly stated. No contradiction with annotations.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is compact: two paragraphs with three sentences total. The first sentence front-loads the core action and fields. The second paragraph provides necessary constraints in a structured, easy-to-follow manner. Every sentence earns its place with no fluff or repetition of schema details.

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

  Completeness5/5

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

  The tool is simple (one parameter), has an output schema, and comes with annotations. The description covers the essential context: what inputs are valid, what the prerequisite is, and what constraints apply. The return value is not described, but an output schema exists and the comparison fields are already listed. This 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.

  Parameters5/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Although the schema already provides a decent description of comparison_refs, the tool description adds significant meaning: the accepted values are exact IDs from jobs_search and exact URLs from jobs_analyze_external, the prerequisite to analyze external jobs, and the requirements to preserve order and avoid duplicates. This goes well beyond the schema's item description and makes the parameter semantics unambiguous.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool 'Compares 2 to 4 jobs side by side' using specific analysis fields, making the verb and resource explicit. It differentiates from sibling tools by referencing jobs_search and jobs_analyze_external as input sources, which is exactly what distinguishes this comparison tool from search, details, or external analysis tools.

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

  Usage Guidelines5/5

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

  The description gives explicit when-to-use guidance: comparing 2 to 4 jobs. It specifies that inputs must be exact FoundRole IDs from jobs_search or external comparisonRef URLs from jobs_analyze_external, and includes a critical prerequisite: analyze external jobs before comparing. It also gives behavioral instructions like preserving order and avoiding duplicates, which helps the agent know how to construct the request.

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