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

Annotations already declare readOnly, idempotent, non-destructive, openWorld, so safety is covered. The description adds nothing behavioral beyond that — 'return HR call insights' is vague where the schema description enumerates speaker turns, sentiment, candidate intent, action items, and skill mentions. It also references a 'ctx' parameter that does not exist in the schema, which can mislead an agent about the call signature.

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

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

It is short, but the opening empty quote artifact and the 'Args:' block that documents a nonexistent parameter are wasted and confusing content. The useful sentence is front-loaded, which is a plus.

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

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

Given rich annotations, a 100%-covered single-parameter schema, and an output schema that carries the return-value detail, the description does not need to explain outputs or safety. What it must convey — that this analyzes a plain-text HR call transcript — is present.

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

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

Schema description coverage is 100% and the description repeats the transcript meaning verbatim ('Plain-text conversation between HR and candidate') without adding format, size, or quality expectations. Worse, the documented 'ctx: Optional MCP request context' parameter is absent from the schema, so the description introduces a phantom parameter rather than clarifying the real one.

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

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

States a specific verb and resource ('Analyze a plain-text HR call transcript') and a return intent ('HR call insights'). No sibling tool covers call analysis, so it is trivially distinguishable from the recruiting/skill-mapping siblings, though it never explicitly says so.

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

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

The 'plain-text' phrasing and the schema note that 'Audio files and call recordings are not supported' imply a usage boundary, but the description itself names no alternatives and gives no when-to-use or when-not-to-use guidance relative to siblings like extract_resume_data or detect_bias.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=true, and an output schema exists, so the disclosure burden is light. The description adds only that the traversal runs over a structured skill graph; it says nothing about latency, cost, or how large graphs are handled.

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

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

The opening sentence is well front-loaded, but the Args block duplicates the input schema verbatim, which is wasted space given full schema coverage. It is not bloated, but roughly half the content earns nothing.

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

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

With annotations, a full-coverage schema, and an output schema in place, the description only needs to establish purpose and use cases, which it does. The lack of sibling differentiation is the main remaining gap.

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

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

Schema description coverage is 100%, so the baseline is 3. The Args block largely restates schema fields and adds no format or semantics beyond it; it does not even reinforce the plain-text vs base64 mutual exclusivity that the schema defines.

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

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

States a specific verb ('traverses a structured skill relationship graph') and enumerates concrete outputs (related skills, gap analysis, near-fit candidates, learning paths). It is clear what the tool does, but it does not distinguish itself from siblings that do overlapping work, notably analyze_skill_gap and recommend_learning_path.

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

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

The enumerated question types imply when to use it, but there is no explicit when-not guidance and no routing to the overlapping siblings (analyze_skill_gap, recommend_learning_path). Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive behavior, so the safety profile is covered. The description's disclosure of returned fields is useful but largely duplicated by the output schema. It adds no cost, latency, or input-quality caveats (e.g., that plain-text resume/JD are required for meaningful results).

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

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

A single front-loaded sentence that states the comparison, the outputs, and the use cases with no filler. Every clause carries information.

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

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

With an output schema covering return values and annotations covering safety, the description only needs to establish purpose and routing. Purpose is complete; routing to the right sibling is the one missing element for this dense HR toolset.

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

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

Schema description coverage is 100% with only two parameters, both documented as 'Plain-text ... Required.' The description adds no format, size, or quality guidance beyond the schema, so the baseline 3 applies.

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

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

The description gives a specific verb+resource ('compares candidate or employee skills against a target job') and enumerates the outputs (present skills, missing skills, readiness score, development areas). It is clear on its own, but it does not name the closest sibling, score_resume_against_jd, which performs an overlapping resume-vs-JD comparison, so an agent cannot distinguish them from this text alone.

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

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

It lists three business contexts (hiring, internal mobility, workforce planning), which implies when to use it. However, there is no explicit when-not guidance and no mention of alternatives, which is a real gap given score_resume_against_jd, match_end_to_end, and analyze_skill_adjacency all sit in adjacent territory.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive behavior, so the safety profile is fully covered. The description adds that results are ranked and canonicalized, which is useful, but it says nothing about result limits, ranking logic, or behavior on empty/no-match input.

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

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

Two sentences with the core behavior front-loaded and no wasted clauses. The second sentence is slightly promotional ('from the moment a recruiter starts typing'), but it still conveys the intended usage context.

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

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

With an output schema present, full parameter documentation, and rich safety annotations, the description only needs to frame purpose and return kind, which it does. Minor gaps around result count and no-match behavior are acceptable for a simple read-only autocomplete endpoint.

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

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

Schema description coverage is 100% and the keyword parameter is documented with concrete examples ('soft', 'data sci'), so the schema does the heavy lifting. The description only echoes the 'partial job title string' notion and adds nothing about locale, language, or customvalues.

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

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

States a specific verb and resource: accepts a partial job title and returns ranked autocomplete suggestions with canonical titles and job families. The job-title domain implicitly separates it from autocomplete_skill and lookup_job_profile, but no sibling is named explicitly, so it falls short of a 5.

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

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

The phrase 'from the moment a recruiter starts typing' implies an interactive typeahead use case, but there is no explicit when-to-use or when-to-prefer alternative guidance (e.g., versus lookup_job_profile for exact lookups or autocomplete_skill for skills).

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds genuinely new behavioral context: a 2-character minimum input and a cap of 10 results, which affects how the agent should call and consume it. It omits what happens with zero matches, so not a 5.

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

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

Two sentences, front-loaded with the minimum length and result cap, which are the operationally important facts. The closing clause about keeping data clean is mild justification padding but supports the usage framing.

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

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

An output schema exists, so return values need not be explained in prose, and annotations cover the safety traits. The description covers input constraints and result shape adequately; the only missing piece is guidance on the optional locale/language scoping and empty-result behavior.

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

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

Schema coverage is 100%, so the schema already documents keyword, locale, language and customvalues; baseline 3 applies. The description restates the minimum length constraint but adds nothing about the scoping role of locale/language/customvalues, which is where extra meaning would have been valuable.

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

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

Specific verb+resource: accepts a partial skill prefix and returns ranked autocomplete suggestions with canonical names and categories, capped at 10. It is clearly an autocomplete tool, though it does not explicitly differentiate itself from the close sibling lookup_skill, which an agent might also consider for skill resolution.

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

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

Usage is implied rather than stated: 'at point of entry' and 'prevents free-text entry errors' suggest it belongs in data-entry flows, but there is no explicit when-to-use/when-not guidance or named alternative (e.g., lookup_skill for exact matches). The agent must infer the boundary itself.

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

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

Annotations already declare read-only, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds useful behavioral context by explaining that the tool returns one of five standardized O*NET Job Zones based on education, experience, and training criteria, though it does not discuss error handling or source-document parsing limits.

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

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

The description is front-loaded with the core action and return value, then explains the five Job Zones and downstream value. It is somewhat long due to the full enumeration of zones, but the information is relevant and structured rather than repetitive.

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

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

There is no output schema, so the description appropriately explains that the tool returns a standardized O*NET Job Zone level and what that enables. Combined with the fully described input schema and safety annotations, it is complete enough 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.

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

Schema description coverage is 100%, so the input schema already documents all four parameters, including filename, json_text, requesttype, and resume_text. The description does not add parameter-level semantics beyond what the schema provides, which is acceptable but not enriching.

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

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

The description states a specific verb and resource: it reads a resume/JD job profile and returns an O*NET Job Zone. It clearly explains the five-level output and the criteria behind it, but it does not explicitly distinguish this tool from similar siblings such as lookup_job_profile or autocomplete_job_profile.

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

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

The description lists downstream use cases like fit filtering, compensation benchmarking, and qualification flagging, which implies when the tool is useful. However, it does not give explicit conditions for choosing this tool over sibling tools or state any exclusions or prerequisites.

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

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

Annotations already declare read-only, idempotent, non-destructive, open-world behavior, so the description does not need to restate those traits. It adds useful context about preserving formatting fidelity and its pipeline role, but it claims base64/URL inputs that are not represented in the schema and omits what the conversion returns.

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

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

The description is three sentences and front-loads the core conversion behavior. It is appropriately sized, though some of its compact claims are inaccurate against the schema.

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

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

For a conversion tool with no output schema and all-optional parameters, the description should clarify what is returned or how converted output is delivered. It provides a useful use case and fidelity note, but leaves the response shape unspecified and mischaracterizes supported inputs.

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

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

Schema coverage is 100%, so the schema already documents filename, outputtype, resume_text, and facedetection. The description's mention of base64 or URL input is not supported by any parameter, and its reference to plain-text output does not match the outputtype enum, so it adds confusion rather than semantic clarity.

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

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

The description states a specific verb and resource: converts documents between named formats. It also distinguishes the tool's role as a pre-processing step before data extraction, which separates it from siblings like extract_resume_data or extract_resume_data_from_url.

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

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

It clearly says when the tool is useful: before extraction on non-standard file types. It does not name when not to use it or explicitly compare it to alternatives, but the context is sufficiently clear for a conversion utility.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered by structured data. The description adds the regulatory framing (NYC Local Law 144/EEOC) and the fact that it suggests neutral replacements, but says nothing about how findings are scored, disclaimers, or limits of the legal-risk judgement.

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

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

Two tight sentences, front-loaded with the action and the enumerated detection categories; the follow-up on suggested replacements earns its place as output behavior. No filler or restatement of the title.

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

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

With a full output schema and complete annotations, the description only needs to convey scope and detection categories, which it does well. The one shortfall is that it frames itself purely as job-description review while the tool equally accepts plain-text resumes, leaving that use case to the schema alone.

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

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

Schema description coverage is 100%, so the two parameters are fully documented in structured data and baseline 3 applies. The description adds no format or sizing guidance, and it never mentions that a resume can be scanned even though resume_data is one of the two inputs — 'hiring criteria' only loosely gestures at it.

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

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

The description gives a specific verb (reviews) applied to a specific resource (job descriptions and hiring criteria) and enumerates exactly the signal classes it detects: gendered language, age-coded terms, credential inflation, cultural exclusion, and LL144/EEOC risk. No sibling covers bias scanning, so it is unambiguously distinct from detect_resume_suspicion or score_resume_against_jd.

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

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

Usage is implied by the domain ('reviews job descriptions ... and hiring criteria'), but there is no explicit when/when-not statement and no routing to alternatives such as detect_resume_suspicion or score_resume_against_jd. The only concrete guidance ('supply this, resume_data, or both') lives in the schema, not the description.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is fully carried by structured data. The description adds only the accepted input formats, and says nothing about what counts as 'suspicious', whether a confidence or risk score is produced, or any size/rate limits — the added value over annotations is modest.

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

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

The purpose is front-loaded in a single sentence and the Args block is compact with no filler. The Args section largely duplicates what the schema already shows, so it isn't perfectly waste-free.

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

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

With an output schema present and full schema coverage, the description needn't explain return values, and annotations cover safety. However, for a fraud-detection judge the agent would benefit from knowing the analysis dimensions or any input constraints, none of which are given.

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

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

Schema description coverage is 100%, so both parameters are already documented with examples in the schema and the description only restates them. It also lists a 'ctx' argument that does not exist in the input schema, which is a minor inconsistency rather than added meaning.

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

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

The first sentence states a specific verb+resource ('Analyze a resume file') and the outcome ('identify suspicious or potentially fraudulent content'), which is clearly distinct from siblings like extract_resume_data or detect_bias. It stops short of explicitly naming the closest alternatives, so it lands at 4 rather than 5.

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

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

There is no when-to-use or when-not-to-use guidance and no prerequisites stated. It doesn't tell the agent how this differs in practice from detect_bias, score_resume_against_jd, or extract_resume_data, leaving the routing decision entirely to inference from the purpose sentence.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds useful context such as field-level confidence scores and GDPR/CCPA suitability, but it does not address limitations, and its reference to 'documents' is not reconciled with the schema's plain-text-only constraint.

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

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

The description is two sentences, front-loads the core extraction purpose, and adds compliance/output context without waste. Every phrase contributes to the tool's scope or output behavior.

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

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

For a simple one-parameter read-only tool with rich annotations and full schema coverage, the description is adequate but incomplete. It mentions confidence scores but does not describe return shape, and it lacks explicit routing versus sibling extraction tools or clarity on the plain-text-only input.

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

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

Schema description coverage is 100%, and the single text parameter is fully documented in the schema. The description adds no syntax or format detail beyond the schema and could mildly mislead by mentioning 'documents' despite the text-only restriction, so baseline 3 is appropriate.

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

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

States a specific verb and resource: it identifies and structures contact fields such as names, emails, phone numbers, LinkedIn URLs, and addresses. This clearly separates it from generic extraction siblings, though it does not explicitly differentiate itself from tools like extract_resume_data or tag_entities.

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

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

The description gives no explicit guidance on when to use this tool instead of alternatives such as extract_resume_data, extract_job_data, or tag_entities. It implies a contact-extraction use case, but provides no when/when-not conditions or routing cues.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive behavior, so the safety profile is fully covered without the description. The description adds the notion that role requirements are 'taxonomy-normalized', which hints at transformation behavior, but says nothing about input constraints, limits, or failure modes; and the field list largely duplicates what the output schema provides.

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

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

It is a single front-loaded sentence with the verb and resource first. The long enumeration of extracted fields is slightly padded, but every clause is on-topic and there is no filler.

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

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

With an output schema present, the return values need not be explained, and the lone input parameter is fully documented in the schema. The description supplies the domain framing (hiring data, taxonomy normalization) needed to place the tool, leaving only selection guidance against siblings unaddressed.

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

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

There is a single parameter with 100% schema description coverage, including an explicit warning to pass verbatim raw text rather than summaries or base64. With coverage this high the schema carries the semantics, so the description adds nothing param-specific and the baseline of 3 applies.

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

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

The description uses a specific verb+resource ('Extracts and converts job descriptions into structured hiring data') and enumerates the output fields, so the agent knows exactly what it produces. The resource name distinguishes it from siblings like extract_resume_data, but no sibling is named explicitly, keeping it just short of a 5.

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

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

The only usage signal is a generic purpose phrase ('for recruitment automation and candidate matching'), which describes downstream consumers rather than when to call this tool. There is no guidance on when to prefer it over extract_resume_data, map_job_to_skills, or generate_jd, and no prerequisites or exclusions are given.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint, so the safety profile is covered. What the description adds is largely unverifiable marketing ('up to 194%' conversion, 'under 10 seconds') and capability claims that the signature cannot back up — 'runs in batch mode' and 'resume reprocessing... without requiring a new document' are impossible with a zero-required-param call that only accepts a filename and inline text. These overstatements actively mislead about what the call does rather than clarifying it.

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

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

The purpose is front-loaded correctly, but the remainder is padded with promotional copy — conversion-rate statistics, speed claims, language counts — that does not help an agent decide or invoke. The genuinely useful sentence (the bulk import / talent refresh distinction) is buried at the end, and two full sentences are spent on capabilities the tool does not expose.

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

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

An output schema exists, so return values need not be explained, and the input schema is fully documented. But the description spends its length on modes (URL intake, batch, reprocessing) that this tool's parameters cannot perform, while omitting the one thing the agent needs to disambiguate: that this tool requires the resume as inline text, unlike its extract_resume_data_from_url sibling. For a tool in a 30+ sibling set with a near-identical name, that omission is a real gap.

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

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

Schema description coverage is 100% and both parameters are well documented in the schema itself (filename default and .txt append behavior; resume_text must be verbatim, not summarized or base64-encoded), so the baseline of 3 applies even though the description says nothing about either parameter. The description neither helps nor badly harms parameter understanding, but its silence on the inline-text requirement while touting URL/batch scenarios works mildly against correct invocation.

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

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

The opening sentence names a specific verb and resource ('Extracts and converts resumes, CVs, and candidate documents into structured, searchable profiles') and enumerates the output fields, so the agent knows exactly what the tool produces. It also contrasts with two related workflows (bulk import, talent data refresh), but those are not actual siblings — the real ambiguous neighbor, extract_resume_data_from_url, is never mentioned, so differentiation from the tool the agent is most likely to confuse it with is missing.

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

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

It describes several usage scenarios (careers page/application form auto-fill, batch migration, reprocessing old records), which implies when to reach for it. However, none of those scenarios are expressible with this tool's two parameters (filename, resume_text) — there is no URL, batch, or reprocess flag — and the description never states the actual selection rule: use this for inline resume text, use extract_resume_data_from_url when you only have a link. Usage is implied but not actionable.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive behavior, so the safety profile is covered. The description adds that the server fetches the URL directly and that it supports batch and multilingual processing, but it says nothing about failure modes the openWorld hint implies: authentication-protected URLs, redirects, oversized files, or fetch timeouts.

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

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

Front-loaded and reasonably brief, but it repeats the same idea twice: 'returns the same normalized JSON profile as the Resume Data Extraction tool' and 'Also supports the same auto-fill, multilingual, and batch-processing capabilities as the core extraction tool.' The second sentence largely restates the first and could be merged or dropped.

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

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

An output schema exists, so return values need no explanation, and the intake scenario is clear. What is missing is any statement about what happens when the fetch fails or the URL requires auth, which matters for an openWorldHint tool whose entire behavior is a remote fetch. Adequate but with a clear gap.

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

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

Schema coverage is 100% and the single `url` parameter is fully documented in the schema, including that it must be publicly accessible and that the server fetches it. The description adds no format or constraint detail beyond that. Baseline 3 applies when the schema does all the work.

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

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

States a specific verb and resource: it fetches a resume document from a URL and returns a normalized JSON profile identical in shape to the core extraction tool. It names the sibling tool implicitly ('the Resume Data Extraction tool'), though it never names `extract_resume_data` directly, so an agent must infer that sibling handles uploaded files while this one handles URLs.

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

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

Gives a clear usage context: 'Ideal for pipeline automation where resumes are stored in cloud storage, S3, or email attachments.' That effectively tells the agent to choose this over the upload-based sibling when the document lives behind a URL. It stops short of an explicit exclusion, e.g. what to do when the URL is not publicly accessible.

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

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

Annotations already declare this as read-only, idempotent, non-destructive, and open-world. The description adds that no index setup is required for the input document and that results are ranked by semantic similarity, but it omits return format, ranking behavior, and any limits on N.

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

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

The description is a single efficient sentence with the core behavior front-loaded. There is no redundant or filler content.

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

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

It is adequate for a read-only matching tool whose annotations cover safety, but without an output schema it does not explain the shape of returned matching documents. It also mentions 'top-N' without clarifying how N is determined, since no top_n parameter exists.

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

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

Schema coverage is 100%, so all four parameters are already documented in the schema. The description does not add meaning beyond the schema about doc_type, index_type, document_text, or the automatically injected index_key.

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

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

The description states a specific action and result: it accepts a resume or JD and returns top-N semantically similar documents from the indexed corpus. This is clear, but it does not distinguish itself from likely siblings such as search_indexed_documents or match_end_to_end.

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

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

It implies usage by describing the input document and indexed corpus, but gives no explicit when-to-use guidance or exclusions. With siblings like search_indexed_documents and score_resume_against_jd, an agent must infer which tool is appropriate.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is clear. The description adds that questions include type, competency, and expected answer signal, but it does not add much behavioral context beyond annotations and the output schema.

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

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

The description is a single efficiently structured sentence with the core action front-loaded and no filler. It covers question types, tailoring, and expected output signals without unnecessary repetition.

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

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

For a two-parameter generation tool with full schema coverage, rich annotations, and an output schema, the description provides enough context to understand what will be generated. The main remaining gap is lack of explicit usage guidance versus sibling tools, which is minor given the clear tool scope.

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

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

Schema description coverage is 100%, and the schema already documents both inputs, including the 50+ word minimum and the requirement to provide at least one. The description's phrase 'tailored to a role and candidate profile' loosely maps to the two inputs but adds no syntax or constraint details beyond the schema.

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

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

The description uses a specific verb and resource: 'Creates ... interview questions,' and names four question categories plus tailoring to role and candidate profile. It is clear what the tool produces, though it does not explicitly distinguish itself from nearby generation tools such as generate_jd.

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

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

The use case is implied by the description and tool name, but it does not state when to use this tool versus alternatives or when not to use it. The schema carries the key usage constraints, such as providing at least one of resume_data or job_description_data.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful non-obvious behavior: the output includes tone alignment, language support and inclusivity scoring. It omits a key behavior, though — all five parameters are optional with empty-string defaults, so it never says what happens if the agent supplies nothing (generic JD? failure?).

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

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

A single well-formed sentence with the verb and the output contract front-loaded, and no filler. It is slightly packaging-heavy by listing eight output facets that the output schema already enumerates.

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

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

With an output schema present the description needn't explain return values, and with 100% schema coverage the parameters are self-documenting; the definition is therefore nearly sufficient. The remaining gap is workflow context — no statement of prerequisites, empty-input behavior, or how the result relates to downstream JD-consuming tools.

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

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

Schema description coverage is 100%, so each parameter is already fully documented with examples ('Senior Java Developer'). The description only summarizes the parameters collectively as "simple role parameters" and adds no format, length or interaction constraints, so the baseline 3 applies.

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

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

States a specific verb+resource ("Generates structured job descriptions") and enumerates the sections produced, so the agent knows exactly what artifact comes back. It doesn't explicitly contrast with related siblings like score_resume_against_jd or extract_job_data, but no sibling shares this generating purpose, so ambiguity is low.

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

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

There is no when-to-use / when-not-to-use guidance and no named alternative. The phrase "from simple role parameters" hints at the input shape but not at the workflow decision (e.g. generate a JD first, then score resumes against it). The agent must infer placement in the pipeline.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=true, so safety and idempotency are covered. The description adds nothing about the open-world implication — that resolution likely hits an external geocoding service, what happens to unresolvable or ambiguous locations, or whether results are cached. With annotations carrying the safety profile, this is adequate but thin.

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

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

Two sentences, front-loaded with the transformation and followed by downstream use cases. No filler, though the second sentence is more marketing framing than operational guidance.

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

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

With no output schema, the description helpfully enumerates the returned fields (city, state, country, ISO codes, latitude, longitude), which is real value. It still doesn't clarify cardinality — whether multiple input locations or a parsed JSON blob yield one resolved object or a list — which leaves a meaningful gap for a tool accepting arrays and free-text blobs.

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

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

Schema coverage is 100% and both parameters carry detailed descriptions including an example object shape and the json_text extraction behavior, so the description need not restate them. It adds no syntax or format guidance beyond the schema, which is the baseline case for full coverage.

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

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

The description uses a specific verb ('Converts') and enumerates the resource and transformation target ('partial or informal location text' into city, state, country, ISO codes, lat/long). This is clearly distinguishable from siblings like normalize_candidate_data or classify_job_zone, though it never names an alternative explicitly.

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

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

Downstream uses are named ('enables radius-based candidate and job search', 'workforce planning analytics'), which implies when the tool is useful. However, there are no explicit conditions, prerequisites, or exclusions — nothing says when to call this versus normalize_hr_data_with_lov or normalize_candidate_data, which also touch location-bearing data.

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

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

Annotations declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, and the description adds real context on top: an external engine call, persistent storage under an index key, and duplicate-handling behavior (check_duplicate, update_duplicate) that materially affects repeat invocations. It still omits failure modes, whether re-indexing overwrites an existing documentid, and what authentication the userkey alternative requires.

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

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

Front-loaded with a one-line purpose, then scope, then an Args block proportional to 12 parameters. The middle sentence largely restates the opening ('RChilli's Index endpoint accepts a resume or job description along with the index type, document ID, and indexing options') and could be trimmed, but nothing is seriously bloated.

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

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

For a 12-parameter external mutation with no output schema, the description covers what is stored, why it matters downstream, and every argument. It stops short of describing return values, error conditions, or what happens to an existing document when a duplicate is found and update_duplicate is false, which an agent would want before calling.

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

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

Schema description coverage is 0%, so the description must carry the full burden, and it does document all 12 parameters with meaning beyond type alone (base64 encoding, filename must include extension, documentid is required and unique, blank userkey falls back to the session key, duplicate_fields defaults to ['id']). Gaps remain: indextype's allowed values are only loosely stated, and conditional relationships such as duplicate_fields only mattering when check_duplicate is true are unstated.

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

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

Specific verb and resource: indexes a resume or job description into the RChilli Search & Match engine, and it names the stored artifact (document against the configured index key). It implicitly separates itself from search_indexed_documents/find_matches_in_index by describing indexing as the write step that precedes searching, but never explicitly names a sibling.

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

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

The second paragraph gives the motivating condition for use: index once so the document can be searched, matched, and updated without re-processing. However, there is no explicit when-not guidance, no statement of when to prefer search_indexed_documents, update_profile, or a re-index, and no ordering prerequisites beyond a passing note about the session key.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds value by enumerating what comes back (canonical title, codes, salary bands, context), but says nothing about miss behavior when no profile matches, locale/language fallbacks, or data freshness — useful context for an openWorld lookup.

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

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

A single front-loaded sentence that leads with the verb and scope, then enumerates the return payload compactly. No preamble or filler; the only minor weakness is that the field list is a comma run rather than prioritized.

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

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

An output schema exists, so the description need not explain return values, and it still names the key fields. Annotations cover read-only and idempotency. What remains unaddressed is edge behavior (no match, locale defaults), which is a modest gap rather than a blocking one.

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

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

Schema description coverage is 100%, so the baseline is 3: each parameter (keyword, locale, language, customvalues, addrelatedskill) is documented in the schema, including the conditional trigger for addrelatedskill. The description adds no parameter-level detail beyond 'known job profile', so it neither compensates for nor exceeds the schema.

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

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

States a specific verb ('Returns authoritative detail for a known job profile') plus the concrete payload: canonical title, SOC/O*NET code, job family, skills, salary bands, work context. An agent can tell this is an exact-profile lookup. It stops short of naming the sibling it differs from (e.g. autocomplete_job_profile for partial/typo input), so it does not fully earn a 5.

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

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

'Known job profile' implies the exact-match/canonical-record case, which implicitly routes away from fuzzy or autocomplete lookups. However, no explicit when-to-use, when-not, or sibling reference (autocomplete_job_profile, map_job_to_skills) is given, so the routing has to be inferred.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered and the bar is lower. The description adds that results are 'authoritative' and full-record rather than ranked, which is useful, but says nothing about not-found behavior, partial keyword matching, or fallback when a skill is missing.

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

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

Two sentences with zero waste: the first front-loads what the record contains, the second frames when to use it. Everything is front-loaded and nothing is repeated or padded.

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

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

An output schema exists and the schema fully documents parameters, so the description needn't carry return structure or parameter detail. The one remaining gap is behavioral edge cases (skill not found, ambiguous matches), which for a lookup tool an agent would reasonably want stated.

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

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

Schema description coverage is 100%, so all four parameters (keyword, locale, language, customvalues) are already documented in the schema; baseline 3 applies. The description adds only the notion of a 'known skill' lookup and no extra meaning about keyword matching, locale fallback, or defaults.

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

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

Names a specific verb and resource ('Returns authoritative detail for a known skill') and enumerates what the record contains (aliases, related skills, proficiency levels, O*NET/ESCO mappings). It distinguishes itself conceptually from search-style behavior, though it never names a concrete sibling such as autocomplete_skill or skill_mapping.

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

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

'Use when you need the complete record rather than a ranked search' gives a clear selection condition. However, the alternative is described generically ('a ranked search') rather than by sibling tool name, and no exclusions or prerequisites (e.g., what to do on ambiguous or unknown skills) are given.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, and an output schema already defines the returned skill-map attributes, so the description's output enumeration adds little. Nothing beyond annotations is disclosed about determinism, taxonomy source, latency, or how proficiency signals are inferred.

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

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

A single front-loaded sentence with no filler. The dense list of output attributes is somewhat padded given an output schema exists, but the sentence remains efficient.

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

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

With annotations and an output schema carrying most of the load, the description is nearly sufficient, but it leaves a real ambiguity about the input: it claims to consume job descriptions while the only parameter is a job title. Clarifying that would close the remaining gap.

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

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

Only one parameter and schema description coverage is 100%, so the schema already explains 'Job Title' and marks it required. The description adds no format or example guidance and actually says 'job descriptions', which mildly conflicts with the single job_title string input.

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

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

Names a specific verb ('converts') and resource ('job descriptions into granular skill maps') and enumerates the output artifacts, so the agent knows the transformation performed. It does not differentiate itself from near-siblings like skill_mapping, autocomplete_job_profile, or extract_job_data, and it describes the input as a job description while the schema takes a job title.

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

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

There is no statement of when to use this tool, when not to, or which sibling to prefer. With three other skill/job-profile tools in the list, an agent has to guess that this is the expansion step rather than the lookup or autocomplete step.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world. The description adds genuinely useful behavior — that the response is ranked, scored, explainable, and audited — but says nothing about the orchestration's cost/latency or what happens to the intermediate extraction/index artifacts, which matters most for a multi-stage tool.

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

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

A single front-loaded sentence that enumerates the pipeline stages and the outputs in a logical order; slightly dense but every clause carries information.

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

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

Output schema and annotations are present, so return shape and safety need no repetition. Still missing for an end-to-end orchestrator: expected cost/latency, and guidance on when to prefer the granular siblings instead of this heavier call.

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

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

Schema description coverage is 100% and both parameters carry their own descriptions, so the schema does the work. The description adds no semantics about the resume/JD inputs, their expected granularity, or why both are marked 'Required' in text while the schema lists no required fields.

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

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

The description names a composite pipeline (extraction, indexing, taxonomy normalization, matching) and the concrete return (ranked candidates or jobs with scores, explanations, audit trail). This clearly separates it from single-step siblings like extract_resume_data or score_resume_against_jd, though it never names them explicitly.

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

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

Usage is only implied: 'from a single call' hints that this is the one-shot alternative to chaining the granular sibling tools, but there is no explicit when-to-use/when-not statement or named alternative.

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

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld. The description adds real behavioral detail beyond them: conflict resolution across sources, deduplication, and a field-level change log as the output artifact. It stops short of saying how conflicts are resolved (precedence rules) or that this is deterministic.

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

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

One dense sentence with no filler, and the resource and transformations are front-loaded. Slightly overstuffed but every clause conveys substance.

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

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

An output schema exists, so the change log needn't be explained, and annotations cover the safety profile. For a tool with a near-identical sibling, though, the description should clarify the boundary and note any input prerequisites; that routing information is the missing piece.

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

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

Single parameter with 100% schema description coverage, so the schema already carries the burden. The description only restates 'from multiple ATS or HR systems' and adds no format, size, or validation guidance beyond what the schema says ('JSON or delimited text').

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

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

States a specific verb+resource: 'cleans and normalizes candidate records from multiple ATS or HR systems', and names the concrete operations (conflict resolution, deduplication, standardized output). It does not differentiate from the sibling normalize_hr_data_with_lov, which an agent could easily confuse with this tool.

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

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

No statement of when to use this versus normalize_hr_data_with_lov or the extraction tools (extract_resume_data, extract_job_data) that feed it. The only implied usage is 'raw records from multiple systems', with no explicit preconditions or exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered by structured data. The description adds that results carry mapping confidence, which is useful behavioral context, but says nothing about unmatched values, fallback behavior, or open-world lookup implications.

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

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

A single well-formed sentence with the action verb front-loaded and no filler. It is efficient, though it spends words on the return value that the output schema likely already conveys.

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

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

With a rich annotation set, an existing output schema, and a fully documented single parameter, the description covers what is needed to call the tool. The missing piece is routing logic relative to sibling normalizers, which is a modest gap rather than a blocker.

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

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

Schema description coverage is 100% and the input_data parameter is fully documented in the schema with the data categories it covers. The description adds no syntax, format, or batching detail beyond that, so baseline 3 applies.

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

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

The description states a specific verb and resource: it maps raw HR data values to standardized List of Values entries and returns canonical values with mapping confidence. This is far more specific than the title alone. However, it never distinguishes itself from the close sibling normalize_candidate_data, so an agent cannot tell from the text which normalizer to pick.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no named alternative such as normalize_candidate_data. The only usage signal is the word 'Required' next to the parameter in the schema, which is contradicted by required params being zero.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive behavior, so the description's main added value is the shape of the output artifact. It does not disclose the openWorld variability (results depend on external labor-market/LMS knowledge) or how exhaustive paths are, which is exactly the context the lower annotation bar would reward.

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

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

A single dense sentence with the action and output structure front-loaded; every clause contributes. It is compact, though the long list of path components makes it slightly list-like rather than fully structured.

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

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

With an output schema present and full parameter descriptions, the description's job is to convey purpose and artifact content, which it does. The remaining gap is usage routing (when to choose this over skill-gap analysis), which is not fully covered.

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

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

Schema description coverage is 100%, so the schema already explains resume_data and job_description_data fully. The description only echoes them at a high level ('person's profile and target role') and adds no format or edge-case guidance, so baseline 3 applies.

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

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

Names a specific verb and artifact ('Builds structured learning paths') and enumerates the path's contents (prerequisites, skill sequence, certifications, proficiency targets, LMS alignment), which distinguishes it from neighbors like analyze_skill_gap or map_job_to_skills. It does not explicitly contrast with any sibling, so it stops short of a 5.

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

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

The phrase 'based on a person's profile and target role' implies the usage context (a resume plus a target job), but there is no explicit when-to-use, when-not-to-use, or pointer to complementary tools such as analyze_skill_gap. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, and the description merely restates 'Idempotent' rather than adding context. It does not explain what the call returns (masked text vs. file), whether the original content is preserved, or how masking interacts with the optional jsondata/resume_text inputs.

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

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

Two sentences, front-loaded with the core action and use cases. The trailing fragments 'Configurable redaction scope. Idempotent.' are low-cost but the idempotency claim duplicates the annotation, slightly wasting space.

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

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

For a 9-parameter tool with no output schema, the description should say what comes back (redacted resume text, filename, highlight metadata) and note that resume_text is the required payload. Those gaps leave the agent guessing about the response shape.

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

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

Schema description coverage is 100%, so every one of the 9 parameters is already documented in the schema. The description's only contribution is the generic phrase 'Configurable redaction scope,' which does not add meaning beyond maskfields/masktype/abbreviationfields.

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

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

States a specific verb+resource: redacts PII from candidate profiles/resumes. That is clearly separable from siblings like extract_resume_data or detect_bias. It stops short of naming a sibling it must not be confused with, so it is clear but not fully differentiated.

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

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

Lists downstream scenarios (anonymized review, bias-aware screening, compliance, audit logs) which imply when to call it, but gives no explicit 'use this instead of X' routing and no prerequisites, such as whether extract_resume_data must run first or how this relates to detect_resume_suspicion.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, and the description is consistent with a non-mutating generator. It adds some behavioral context (support for arbitrary input structures, six templates, four output formats) but says nothing about size limits, template rendering failures, or whether the output is returned inline, as a URL, or as a file blob.

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

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

The operational content is front-loaded in a single strong opening sentence. The second sentence is promotional padding ('eliminates manual reformatting effort', 'professional layout') that gives an agent no call-relevant information and could be cut without loss.

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

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

With six optional parameters, no output schema, and full schema coverage, the description covers inputs adequately via schema. The real gap is the return shape: for a document-generation tool the agent has no idea whether it receives bytes, a base64 string, a URL, or a stored filename, and the description does not fill that hole.

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

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

Schema description coverage is 100%, so every parameter — filename, json_text, outputtype, resume_text, templatekey, templatedata — is already documented in the schema. The description restates the template range and output formats but adds no semantics the schema lacks, such as when to prefer json_text over resume_text. Baseline 3 applies.

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

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

The first sentence states a specific verb and resource: it takes a structured candidate profile and applies one of six branded templates (TM001–TM006) to emit a PDF/DOCX/RTF/HTML document. That is far more precise than the title. It does not, however, distinguish itself from the sibling 'convert_document_format', which an agent could easily confuse with this tool.

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

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

The second sentence describes an audience (staffing firms, agencies, enterprise HR) and a benefit (brand consistency), not a usage condition. There is no statement of when to pick this over 'convert_document_format' or after 'extract_resume_data', and no prerequisites or exclusions. An agent must infer the decision boundary itself.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so the safety profile needs no restating; the description instead contributes the output contract and the 'bias-controlled and audit-ready' posture. Those qualifiers are useful but vague—no detail on how bias control is applied or what 'audit-ready' entails.

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

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

A single front-loaded sentence with zero waste on process description. The trailing 'Bias-controlled and audit-ready' is mildly promotional rather than operational, which keeps it off a 5.

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

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

With no output schema, the description correctly enumerates the return values an agent needs to decide to call it. It leaves open which dimensions are scored and how gaps are represented, a minor gap for a read-only scoring tool with fully documented parameters.

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

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

Schema description coverage is 100%, so every parameter is already documented, and the baseline is 3. The description only reinforces the cardinality (one resume, one JD) and adds nothing about match_type direction or the filename parameters.

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

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

States a specific verb and resource (scores one resume against one JD) plus the exact return payload (overall score, dimension scores, skill gaps, explanation). The phrase 'no index required' differentiates it from indexed siblings like find_matches_in_index and match_end_to_end.

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

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

'Accepts one resume and one Job Description (no index required)' implicitly routes the agent away from index-based matching tools, and the return shape signals it is the single-pair scoring path. It does not explicitly name an alternative or state when not to use it, 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.

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

Annotations already declare readOnlyHint=false, openWorldHint=true and idempotentHint=false, so the description is not carrying the safety burden. It does add that the agent runs over volume and emits a proceed/hold/reject decision, but it omits the interactive, session-scoped nature of the operation — that follow-ups resume the same conversation — which is the primary behavioral surprise here.

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

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

Two tight sentences with no filler; the core capability leads and the batch-scope qualifier follows. Nothing is wasted, though the trailing sentence is a qualifier rather than new information.

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

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

An output schema exists, so return values (score, insights, gaps, recommendation) need not be fully specified, and annotations cover the safety profile. The remaining gap is orientation against the many similarly named screening siblings, which the description does not address.

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

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

Schema description coverage is 100%, so both parameters (message, session_userkey) are already fully documented in the schema, including the 'reuse the same value for every follow-up' instruction. The description adds no parameter-level detail beyond that, which is the expected baseline when the schema does the work.

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

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

States a concrete verb and resource — evaluates candidates against job requirements and custom criteria — and enumerates what comes back (score, insights, skill gaps, proceed/hold/reject). The batch framing ('high-volume application batches') separates it somewhat from single-resume siblings, but it never names an alternative such as score_resume_against_jd or match_end_to_end, so the boundary stays inferential.

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

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

'Supports high-volume application batches' implies usage on bulk application flows, but there is no explicit when-to-use, when-not-to-use, or routing to a sibling tool. The agent must infer whether to pick this over score_resume_against_jd or match_end_to_end.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the indexing prerequisite, which is useful operational context, but says nothing about result limits, empty-result behavior, or corpus scope despite openWorldHint=true.

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

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

Two short sentences with no filler; the core action leads and the prerequisite follows. Slightly under-informative rather than padded, which is the right direction.

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

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

With only two fully documented parameters, strong annotations, and no output schema, the definition is nearly sufficient. Still missing is any hint of what a search returns or how it relates to the sibling matching tool, which an agent would want before choosing it.

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

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

Schema coverage is 100%, and the schema itself documents both 'keyword' (with an example) and 'indextype' (with allowed values Resume/JD). The description adds no parameter-level meaning beyond this, so the baseline 3 applies.

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

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

States a specific verb (search) and resource (indexed documents) plus the mechanism (keyword), so the agent knows exactly what the tool does. It does not differentiate itself from nearby siblings such as find_matches_in_index or index_document, leaving the boundary to be inferred.

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

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

The prerequisite 'Documents must be indexed before using this tool' gives a real usage condition. However, there is no guidance on when to prefer this over find_matches_in_index or other matching/search tools, so the choice among siblings is implied at best.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds that the output is a 'normalised taxonomy label' (RChilli taxonomy) and that input must be escaped plain text, but says nothing about what happens to unmatched skills or about taxonomy coverage limits. Note the stale 'userkey' arg, which no longer exists in the schema.

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

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

The opening sentence is well front-loaded and wastes nothing. The trailing 'Args:' docstring block is boilerplate that partly duplicates the schema and contains an argument the schema does not define, so it does not earn its space.

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

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

With a single well-documented parameter, full annotation coverage, and an output schema handling the return value, the description covers what an agent needs to make the call. Only the stale userkey reference and lack of sibling disambiguation keep it below complete.

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

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

Schema description coverage is 100% and resume_data is fully documented in the schema, so the baseline is 3. The description restates the same idea ('Resume as an escaped plain text string') and adds a format hint, but also lists a 'userkey' parameter that is not present in the input schema, which risks the agent passing a nonexistent argument.

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

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

The first sentence gives a specific verb and resource ('Map every skill mentioned in a resume to a normalised taxonomy label'), so the agent knows exactly what transformation happens. It does not distinguish itself from nearby siblings such as map_job_to_skills or lookup_skill, which is the only thing keeping it from a 5.

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

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

Usage is only implied by the phrase 'in a resume'; there is no explicit when-to-use, when-not-to-use, or prerequisite statement. With siblings like map_job_to_skills, autocomplete_skill, and lookup_skill in the catalog, the description should say which one applies to which input.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds the genuinely unknown behavior: that output is inline-labeled text preserving the original document structure rather than offset/field lists, plus the entity type coverage. No mention of text-size limits or failure modes, which keeps it from a 5.

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

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

The core behavior and the differentiating examples are front-loaded and earn their place. The closing clause ("immediately consumable by ATS field-mapping pipelines... without any offset calculation or post-processing") drifts into marketing framing that could be trimmed.

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

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

With no output schema, the description carries the burden of explaining returns and does so well via concrete inline-labeled examples and stated entity coverage. A note on input size limits or entity-type edge cases would make it fully complete for a lightweight two-parameter tool.

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

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

Schema description coverage is 100%, so both parameters (text, subuserid) are already documented, and the description adds only the implicit note that input is plain text rather than a file. The tenant-isolation parameter is never referenced, so the description does not meaningfully extend the schema.

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

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

States a specific verb and resource: it annotates already-extracted HR text by wrapping recognized entities in inline XML-style labels. The contrast with sibling extraction tools ("Unlike data extraction tools that produce separate field lists") makes the boundary clear, and the inline examples make the output unmistakable.

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

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

Clearly signals the input precondition (already-extracted plain text) and distinguishes the tool from extraction siblings, which routes the agent well. It stops short of an explicit when-to-use/when-not rule naming a specific alternative such as extract_resume_data, so it's clear context rather than full routing guidance.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, destructiveHint=false and non-idempotent, so the safety profile is covered. The description adds real value beyond those flags: it discloses that refreshed profile fields are written back into external ATS/CRM systems, that consent is captured, that interaction logs are produced, and that backend rejections must be masked while missing values are re-requested from the user.

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

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

The purpose is front-loaded, but roughly half the text is output-formatting rules that repeat themselves ('Do not show ... explanation, dashboard guidance, or any other text' restated later as 'Do not add dashboard guidance, call-status disclaimers ... or any other explanation'). The verbose Args block duplicates the schema instead of earning space.

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

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

An output schema exists, so return values need no explanation and the schema documents all seven parameters. Still missing is context an agent needs to invoke safely: what triggers consent capture, whether the candidate must already exist, and whether calling this initiates a real-time interaction or just a write — especially given the 'Call scheduled successfully.' contract.

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

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

Schema description coverage is 100%, so the baseline is 3 and the Args block largely restates the schema. The one genuine addition is the timezone inference/ambiguity rule, which explains behavior the schema only hints at; the rest (e.g. 'Candidate identifier.') duplicates existing parameter descriptions verbatim.

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

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

The opening sentence names several outcomes (collect candidate info, capture consent, log interaction, write fields back to ATS/CRM), but the core action is ambiguous: the mandated success text 'Call scheduled successfully.' implies this schedules an outbound call, which the description never states. An agent cannot cleanly separate this from siblings such as normalize_candidate_data or screen_application_batch, since no sibling is named or excluded.

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

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

There is no explicit when-to-use guidance and no mention of alternatives among the 34 sibling tools. The only conditional instruction is procedural ('If timezone inference returns multiple possible zones, request the candidate's exact IANA timezone ... before calling the tool again'), which covers a retry edge case rather than tool selection.

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