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

Adds real behavioral context beyond annotations: extracted claims are tagged with confidence 'user_claim' and are unverified assertions by the candidate, which tells the agent how to treat downstream results. Annotations only cover readOnly/idempotent/destructive hints; the semantic 'not verified' caveat is valuable. Doesn't disclose return shape or duplicate-profile behavior, 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 tight sentences, front-loaded with the primary action and followed by the critical semantic caveat. 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?

Annotation set (readOnly=false, idempotent=false, destructive=false) matches a registration tool, and the description covers the write action plus claim semantics. No output schema exists, yet the description explains the key return concept (individually-citable claims with confidence). Lacks explicit 'what happens on duplicate candidate' detail, hence not 5.

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 parameters are fully documented in the schema (name, cvText, summary, headline). The description adds only format guidance ('Markdown or plain text'), which the schema already states, so baseline 3 is correct.

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 ('Registers') and resource ('a candidate's CV') plus the generative action ('extracts individually-citable claims'). Far clearer than siblings like careerproof_add_project_evidence, which the description implicitly distinguishes by focusing on the candidate's own CV.

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

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

Implies usage (onboarding a candidate's CV before scoring/matching), but never explicitly says when to use this vs careerproof_add_project_evidence or careerproof_index_repository, nor any prerequisites. Adequate but no alternative routing.

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, idempotentHint=false, and destructiveHint=false, so the write/safety profile is covered structurally. The description adds the useful rationale for the default confidence value, but says nothing about the consequences of non-idempotency (e.g., whether repeated calls create duplicate evidence rows) or what the caller gets back, which is the kind of extra context a mutation tool benefits from.

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 tightly written sentences, front-loaded with the verb and resource before the rationale, with no wasted framing. The second sentence slightly duplicates the schema's declared default, but it earns its place by explaining why the default exists.

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 is the only place an agent could learn what the call returns, and it is silent on that. It also leaves the spatial/line parameters and sourceType semantics unaddressed, though for a straightforward add operation whose safety profile is covered by annotations, it is minimally adequate.

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

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

Schema description coverage is only 43% across 7 parameters, so the description should compensate, but it does not: filePath, lineStart, lineEnd, and sourceType are unexplained in both places. The only parameter reference is the 'inferred' confidence default, which merely restates the schema's own description and enum default.

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 (manually attaches), the resource (an evidence item), and the target (an indexed project), with a concrete example clarifying what counts as manual evidence. The word 'manually' plus the 'indexed project' reference cleanly separates it from automatic extraction siblings like careerproof_index_repository and from retrieval siblings like careerproof_find_evidence.

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 mention of a default 'inferred' confidence because the item 'wasn't pulled directly from a verifiable source' implies this tool is for evidence that cannot be sourced automatically, which hints at when to use it. However, it never explicitly says when to prefer this over careerproof_index_repository or other add_* siblings, nor any prerequisites beyond the implicit need for an indexed project.

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

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

With no annotations, the description carries the full burden and does real work: it discloses the extraction mechanism (bullet parsing plus a curated keyword dictionary), that no LLM is involved (deterministic, limited recall), and that the JD is persisted. It still omits what happens on re-submission, whether the text is deduplicated, and any permission or size constraints.

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 followed by the mechanism and the important 'no LLM' caveat. No filler, though the em-dash clause could be tightened slightly.

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 2-parameter tool with no output schema, the description adequately covers intent, mechanism, return shape (structured skills/tools/competencies), and the determinism caveat. What is missing — error behavior, persistence semantics, and downstream pipeline ordering — is minor but non-trivial.

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 documented there, so the baseline is 3. The description adds no syntax, format, or length guidance beyond the schema (e.g., it does not mention the 20-character minimum).

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 pair ('stores a pasted job description and extracts structured requirements') and even names the extracted categories (skills, tools, competencies). It does not explicitly differentiate itself from siblings like careerproof_match_requirements, but an agent can tell it is the ingestion/extraction step.

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: storing and extracting a JD is clearly the upstream step before match_requirements or find_evidence_gaps, and the note that 'the connected client can add further reasoning' hints at pipeline position. No explicit when-to-use, when-not-to-use, or named alternative is given.

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

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

With no annotations, the description carries the full behavioral burden, and it does disclose the output medium ('Returns either JSON or a Markdown report'), which is genuinely useful. However, it says nothing about side effects (is anything persisted?), cost/latency implied by generating interview questions, or whether it requires prior analysis state, so the disclosure is partial.

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 tightly written sentences: the first front-loads what is assembled and its components, the second covers the return format. No filler, no restatement of the tool name, every clause earns its place.

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

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

For a three-parameter aggregation tool with no output schema and no annotations, the description covers purpose and output medium but leaves the candidateId parameter unexplained and gives no usage routing against the many sibling tools that perform the same sub-tasks. Adequate but with clear gaps.

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

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

Schema description coverage is only 33%, so the description should compensate, and it partially does by explaining the output format choice (JSON vs Markdown) that the 'format' parameter controls. It adds nothing about 'candidateId' (unlabeled in schema and absent from the description) and only implicitly covers jobId via the task framing.

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 ('Assembles') and a well-defined artifact ('complete evidence-backed preparation pack for a job'), then enumerates the three contents: requirement matches, evidence gaps, and generated interview questions. That enumerates capabilities that map onto sibling tools (match_requirements, find_evidence_gaps, generate_interview_questions), implicitly distinguishing this aggregator from them, but it never names those siblings or states the distinction 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?

There is no when-to-use guidance: nothing says whether to reach for this aggregate pack versus calling careerproof_match_requirements, careerproof_find_evidence_gaps, and careerproof_generate_interview_questions individually, nor whether a candidate profile must exist first. The only prerequisite information (jobId coming from careerproof_analyse_job_description) 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?

No annotations are provided, so the description carries the full burden. It does disclose a valuable behavioral trait not in the schema: every result carries a confidence tag (verified/inferred/user_claim/missing), which tells the caller how much to trust hits. However, it says nothing about ranking, pagination, result volume, or performance characteristics of a cross-corpus search.

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, zero filler, and the scoping statement (all stored evidence) is front-loaded ahead of the return-value note. Every clause earns its place.

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

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

No output schema exists, and the description usefully covers the return shape (results tagged with confidence levels), which is the main thing an agent needs to interpret output. It is slightly incomplete on the undocumented limit parameter and on how results are ordered when many match, but is otherwise solid for a 3-param search 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 67% – query and projectId are documented in the schema, while limit is not. The description adds no parameter-level detail beyond the schema (no ranking, ordering, or limit defaults), so it neither compensates for the undocumented limit nor enriches the documented ones. Baseline 3 for mid-range coverage 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 ('Free-text search across all stored evidence') and enumerates the searched corpora (commits, PRs, docs, manifests, CV claims, notes), which is far more than a restatement of the name. It does not explicitly distinguish itself from the sibling careerproof_find_evidence_gaps, so an agent must infer the boundary rather than read it.

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

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

The description implies a discovery use case (searching stored evidence) but never states when to reach for this tool versus find_evidence_gaps, match_requirements, or the add_* tools, and gives no exclusions or prerequisites. Usage is inferable from the verb but not spelled out.

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

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

With no annotations, the description carries the full burden. It usefully discloses that matching is re-run (implying recomputation/refresh of prior results) and describes the shape of the return (only failing requirements, each with a suggestion). However, it omits side effects, whether prior results are overwritten, required permissions, or whether a prior analyse_job_description/match_requirements run is mandatory.

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 core action and the distinguishing output scope front-loaded. No filler or redundancy.

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

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

There is no output schema, so the description must explain return values; it does so partially (gaps plus a concrete suggestion for each). But with no annotations and two of three parameters undocumented, the definition stops short of fully equipping an agent to call the tool correctly in all cases.

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

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

Schema description coverage is only 33% — jobId is documented in the schema (and echoed indirectly by 'for a job'), while projectId and candidateId are entirely undocumented in both schema and description. The description adds no meaning beyond the schema and does not compensate for the two unexplained optional parameters.

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

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

The description states a specific verb and resource ('re-runs requirement matching for a job') and precisely narrows the output scope ('only the requirements with weak or unproven support'), which distinguishes it from the sibling careerproof_match_requirements and careerproof_find_evidence without needing to open any schema.

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: the phrase 're-runs requirement matching' suggests this follows a prior analysis and complements match_requirements, but the description never explicitly says when to choose this tool over match_requirements or find_evidence. 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?

With no annotations, the description carries the full burden, and it does disclose a real behavioral trait: questions are biased toward requirements with the weakest evidence. It says nothing about determinism, output format, limits on generation, or whether count is capped at the schema maximum of 30.

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, leading with the action and following with the prioritisation rationale. Slightly dense and lacks any structural separation of purpose vs. behaviour, but every clause earns its place.

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

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

For a simple two-parameter generation tool with no output schema, the description covers what it produces but omits the relationship to prerequisite tools, the meaning of `count`, and any indication of return shape or determinism. Adequate for selection, thin for confident invocation.

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

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

Schema coverage is 50%: jobId has a description pointing at careerproof_analyse_job_description, while `count` (1-30) is undocumented in both schema and description. The description never references either parameter, so it does not compensate for the gap.

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

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

States a specific verb (generates) and resource (interview questions) and adds scope ('from a job's requirements'). It is clearly distinguishable in substance from siblings like careerproof_generate_star_answer or careerproof_score_interview_answer, though it never names or contrasts them.

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. The phrase 'prioritising requirements with the weakest evidence' hints at intent but does not state prerequisites (presumably a prior careerproof_analyse_job_description) or when another sibling should be chosen instead.

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

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

With no annotations, the description carries the full burden and does disclose a meaningful behavioral trait: it 'Never invents narrative detail' and surfaces gaps via 'missing_information.' That is valuable anti-hallucination context. It omits prerequisites (e.g., project must be indexed) and any auth/rate-limit context, 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?

Four compact sentences, front-loaded with what the tool builds, followed by its non-invention guarantee and the downstream handoff. No sentence is 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?

For a generation tool with no output schema, the description usefully names a return field ('missing_information') and the outline structure, which compensates for the absent output schema. It stops short of stating prerequisite state (project indexed, evidence added) that an agent would need to call it successfully.

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 documents all three parameters with clear semantics. The description reinforces the competency/project pairing but adds no syntax or formatting detail beyond the schema, and maximumWords is not addressed in prose. 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 (Builds) and resource (Situation/Task/Action/Result outline), names its inputs (competency, project), and specifies the evidence source (commits, PRs, docs). This clearly distinguishes it from siblings like find_evidence or generate_interview_questions.

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?

Describes the pipeline role explicitly: 'The connected client should turn this outline into flowing prose,' which tells the agent where this tool sits relative to downstream work. However, it does not contrast with siblings like score_interview_answer or find_evidence, so the when-not-to-use case is left implicit.

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, idempotentHint=false, and destructiveHint=false, so the write nature is partly covered structurally. The description adds real context by stating that fetched data is tagged as 'verified' evidence because it is directly observed — a behavioral trait not in the annotations. It does not, however, explain the idempotentHint=false implication (what happens on re-indexing the same repo) or auth requirements beyond 'token-accessible'.

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 that front-load the operation and its scope, then state the evidence-classification consequence. No filler; every sentence carries distinct 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?

There is no output schema, so the description should ideally describe what the call returns or confirms. For a state-mutating index operation with idempotentHint=false and no output schema, the absence of return/re-run behavior leaves a real gap, though the tool's core effect (storing verified evidence) is 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 coverage is 60%; commitLimit and pullRequestLimit have no descriptions. The description's mention of 'recent commits' and 'pull requests' hints that those parameters bound what is retrieved, but it adds no syntax, defaults, or meaning for candidateId and projectName beyond the schema. Baseline 3 is appropriate given partial coverage and only marginal 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?

States a specific verb ('Indexes') and resource ('GitHub repository') and enumerates what is pulled: commits, PRs, README/architecture docs, and dependency manifests. This is clearly distinguishable from sibling tools like analyse_job_description or generate_star_answer, though it doesn't explicitly differentiate itself from careerproof_add_project_evidence, which also writes evidence.

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

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

The description implies the operation by name but gives no explicit when-to-use/when-not guidance and names no alternatives. Given the sibling set includes careerproof_add_project_evidence, an agent has no stated rule for choosing between manual evidence entry and automated repo indexing.

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

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

With no annotations, the description carries the full burden and does well: it discloses the matching scope (all requirements vs all stored evidence), the granularity (per requirement), and the returned match-strength categories plus cited evidence. It does not state that the operation is read-only, whether results are persisted, or the cost of matching against all evidence.

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 that front-loads the action and keeps the return values at the end; every clause earns its place. It borders on run-on but wastes no words.

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

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

No output schema exists, and the description does cover the return shape, which is a plus. However, for a 3-parameter tool with an undocumented candidateId and no annotation coverage, it leaves the filtering semantics and operational side effects (persistence, read-only nature) 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?

Schema coverage is only 67% and the description adds no parameter meaning at all. candidateId is undocumented in both places, and 'all stored evidence' mildly obscures the projectId/candidateId restriction options rather than explaining them.

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: scoring every extracted job requirement against all stored evidence, and it names the output vocabulary (strong/moderate/weak/unproven). This clearly separates it from siblings like careerproof_find_evidence_gaps or careerproof_analyse_job_description, though no sibling is named 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?

The description gives no when-to-use, prerequisite, or alternative guidance. The only pipeline hint (jobId comes from careerproof_analyse_job_description) lives in the schema, not the description. An agent must infer that this is the step after job analysis.

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

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

With no annotations, the description carries the full behavioral burden and does well: it discloses that the check is rule-based/non-LLM, lists what is evaluated, and promises actionable feedback rather than a black-box grade. It does not clarify whether the optional questionId causes the score to be persisted or attached, leaving a side-effect gap.

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

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

The description is two sentences with no wasted words. It front-loads the core check and follows with the return behavior, making it easy for an agent to parse quickly.

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 four parameters, no output schema, and no annotations, the description provides enough context for correct invocation: it explains what is checked and the nature of the returned score and feedback. It stops short of detailing score range, feedback format, or whether the score is persisted when questionId is supplied.

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 75%, and the description adds meaning beyond the schema by clarifying that maximumWords functions as a target word count and that competency drives keyword relevance. The answerText parameter is also directly described as the candidate's practice answer. Only questionId is left to the schema alone.

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 checks a candidate's practice answer, enumerating five concrete dimensions (STAR structure, action verbs, measurable results, length, keyword relevance). It is clearly distinguishable from sibling generation tools like generate_star_answer, but it does not explicitly name or differentiate them.

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

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

The description implies the tool is for evaluating practice answers, but it gives no explicit when-to-use guidance, prerequisites, or alternatives (e.g., when to score versus when to generate a STAR answer). Usage is inferable from the title and first sentence, which meets the minimum viable threshold.

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