Server Quality Checklist

Tool Scores

• get_skill_historyA
  4.4/5.0
  Behavior4/5

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

  Annotations already indicate readOnlyHint and openWorldHint. The description adds context about the data granularity (monthly) and computed deltas, and mentions 'Analyst tier' implying access level. 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.

  Conciseness5/5

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

  Highly concise: two sentences plus a use-case statement and a negative instruction. Information is front-loaded and every sentence adds value.

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

  Completeness4/5

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

  With output schema present and annotations, the description covers core purpose, use cases, alternatives, and data details. Minor omission: data start date (March 2026) is in schema but not description. Still largely complete.

  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 covers all parameters with descriptions. The description adds example values but does not significantly enhance understanding beyond schema. Baseline 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 it provides time-series data on a skill's market adoption, listing specific metrics (companyCount, jobMentions, top companies, MoM deltas). It gives concrete example queries and distinguishes from 'find_emerging_skills'.

  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?

  Explicitly tells when to use (tracking adoption growth/dominance of known skills) and when not to (for unknown early-stage skills), directing to an alternative tool. Provides example use cases.

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

• get_company_profileA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, so the read-only behavior is clear. The description adds behavioral context by enumerating the return fields and stating that it returns a comprehensive hiring profile. No contradictions with annotations. Could be higher if it mentioned any potential rate limits or additional side effects, but for a read-only tool the transparency is solid.

  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 (two sentences), front-loaded with the purpose, and contains no filler. Every sentence adds value: purpose, return values, usage examples, and exclusions. Efficient and well-structured.

  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 has only 1 parameter, high schema coverage, and an output schema (which presumably details return structure), the description is sufficiently complete. It specifies what is returned and provides context on when to use the tool. No missing critical information for an AI agent to correctly select and invoke the 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?

  Schema description coverage is 100% and the single parameter 'domain' already has a detailed description in the schema (e.g., format example, apex domain note). The tool description does not add additional parameter information; it only mentions 'by domain'. Therefore, baseline 3 is appropriate as the schema covers parameter semantics adequately.

  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 verb 'Fetch' and the resource 'full hiring profile for a single company by domain'. It lists specific return fields (tech stack, role distribution, etc.) and distinguishes from siblings by referencing alternatives like get_company_history and company_fit. This provides high specificity and differentiation.

  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 explicitly provides example queries ('what is Stripe hiring?', 'what tech does Anthropic use?') and states what the tool is NOT for ('Not for historical trends... or the user's personal fit'), naming specific sibling tools. This gives clear when-to-use and when-not-to-use guidance.

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

• get_jobA
  4.5/5.0
  Behavior4/5

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

  Annotations declare readOnlyHint=true, consistent with fetch. Description adds return field details beyond annotations, but no behavioral quirks beyond that.

  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?

  Three concise sentences: purpose, usage, exclusions. No redundancy, well-structured.

  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 read tool with output schema, description covers input modes and return fields adequately.

  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%, so description adds limited new meaning. It clarifies the relationship between url, jobId, and domain, and warns about verbatim jobId usage.

  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 fetches one job posting by domain+jobId or URL, and lists return fields. It distinguishes from siblings like search_jobs and match_job.

  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?

  Explicitly says when to use (after search_jobs or when user pastes a URL) and when not to (browsing, personal fit scoring), with sibling tool names.

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

• get_company_historyA
  4.6/5.0
  Behavior4/5

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

  Annotations already indicate readOnlyHint=true, and the description adds context about being 'Analyst tier' and notes that detailed snapshots began March 2026, capping available history. No contradictions. Description 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.

  Conciseness5/5

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

  Two sentences: first packs the return values, second gives usage and exclusions. No unnecessary words. Highly efficient.

  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?

  Given the tool's complexity (time-series with many fields), the description covers key return elements and the main limitation. Output schema exists but not shown; description compensates. Missing edge case handling or error scenarios, but still very complete.

  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%, baseline 3. The description adds context about months default and max, and the historical depth limitation starting March 2026. This extra information helps the agent understand parameter constraints beyond 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's purpose: 'Time-series of a company's hiring profile.' It lists the specific data returned (monthly snapshots with metrics like totalJobs, engineeringJobs, etc.) and explicitly differentiates from siblings get_company_profile and compare_companies.

  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 usage examples: 'Use for "how has Anthropic's hiring changed since January?" or "is Stripe growing or shrinking?"' and clearly states when not to use: 'Not for a current-state snapshot (get_company_profile) or side-by-side comparison (compare_companies).'

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

• market_positionA
  4.6/5.0
  Behavior4/5

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

  Annotations indicate readOnlyHint=true; description adds detailed computation weighting (50% skill demand, etc.) and expected output fields. Does not disclose rate limits or authentication beyond 'Pro tier', but is largely transparent.

  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?

  Description is concise and front-loaded with purpose and weighting, though the weight breakdown could be slightly more succinct. No unnecessary 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?

  Given no parameters and presence of an output schema, the description fully covers tool functionality, including inputs (none), computation logic, and return fields. Appropriate for its 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?

  No parameters; schema coverage is 100%. Description explains the computation context, which is sufficient for a param-less tool. Baseline score of 4 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?

  Clearly states it computes a market position score (0-100) with weighted breakdown. Distinguishes from job-specific and company-specific tools, making its 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 Guidelines5/5

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

  Explicitly lists example queries and what the tool is not for (job-specific or company-specific scores), providing clear guidance on when to use vs. alternatives.

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

• interview_prepA
  4.7/5.0
  Behavior5/5

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

  Beyond annotations (readOnlyHint, openWorldHint), the description reveals premium tier status, depth variation based on seniority, and context sources (job description, tech stack, user skills), providing rich behavioral context 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.

  Conciseness5/5

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

  The description is concise with two sentences that are front-loaded with purpose. Every sentence adds value: first sentence specifies outputs, second provides usage guidance and sibling distinction.

  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, output schema existence, and 100% parameter coverage, the description sufficiently covers inputs, outputs, usage, and constraints, leaving no major gaps for an AI agent.

  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%, so baseline is 3. The description does not add extra meaning beyond the schema's parameter descriptions (url, jobId, domain). The instruction to pass jobId verbatim is already in 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 generates targeted interview prep with specific outputs (5 key topics, 5 questions, 3 research items) and explicitly distinguishes from the sibling tool `resume_rewrite` by stating it is not for resume tailoring.

  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 use cases ('help me prep for my Anthropic interview') and directly states when not to use the tool ('Not for resume tailoring — use `resume_rewrite` for that'), offering clear guidance and an alternative.

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

• salary_benchmarkA
  4.7/5.0
  Behavior4/5

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

  Annotations already indicate readOnlyHint=true. The description adds valuable behavioral context: it's Pro tier, returns percentiles, percentile ranking, and career-ladder progression. 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.

  Conciseness5/5

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

  The description is concise and well-structured, with the action first, followed by key features and exclusions. Every sentence adds 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 has an output schema and 3 parameters, the description covers the purpose, output contents, usage guidance, and exclusions comprehensively.

  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%, but the description adds meaning beyond individual parameter docs by explaining how omitting parameters affects the slice (whole market, all seniorities) and that salary enables percentile ranking.

  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 a salary against live market data for a role family and seniority slice. It uses specific verbs and resources, and distinguishes from sibling tools like get_job and get_market_pulse.

  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 explicitly provides use cases ('am I paid well?', 'what should I ask for?') and tells what not to use it for, naming specific alternatives (get_job, get_market_pulse).

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

• watchlist_intelligenceA
  4.7/5.0
  Behavior4/5

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

  Annotations already indicate readOnlyHint=true; the description adds valuable context about Pro tier requirement and details the returned fields (hiringTrend, trendPct, etc.) without contradicting 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 (few sentences), front-loaded with purpose, then return fields, then usage guidelines. Every sentence adds value with no 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?

  Given zero parameters and an existing output schema, the description fully covers purpose, usage, return values, and constraints (Pro tier), making it complete for an AI agent.

  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?

  No parameters are defined, so the description correctly focuses on the output and usage. The 0-param baseline is 4, and the description adds no unnecessary param info.

  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 ('aggregate') and resource ('hiring intelligence on watched companies'), clearly distinguishing from sibling 'list_watchlist' which returns a plain list.

  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?

  Explicitly provides example queries for when to use the tool and specifically states when not to use it, naming the alternative tool (list_watchlist).

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

• get_market_historyA
  4.9/5.0
  Behavior5/5

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

  Annotations declare readOnlyHint=true, confirming safe read operation. Description adds behavioral details like data resolution (daily back to early March 2026, monthly from March 2026) and explains the difference between compact and full detail modes. 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.

  Conciseness5/5

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

  Three sentences, front-loaded with the core purpose and key outputs. Every sentence adds essential information without waste.

  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 (4 parameters, two granularities, two detail modes), the description covers resolution, parameter interactions, and distinguishes from sibling tools. Output schema exists, so return values need not be detailed.

  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 already provides 100% coverage with detailed parameter descriptions. The description adds value by explaining when parameters are used or ignored based on other parameters (e.g., days ignored when range=monthly), which aids correct usage.

  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 it returns time-series of market-wide hiring stats with specific metrics (total jobs, remote share, compensation, etc.). It distinguishes from siblings like get_market_pulse by explicitly noting it is not for current snapshots.

  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?

  Explicitly provides usage scenarios: 'how has the market shifted in 2026?' or 'is remote hiring trending up?'. Also clearly states when not to use: for current snapshot, use get_market_pulse instead.

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

• resume_rewriteA
  4.9/5.0
  Behavior5/5

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

  The description adds behavioral context beyond annotations: it specifies the returns (before/after rewrites, missing keywords, ATS tips), notes it's a premium tier feature, and indicates the resume upload requirement. No contradiction with readOnlyHint 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 brief, well-structured, and front-loaded. Every sentence adds critical information without redundancy.

  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 has 3 parameters and an output schema, the description fully covers input preconditions, output summary, and usage context. It also mentions premium tier and prerequisites.

  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 baseline 3. The description adds extra value by explaining that 'url' is a convenience alternative to 'domain'+'jobId', and that 'jobId' must be passed verbatim from search_jobs with '#' separators.

  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 explicitly states the tool generates targeted resume bullet rewrites for a specific job using the user's resume and job description. It clearly distinguishes from sibling tools like interview_prep.

  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 direct usage examples ('rewrite my resume for this Stripe role') and explicitly states when not to use it ('Not for interview preparation') with a named alternative (interview_prep). It also mentions the prerequisite of having a resume uploaded.

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

• search_jobsA
  4.9/5.0
  Behavior5/5

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

  Beyond the readOnlyHint annotation (true), the description discloses important behavioral traits: q does not search job descriptions or skill list, pagination via cursor, salary_min/salary_max matching logic, and that results are a slim list with specific fields. No contradictions 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.

  Conciseness4/5

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

  The description is well-organized and front-loaded with the primary action. It efficiently covers purpose, output, examples, and exclusions. Slightly verbose with comma-separated lists but no wasted sentences.

  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 16 parameters and the existence of an output schema, the description adequately covers filtering behavior, return fields, pagination, and edge cases (e.g., salary range matching, q not searching descriptions). It leaves no major gaps.

  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?

  Despite 100% schema coverage, the description adds significant meaning: explains q's scope limitations, clarifies salary_min and salary_max semantics with examples, describes cursor usage, and provides usage tips for skill and posted_since parameters.

  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 searches HireJack's database of live tech job postings, lists filterable attributes, and describes the returned data format. It also explicitly distinguishes from sibling tools like get_job, get_company_profile, recommendations, and get_market_pulse.

  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 guidance on when to use this tool (for searching tech jobs with various filters) and when not to use it (for single job, company profile, recommendations, market stats). Also gives example queries to illustrate appropriate usage.

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

• skill_gapA
  4.9/5.0
  Behavior5/5

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

  Description adds significant behavioral context beyond annotations: explains return values (matchPct, map of skills, missing skills ranked by impact). Annotations already indicate readOnlyHint, and description does not contradict it.

  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?

  Three sentences with no fluff: first sentence states purpose, second details outputs, third gives usage guidelines. Front-loaded and efficient.

  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 zero parameters and output schema present, the description fully explains what the tool returns and when to use it. Sibling tools provide context. No 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?

  No parameters defined, so schema coverage is 100% vacuously. Baseline for 0 params is 4; description has no need to add param info.

  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 analyzes the gap between the authenticated user's current skills and desired role requirements in the live market. It uses a specific verb ('Analyze') and resource ('gap'), and distinguishes from sibling tool 'skill_impact'.

  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?

  Explicitly provides use cases ('what should I learn next?', 'how close am I to senior PM roles?') and tells when NOT to use it ('Not for simulating...'), directing to alternative 'skill_impact'. Also mentions 'Pro tier' as context.

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

• skill_impactA
  4.9/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint=true and openWorldHint=false; the description adds that it is a simulation (no actual skill addition) and lists output fields. No contradictions, and adds meaningful behavioral context 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.

  Conciseness5/5

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

  Three sentences: purpose, output details, usage guidance. Front-loaded and every sentence adds value. No 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?

  Given zero parameters, an output schema exists, and sibling tools are listed, the description covers purpose, usage, output structure, and distinguishes from related tools. Complete for an agent to decide when and how to invoke.

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

  Parameters4/5

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

  No parameters (0 params), so baseline is 4. The description does not need to add parameter information and appropriately focuses on behavior and output.

  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 simulates adding each missing skill and computes market impact, returning a ranked list. It explicitly distinguishes from sibling 'skill_gap' by noting it's not for auditing current skills.

  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 use cases ('what should I learn next?', 'which skill would unlock the most jobs?') and a clear when-not-to-use ('not for auditing... use skill_gap'), naming the alternative tool.

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