TechJobs.vn

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

Beyond the annotations (readOnlyHint=false, destructiveHint=true, idempotentHint=false), the description discloses auth requirements and an important side effect the annotations cannot express: the candidate is notified that a referrer is looking at the request. It does not explain what happens on a conflicting claim or whether the action can be undone, so it stops short of full transparency.

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

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

The prerequisites are front-loaded and every sentence carries information. The teletype fragment style ('Then mark_referral_request_referred once submitted, or release_referral_request / decline_referral_request.') is dense but slightly elliptical, and the trailing sentence listing siblings reads as notes rather than prose.

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

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

With only one well-documented parameter, full annotations, and an output schema, the description covers the remaining gaps an agent needs: auth requirements, the notification side effect, and the correct next step in the referral lifecycle. Only failure/conflict behavior on an already-claimed request is 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 description coverage is 100% and the single parameter already points back to list_referrer_requests, so the schema carries the semantics. The description adds no further detail about the request_id format or validation bounds, which is acceptable at baseline but adds no value.

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 ('Takes an open referral request for the signed-in referrer') and scopes it to the caller's own account, which separates it from read-only siblings like list_referrer_requests. It does not explicitly contrast itself with the other lifecycle tools (release/decline/mark_referred), leaving that differentiation to the follow-up sentence.

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 states the prerequisites (techjobs.vn sign-in plus a verified referrer account) and the condition ('open referral request'), and it names the correct follow-on tools and when to use each. There is no explicit when-not-to-use, but the 'open' qualifier implies the request must be unclaimed, which covers the main misuse case.

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?

Beyond the annotations, it discloses the techjobs.vn sign-in requirement and states that saving again updates the existing answer, which usefully corroborates idempotentHint=true. It does not address the destructiveHint=true flag — nothing in the description explains what could be overwritten or lost — so that annotation remains unexplained.

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

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

Three short sentences, front-loaded with the auth requirement and then the state precondition, with no filler. The phrasing 'For a referral request the signed-in user sent that a referrer already referred (status referred)' is slightly convoluted but still parses correctly.

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, return values need not be described, and the description covers auth, the state precondition, and repeat-save behavior. The one gap is what happens when the precondition is unmet (error vs. silent no-op), which matters for a mutation 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 coverage is 100%, so the schema already carries the parameter definitions and the yes/no meaning of 'answer'. The description still adds value by constraining request_id to a user-owned request in 'referred' status, which the schema does not express.

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 — records whether the company got in touch with the user for a referral request — and scopes it to requests the signed-in user sent that are already in 'referred' status. This distinguishes it from siblings like mark_referral_request_referred or claim_referral_request without needing to open their schemas.

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 gives a clear precondition for use (the request must be one the user sent and already have status 'referred'), which effectively gates invocation. It does not name an alternative tool or say what to do if the request is not yet referred, so the routing guidance is implied rather than explicit.

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

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

Annotations only say the tool is a non-destructive, non-idempotent write, so the description adds real value: authentication is required, there are per-plan quotas, the source CV is left unchanged, and the call returns the copy's content plus a review link. These are exactly the side effects an agent needs before invoking a mutating copy operation.

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 dense but front-loaded: the sign-in precondition comes first, then what gets copied, then follow-up tools. The plan-limit parenthetical is slightly bulky in a single sentence, but nothing is filler and each clause carries instruction value.

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

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

With no output schema, the description still says what comes back (the copy's content and a review link). Combined with the auth gate, quota limits, non-destructiveness of the original, and next-step tool routing, an agent has everything needed to call this correctly and explain the result to a user.

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 each parameter already carries a description including the from_cv_id default (omit to copy the primary CV) and the job_id tailoring behavior. The description restates these at a high level without adding format or edge-case detail, so the schema is doing the heavy lifting and 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 (copies a CV into a new editable CV) plus source options (primary CV or from_cv_id) and scope (optionally tailored to one job). It distinguishes itself from siblings by name: delete_cv_variant, update_cv_variant, and set_primary_cv are all clearly different operations.

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

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

It gives explicit routing: use update_cv_variant to edit the copy afterwards, and set_primary_cv if the user wants it as primary. It also states the precondition (techjobs.vn sign-in) and the practical ceiling (5 CVs on Free, 20 on Pro), which tells an agent when this call will fail or be inappropriate.

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 destructiveHint=true and non-idempotent, so irreversibility is covered structurally. The description adds genuinely new context: sign-in plus a verified referrer account are prerequisites, and the candidate is notified by email with the reason. It stops short of saying whether the decline can be reversed or what state the request ends in.

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

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

Three tight sentences with no filler. Minor structural flaw: the auth prerequisite leads instead of the purpose, so the first thing the agent reads is a constraint rather than what the tool does.

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 annotations carry the safety profile, so the description only needs to supply prerequisites, side effects and sibling routing — which it does. Missing is any note on post-decline request state or whether a released/claimed request can still be declined.

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 request_id and decline_reason are already documented, including the 300-character limit. The description's 'with the reason if one is given' confirms decline_reason is optional and surfaces to the candidate, but that meaning is already in the schema. 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 and resource ('Declines a request') plus the operative condition ('because the candidate is not a fit'), and explicitly names the two siblings it must not be confused with. An agent can route to it without opening the 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?

Gives explicit alternatives with the conditions that select them: request_cv_changes when only the CV is weak, report_referral_request for spam. This is exactly the discrimination an agent needs in a 40+ sibling tool set.

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 destructiveHint=true and idempotentHint=true, and the description goes well beyond them: techjobs.vn sign-in required, deletion is reversible via a 30-day trash window, the first invocation changes nothing, and the primary CV is protected. These are exactly the behavioral facts an agent needs before committing a destructive call.

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

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

Three tight sentences, each carrying new information: precondition, effect/reversibility, and the confirmation protocol. The auth requirement is front-loaded ahead of the destructive semantics, which is slightly less optimal than leading with what the tool does, but nothing is wasted.

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 destructive two-parameter tool with no output schema, the description covers the safety profile, the reversibility window, the confirmation loop, and even what the first (non-committing) call returns. Nothing material is left for the agent to infer.

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 cv_id already documents its source (list_my_cvs), so the baseline is 3. The description adds protocol-level meaning to confirm_delete by explaining it should only be set on a repeated call after user agreement, which reinforces and contextualizes the schema's own note.

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 (delete one of the user's editable CVs) and adds scoping detail: it goes to trash, is restorable for 30 days, and the primary CV is never affected. An agent can distinguish this from update_cv_variant or set_primary_cv without opening either 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?

Explicit trigger condition ('Only when the user asked') plus a concrete two-step protocol: the first call is a no-op that reports what would be removed, then repeat with confirm_delete true after asking the user. That is precise when-to-use guidance with the required prerequisite 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?

Goes beyond the annotations by disclosing an auth prerequisite (sign-in required), the user-visible side effect (notification on new postings), and the repeat-call semantics in plain language. The idempotency statement reinforces the idempotentHint rather than merely restating 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?

Four short sentences with the prerequisite front-loaded, then purpose, then idempotency, then alternatives — an efficient ordering. Every sentence contributes a distinct fact; there is no filler despite the repeated product name.

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 one-parameter mutation with no output schema and rich annotations, the description covers the missing pieces an agent needs: auth requirement, side effect, idempotency, and sibling routing. Nothing material is left to inference.

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 slug field already documents its source and an example, so the schema carries the load. The description's "Find the slug with search_companies" largely duplicates the schema text, adding no new format or validation detail — 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?

Uses a specific verb and resource ("Follows a company for the signed-in user") and immediately states the consequence — notification on new job posts. It is clearly separable from neighbors like get_company (retrieve) and set_role_alert (role-based alerts at any company).

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?

Tells the agent how to obtain the required input (find the slug via search_companies) and routes the adjacent-but-different need to the correct alternative (set_role_alert for role-wide job alerts). It also states the no-op condition for an already-followed company, so the agent knows calling twice is safe.

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, non-destructive and openWorldHint=false, so the safety profile is covered. The description adds what those annotations cannot: a sign-in requirement ('Requires techjobs.vn sign-in') and a data-scope constraint that results come from the user's private tracker rather than aggregate benchmarks. It does not describe response shape or size, which would be the remaining valuable detail.

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-loading the auth prerequisite and the sibling routing is good, but the middle is one long comma-spliced inventory of ten-plus metrics that is hard to scan and mixes distinct concerns (rates, stalled entries, lessons, snapshots). It could be split into a purpose sentence, a scope sentence, and a compact list of returned categories without losing content.

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

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

With no parameters and no output schema, the description carries the burden of telling the agent what comes back, and it does so thoroughly by enumerating the insight categories. The read-only/closed-world behavior is covered by annotations. Completeness would be higher if the enumeration were structured so an agent could match a specific question to a specific returned section.

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

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

The tool takes zero parameters (schema is an empty object with 100% coverage), so there is nothing for the description to disambiguate. Baseline of 4 applies; no parameter-level meaning is needed or missing.

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 the resource precisely (the signed-in user's own Apply Tracker, 'not market benchmarks') and enumerates the subjects returned: funnel and conversion, days per stage, response/interview rates, outcomes, stalled entries, lessons and snapshots. It differentiates itself from list_applications and save_insights_snapshot explicitly. The only weakness is that the verb is implied ('How ... job search is going') rather than stated as a read operation.

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 explicitly routes the agent away from two siblings with conditions attached: 'For the entries themselves use list_applications' and 'to keep today's numbers use save_insights_snapshot'. It also pre-empts a misreading by excluding market benchmarks. It does not cover edge cases such as what happens when the user has no tracked applications, so it stops short of full when/when-not coverage.

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 bar is lower, but the description still adds real interpretive context: the positive TechJobs estimate is from public sources, is explicitly not an official ranking, and a missing label means insufficient public data rather than a negative signal. That caveat prevents an agent from misreading absence as bad news; the only gap is no mention of error behavior for an invalid slug.

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 what the profile contains and ending with the usage recipe; the long field enumeration is dense but each clause maps to actual returned content. The parenthetical caveat is necessary but makes the first sentence a run-on.

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, return format needn't be explained, annotations cover the safety profile, and the single parameter is fully documented and reinforced by the description. Nothing an agent needs to call this correctly is missing.

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 slug parameter already documents its source and an example ('grab'), so the schema does the heavy lifting. The description restates the slug-acquisition route via search_companies, adding workflow framing rather than new meaning, which fits the baseline 3.

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

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

The description names a specific resource (a company's profile) and enumerates exactly what it contains: introduction, industry, size, tech stack, open-job count, referral status, and an optional estimate. It also implicitly separates itself from search_companies (slug lookup) and search_jobs (job listings), so an agent can pick the right tool without opening schemas.

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 an explicit trigger ('Use when the user asks about an employer') plus a two-step routing recipe: obtain the slug via search_companies and enumerate openings via search_jobs (company). Alternatives and their conditions are stated rather than left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world scope, so the safety profile is covered. The description adds genuinely new context: an authentication prerequisite (techjobs.vn sign-in), the exact set of fields returned despite having no output schema, and the guarantee that the shape matches what update_cv_variant accepts. It stops short of describing failure or empty-CV behavior, which keeps it at 4 rather than 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?

Front-loaded with the auth prerequisite, then the resource scope, then the field list, then the workflow instruction — a sensible ordering. The long section enumeration and the closing sentence partially restate the update_cv_variant relationship already implied by "in the shape update_cv_variant takes," so it is slightly longer than strictly necessary.

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 single-parameter, read-only tool with no output schema, the definition supplies everything an agent needs: auth requirement, default target, what comes back, and how the result feeds into update_cv_variant. Adding more would mostly duplicate the schema or the annotations.

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 parameter is already documented as coming from list_my_cvs, so the baseline is 3. The description reinforces the default behavior (omit cv_id to read the primary CV) and frames cv_id as selecting among the user's own CVs, which adds slight clarity about scoping beyond the schema 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?

"Reads the sections of the user's primary CV (or of another of their CVs by cv_id)" gives a specific verb plus resource and states the default scope, which cleanly separates it from list_my_cvs (listing IDs) and update_cv_variant (writing). The enumerated section list further pins down exactly what is retrieved.

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 explicitly prescribes the workflow: read with this tool before rewriting with update_cv_variant, and it names list_my_cvs as the source of cv_id. That is a concrete when-to-use plus a named alternative, so little is left to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's job is to add behavior, which it does: it discloses that only a short summary is returned rather than the full posting, and directs the agent to hand the canonical link to the user. It does not say what happens when the id/url does not resolve, but that is a modest gap given annotation coverage.

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

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

Three short sentences, front-loaded with what is returned, then when to use it, then what to do with the result. 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?

For a simple two-parameter read tool with a full schema and an output schema, the description covers purpose, trigger, and result handling without needing to restate return shapes. Only error/not-found behavior for a bad id or url is left 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 description coverage is 100% and the schema already states "Pass either id or url" for both parameters with an example URL, so the description adds little beyond restating that the id comes from `search_jobs`. Neither source clarifies the implicit requirement that at least one of the two (which are both optional) must be supplied.

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 (fetch one open job) and enumerates the payload returned: a short summary, key skills, and the techjobs.vn link. It names `search_jobs` as the upstream source, so the agent can distinguish it from the sibling that lists jobs.

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 the user wants to know more about a specific job" gives a clear trigger condition and implicitly separates this detail lookup from list/search tools. It also adds a downstream instruction ("Share the link so the user can read the full description and apply"), but names no explicit exclusion or fallback for a missing/invalid id.

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, non-destructive and closed-world, so the safety profile is covered. The description adds useful behavioral context by listing exactly what the response contains (deadlines per cycle, official application link), which helps the agent decide whether this call answers the user's question.

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. The content enumeration is front-loaded and the usage routing follows immediately, so an agent gets purpose and trigger in one pass.

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 fully documented parameter, rich annotations, and an output schema that covers return values, the description needs only to state purpose and usage — both are present. Nothing required to invoke it correctly is missing.

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 slug parameter is documented with a concrete example, so the schema carries the parameter burden. The description only implies the slug's provenance via 'Use after search_programs' and adds no format or constraint detail beyond the schema, 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?

States a specific verb and resource ('Details of one internship, fresher, graduate or scholarship program in Vietnam') and enumerates the content covered: overview, eligibility, benefits, selection process, locations, deadlines, application link. This clearly separates it from the list-style sibling search_programs.

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

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

Explicitly says 'Use after search_programs when the user wants to know more about a program', naming the alternative tool and the condition that selects this one. The sequencing (detail fetch after a search) is unambiguous.

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?

Goes well beyond the annotations by disclosing the return value's nature (short-lived link, immutable snapshot of the CV as sent), the required account state, and a real side effect: opening the link the first time notifies the candidate, without naming the referrer. That side effect is exactly the context an agent needs given readOnlyHint=false, and it is not derivable from the structured fields.

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

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

Three sentences, front-loaded with the access requirements, then the effect, then the caveat about the notification. No filler and nothing repeated from the schema or annotations.

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 single-parameter tool with an output schema and full annotation coverage, the description supplies everything else an agent needs: auth prerequisites, the claim precondition, the transient nature of the link, and the candidate-visible side effect.

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 parameter is described as coming from list_referrer_requests, so the baseline is 3. The description adds a genuine semantic constraint beyond the schema: the request must be one this user has claimed, which narrows valid values in a way the schema does not.

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: returns a short-lived download link to the CV a candidate sent with a referral request, snapshotted at send time. This clearly distinguishes it from get_cv / list_my_cvs, which deal with the user's own CVs rather than a candidate's submitted document.

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 an explicit precondition plus a named sibling to run first ('Only for a request this user claimed (claim_referral_request first)'), and mentions the sign-in / verified-referrer-account requirement. What is missing is any steering away from cases where another tool (e.g. get_cv) would be the right choice, but the exclusions given are concrete.

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/closed-world, so the description doesn't need to re-litigate safety. It earns credit by adding the sign-in prerequisite, the default sort order (most recently updated first), and a sketch of what each entry carries, none of which is in the annotations.

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

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

Two sentences, front-loaded with the auth requirement, then scope, ordering, filtering, and payload in a single flow. The parenthetical field list (source, salary, next step, outcome) is slightly decorative given an output schema exists, but it does not obscure the call decision.

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?

Covers prerequisites, scope, default ordering, optional filtering, and the identity of returned fields, while the output schema handles return-value detail. Nothing needed to call this correctly is missing for a one-optional-parameter read 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 coverage is 100% and the enum is fully self-documenting, so the baseline is 3. The phrase 'optionally only one status' confirms that omitting the parameter returns all statuses, which is marginal added meaning over 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 scoped resource: 'Lists the jobs in the signed-in user's Apply Tracker on techjobs.vn', with parenthetical status examples. This clearly separates it from search_jobs/search_remote_jobs, which surface listings rather than the user's own tracked entries.

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 the use case (reviewing your own tracker, optionally narrowed to one status) and names the siblings that consume the returned id (update_application, log_interview, save_interview_retro). It stops short of an explicit 'use search_jobs instead when...' exclusion, so it is not a full when/when-not statement.

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 and non-destructive behavior, yet the description adds real value on top: a sign-in requirement, the anonymization guarantee (no names or emails), an explicit untrusted-data warning about self-written profile text, and the 1–5 selection constraint. These are exactly the operational facts an agent needs before calling and are not present in structured fields.

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?

Dense and largely front-loaded, with the return shape and the untrusted-data caveat packed into one sentence. Leading with the sign-in prerequisite before stating what the tool does slightly delays the core purpose, but nothing is wasted.

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 single-parameter read tool with an output schema, this is complete: auth requirement, eligibility scope, the shape of returned data (handle, role, team, level, areas), privacy boundaries, and the follow-up action are all covered. An agent needs nothing more to call it correctly.

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

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

Schema coverage is 100% and the single job_id is already documented with its source tools, so the schema does the heavy lifting. The description only indirectly ties job_id to 'the job's company', adding marginal meaning 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?

States a specific verb (lists) and a precisely scoped resource: anonymous profiles of verified referrers at the job's company who are eligible for request_referral. An agent can distinguish it from siblings like get_company or watch_company_referrers without opening 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?

Implies the workflow clearly – this feeds request_referral, and the user must choose 1 to 5 referrers, which is actionable context. It does not explicitly exclude alternatives such as watch_company_referrers or say what to do when no referrers exist, so it falls short of full when/when-not 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 this a safe, idempotent read, so the description focuses on what they cannot express: an authentication prerequisite ('Requires techjobs.vn sign-in') and the fact that results are implicitly scoped to the signed-in user's own tracker. It also discloses the 14-day default window for upcoming_only, which is real behavioral context beyond the annotations.

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

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

Two tight sentences, with the auth prerequisite and the core action front-loaded before the optional filters and the sibling pointer. The parenthetical filter clause is dense but every element 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?

An output schema exists, so return values need no further explanation; the description covers the auth gate, the default scope, both filters, and the write-path alternative. For a 3-parameter read tool with full annotation coverage, nothing an agent needs to call it correctly is missing.

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 baseline is 3, but the description adds the cross-parameter interaction the schema does not spell out: upcoming_only defaults to the next 14 days 'unless days is set.' That linkage is genuine value beyond the per-field descriptions.

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 ('Lists the interview rounds in the signed-in user's Apply Tracker') and enumerates the returned fields (time, format, link, result). It also distinguishes itself from the write sibling by naming log_interview, so an agent can route without opening either 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?

Explicitly frames the two optional scoping modes (per-application via application_id, upcoming-only via upcoming_only with a 14-day default), and points to log_interview as the tool for adding or changing a round. When-to-use and the alternative are both stated rather than 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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new context: a sign-in requirement and the shape of the results (primary CV plus other CVs, each with an open link). It does not discuss result limits or ordering, which is a minor residual gap for a zero-parameter listing.

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 authentication prerequisite and followed by the returned content and the routing guidance. Every clause earns its place; only the repeated site name is slightly redundant.

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 description still usefully summarizes the two CV categories. The one gap is that the relationship to the CV-variant siblings (create_cv_variant, set_primary_cv) is only implicit in "their other CVs", which may leave ambiguity about whether variants appear in this listing.

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

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

The tool takes no parameters, so there is nothing to disambiguate, and the empty schema leaves no gaps. The description correctly spends no words restating parameter details and instead describes the returned entities.

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 ("Lists the signed-in user's CVs") and further specifies the contents: the primary CV and the other CVs, each with an open link. It distinguishes itself from get_cv and score_cv by positioning itself as the enumeration 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?

It states the concrete use case ("Use it to pick a cv_id") and explicitly routes follow-up actions to the right siblings: reading content with get_cv and rating with score_cv. That is a clear when-to-use plus named alternatives, which is what an agent needs to choose this tool over get_cv.

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 closed-world, so the safety profile is covered. The description still adds real context beyond them: authentication requirement, sort order, and the fact that decline reasons and CV feedback are surfaced per request. It stops short of noting result volume or truncation for a list that could grow.

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

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

Three short sentences, each doing distinct work: prerequisite, payload/sort, and sibling disambiguation. The disambiguation is placed last as a natural redirect and nothing is repeated from the annotations.

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 parameters, full annotation coverage and an output schema handling return shape, this description covers everything an agent needs to select and call it. The only gap is guidance on result size or whether the listing is paginated/limited.

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?

Zero parameters, so there is nothing for the description to disambiguate and the baseline applies. It correctly implies the result set is determined entirely by the caller's identity rather than by any 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?

States a specific verb and resource ("Lists the referral requests the signed-in user sent") and pins the scope narrowly to outbound requests, with ordering ("newest first"). It explicitly separates itself from list_referrer_requests, which is the one sibling an agent would plausibly confuse it with.

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 both the prerequisite ("Requires techjobs.vn sign-in") and the routing rule: inbound requests are in list_referrer_requests. An agent can pick between the two list tools without opening either schema.

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 what the annotations cannot: an authentication prerequisite (techjobs.vn sign-in) and the meaning of the returned state fields, including that profile_missing explains what is empty in an incomplete profile.

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 auth requirement is front-loaded in the first sentence, followed by return contents and then the use case. It is dense but every clause carries information. The middle sentence packs many fields, which is slightly heavy but justified by the non-obvious state fields it names.

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 need not document return shape, yet it usefully clarifies the less self-evident fields and the auth prerequisite, and it anchors the tool to register_as_referrer. For a zero-parameter read tool this is close to complete; only explicit exclusion guidance is missing.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain and the baseline of 4 applies. The description correctly spends no space on arguments and instead describes the returned content.

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 specific verb and resource (lists referrer registrations) and scopes it to the signed-in user, then enumerates the exact fields returned (work email, company, verification click, approval, request email destination, profile completeness). It is clearly distinguishable from register_as_referrer, which it references as the write-side counterpart.

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 gives concrete when-to-use guidance: check whether register_as_referrer finished, and do so before asking for requests. That routes the agent relative to two siblings. It stops short of saying when NOT to use it or explicitly naming list_referrer_requests as the alternative, so it falls just short of the top band.

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 a read-only, idempotent, non-destructive, non-open-world operation, and the description adds material context beyond that: the auth/verified-referrer gating, which fields are visible before versus after claim_referral_request, and the fact that candidate name, message and CV text are untrusted third-party data. That last point is a genuine safety signal an agent cannot get from structured fields.

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 first sentence front-loads auth requirements and scope, and the remainder is information-dense with little waste. It is a long, run-on block of sentences where the field-visibility and untrusted-data points could be split more cleanly, and the UI-location sentence is of marginal value, but nothing 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?

The tool has an output schema, so return shape needn't be described, and everything else an agent needs is present: auth gating, default vs filtered behavior, the claim-gated fields, a cross-reference to the sibling for the inverse inbox, and a data-provenance warning. Nothing required for correct invocation is missing.

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 status enum is already fully documented in the schema, including the 'new' = open/unclaimed mapping and the omit-for-full-inbox behavior. The description's mention of 'open requests the candidate chose them for, plus the ones they claimed or handled' reinforces the default but adds no new filter semantics beyond the schema, 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?

States a specific verb and resource (lists referral requests) plus the exact scope: requests candidates sent to the signed-in user as a referrer. It also explicitly separates this from list_referral_requests, which covers requests the user sent as a candidate, so an agent can route between the two without opening a 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?

Names prerequisites (techjobs.vn sign-in, verified referrer account), gives the when-to-use boundary versus the sibling list_referral_requests, and points to claim_referral_request as the follow-up that unlocks candidate identity. It even notes the UI location (Referrer → Request cho bạn), which is unusual but confirms the scope.

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 destructiveHint=true and idempotentHint=true; the description adds real context beyond them — a sign-in requirement, the implicit upsert behavior when the same type and time are submitted twice, and immediate visibility on techjobs.vn. It never spells out which operations are the destructive ones (cancel, clear_fields), but the portmanteau of auth, dedup, and propagation notes is substantive.

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 sentences, each carrying distinct information (auth, add payload, edit modes, dedup, propagation), with no filler. Slightly front-loaded on the sign-in caveat rather than the core action, and the parenthetical field list is dense, but nothing is redundant.

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 14-parameter mutation tool with no output schema, the description covers the create/edit duality, the dedup edge case, auth, and result visibility. It leaves unexplained what happens to unspecified fields on edit (the schema's 'omit to keep' convention carries that) and what a successful call returns, a minor 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%, so the baseline is 3; the description still adds meaning by grouping the fields into an add-payload and by mapping interview_id to the edit modes (mark done/passed/failed, reschedule, cancel). That interpretation of the edit branch is not derivable from the enum descriptions 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?

States a concrete verb and resource — adds an interview round to a tracked application, or edits an existing one when interview_id is supplied — and enumerates the payload (type, date/time, format, link, interviewers, prep notes). This clearly separates it from list_interviews (read) and save_interview_retro (retrospective), so an agent can route without inspecting the 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?

Gives a clear create-vs-edit rule (omit interview_id to add, supply it to edit) and names the sibling that produces that id ("id from list_interviews"). It also describes the dedup rule for repeated type+time. It stops short of an explicit 'use X instead' routing statement against save_interview_retro or update_application.

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 destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description still earns credit by disclosing the auth prerequisites (sign-in plus a verified referrer account) and the external side effect — the candidate is notified to watch their email, which reaches the company. It does not say whether the mark can be undone or what happens if it is called before submission truly occurred.

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, no filler, and the prerequisite is front-loaded before the effect. The first sentence's comma placement ('sign-in, and a verified referrer account') and the fragmentary style of the last sentence are slightly rough, but nothing is redundant.

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 required parameter, an output schema, and full annotation coverage, the description supplies exactly the pieces the structured data cannot: auth requirements, the claim-before-submit precondition, and the candidate-facing notification consequence. Only the irreversibility/error path is left unstated, which is a minor remaining gap for a destructive tool.

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

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

The schema documents request_id at 100% coverage and already points to list_referrer_requests as the source. The description adds a constraint on which request_id is valid ('only for a request this referrer claimed'), which is real meaning beyond the schema, but it adds nothing about type, format, or failure behavior for the parameter.

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 ('marks a claimed request as referred') and then defines what 'referred' actually means — the referral was submitted in the company's own system. That semantic definition is more than the title gives. It stops short of naming the sibling it supersedes (claim_referral_request), but the phrase 'a request this referrer claimed' implicitly scopes it away from the claim 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?

Gives concrete preconditions: sign-in required, verified referrer account required, the request must have been claimed by this referrer, and the submission must have actually happened. That is a clear when-to-use test rather than an implied one. It does not name an alternative for the negative case (e.g., decline_referral_request or report_referral_request when no submission occurred), which is the main gap.

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

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

Annotations already declare readOnlyHint, idempotentHint, closed-world and non-destructive, so the safety profile is covered. The description adds context annotations cannot: a techjobs.vn sign-in prerequisite, a per-account rate limit of 30 matches/day, and confirmation that scoring is rule-based and returns matched vs. missed required skills. Return-shape details are legitimately omitted because an output schema exists.

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

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

Three dense sentences with no filler: prerequisite, what it does and returns, then quota plus sibling routing. The order is logical, though the quota and alternatives are packed into one long clause that an agent must parse rather than skim.

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 one-parameter, read-only scoring tool with an output schema, everything an agent needs is present: auth requirement, quota, score semantics, and explicit disambiguation from the two nearest siblings. Nothing material is left to inference.

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 job_id parameter is already documented as coming from search_jobs, get_job or suggest_jobs_for_me results. The description adds only the implication that the job must be open and that the primary CV (not a variant) is used, so the 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: scores the signed-in user's primary CV against one open job, with a 0–100 rule-based scale and matched/missed required skills as output. It explicitly distinguishes itself from score_cv (rates the CV itself) and suggest_jobs_for_me (finds fitting jobs), so an agent can route correctly without opening 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?

Gives a concrete when-to-use condition ('a job the user names') and names both alternatives with the case each covers. The 30-per-day quota is framed as the reason to be selective, which is usage guidance rather than just trivia.

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

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

Adds substantial context beyond the annotations: authentication is required, a verification link is emailed to the work address, the email domain must match the company, and the user is not a referrer until the link is clicked. This pending-verification state materially changes how an agent should report the outcome, which the destructive/non-idempotent hints alone would not convey.

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 short sentences ordered as prerequisite, trigger, effect, and outcome. No filler, and the sign-in requirement is front-loaded before the behavioral details.

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 description covers auth, side effects, and the activation condition well. It leaves out what happens on repeat registration (the tool is non-idempotent) or if a verification is already pending, which an agent would want to know before retrying.

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 baseline is 3, but the description adds a real constraint not in the schema: the work email domain must belong to the target company. It also frames the email as the user's own work address, reinforcing the schema's 'not Gmail/Yahoo' note.

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 ('Registers the signed-in user as a referrer for the company') and scopes it to a single company. Among siblings such as update_referrer_profile, set_referrer_availability, and list_referrer_registrations, this is clearly the one-time onboarding action, so an agent can select it without opening schemas.

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 an explicit trigger ('Use when the user says they work at a company and want to refer candidates') plus a precondition (techjobs.vn sign-in). It does not name a sibling to use instead when the user is already registered or wants to change availability, so it stops short of full when/when-not 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 destructiveHint=true and idempotentHint=false, but the description adds the concrete consequences: an auth gate (techjobs.vn sign-in plus verified referrer account) and the fact that the request becomes visible to every referrer at the company, not just the caller. It stops short of saying whether the action can be undone or whether the request can be re-claimed, which is the remaining 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?

Two sentences, no filler, each doing distinct work (prerequisites, effect, then routing to alternatives). The ordering puts auth prerequisites ahead of the action, which is slightly less front-loaded than leading with the effect, but nothing is wasted.

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 description covers prerequisites, the state change, and the alternative. For a destructive single-parameter mutation this is nearly complete, missing only reversibility and whether the candidate is notified.

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 parameter already carries a description pointing at list_referrer_requests as the source of the id. The description adds nothing about the parameter, so baseline 3 applies.

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

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

States a concrete verb and effect: gives a claimed request 'back to the open pool for every referrer at the company.' The resource and the scope of the state change are both explicit, and the contrast with decline_referral_request makes it separable from the nearest 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?

Explicit when-to-use ('when a colleague could refer instead') and an explicit named alternative with its own condition ('use decline_referral_request when the candidate is not a fit'). The routing decision between the two tools is fully specified.

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?

Goes well beyond the annotations: it discloses that the request is removed from the user's inbox, that block additionally prevents the candidate from choosing the user, that the candidate is never notified, and that auth plus a verified referrer account are required. The silent-notification and inbox-removal consequences are exactly the kind of irreversible side effects an agent needs before firing a destructiveHint=true call.

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?

Information-dense with no filler: preconditions lead, then the action and its effects, then the scope limit and the confirm-first rule. The confirmation requirement is a safety-critical instruction buried in the final clause, and the block consequence is folded into a semicolon chain, which slightly hurts scanability.

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 description covers everything else a four-parameter mutation needs: auth requirements, the destructive consequences, the silent-notification behavior, and the valid input source. Nothing essential to a correct first invocation is missing.

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 baseline is 3, but the description adds real meaning for 'block' by framing it as the candidate being unable to choose the user, complementing the schema's wording about the referrer card and other open requests disappearing. The reason enum is restated rather than expanded, and note/request_id are left entirely to the schema, so it does not fully compensate for zero description-level coverage of those two.

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?

Uses a specific verb (reports) against a specific resource (a referral request) and immediately names the four reason categories and the two effects (removal from inbox, optional blocking). An agent can distinguish this from decline_referral_request or release_referral_request without opening the schema, because the description ties it to reporting to the techjobs.vn team.

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 prerequisites (sign-in, verified referrer account) and a clear scope restriction: 'Only for requests list_referrer_requests shows,' plus an explicit procedural instruction to ask the user to confirm first. It stops short of naming the adjacent sibling (decline_referral_request) and stating when to decline instead of report, which is the one remaining ambiguity for an agent picking among referral-request actions.

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 destructiveHint=true, idempotentHint=false and openWorldHint=true; the description adds real value beyond them by stating the auth prerequisites (sign-in plus verified referrer account), that the candidate is notified with the supplied tags and note, and that they can send a corrected CV back. It does not spell out what state is destroyed by the destructive hint or whether the request can be re-requested, which keeps it short of 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 short sentences with no filler; prerequisites, effect, and the sibling routing rule are all stated compactly. Leading with the auth requirement rather than the action is a minor structural weakness, but nothing is wasted.

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, return values need no explanation, and the description covers preconditions, side effects (notification to candidate) and the alternative tool. The only gap is the unresolved consequence for the referral request itself when the candidate is asked to fix their CV.

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 each parameter is documented inline, so the baseline is 3. The description only adds that the tags and note are delivered to the candidate, which is mild added meaning rather than syntax or constraint detail.

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?

"Asks the candidate to fix their CV" is a specific verb+resource, and the description names the sibling it replaces (decline_referral_request), so an agent can distinguish it. The phrase "before the request goes on" is slightly opaque about the request's resulting state, which keeps 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?

Explicit routing rule: "Use it instead of decline_referral_request when the candidate fits but the CV does not show it." This names the alternative tool and the exact condition that selects it, leaving nothing to inference.

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

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

Goes well beyond the annotations by disclosing sign-in requirement, per-week rate limit, that only chosen referrers receive it with first-to-take ownership, that a sent request reaches real people and cannot be undone, and that the unconfirmed call sends nothing. These are exactly the operational facts an agent needs given destructiveHint=true and idempotentHint=false.

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?

Dense but front-loaded: sign-in and the core action come first, then the fallback, then the two-step confirmation, then the irreversibility and rate-limit warnings. No filler sentences, though the long compound middle sentences slow scanning 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 destructive, non-idempotent, open-world mutation with an output schema, it covers auth, flow, failure fallback and irreversibility. The only omission is the behavioral consequence of share_outcome (that the referrer is later told about progress), which is described only inside the schema property.

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 already 100%, so the baseline is 3, but the description adds real meaning: the 1-to-5 referrer cap and first-taker semantics, the omission rule for referrer_handles, and the rule that confirm_token must be reused with identical job_id, message and referrer_handles. share_outcome is left entirely to the schema, which keeps this from a 5.

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 ('Asks the referrers ... to refer the signed-in user') with concrete scope: chosen referrers at the job's company, CV plus message attached. It also names the sibling it depends on (list_company_referrers), so the agent can distinguish it from claim_referral_request or list_referral_requests without opening schemas.

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?

Explicit when-to-use and when-not-to: call with referrer_handles normally, omit them only when list_company_referrers returns nobody so the request joins the waiting list. It also mandates the preview-then-confirm sequence and the condition that the user must explicitly agree before the second call.

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?

Beyond annotations it discloses the two facts that matter most for a write tool: an authentication requirement (techjobs.vn sign-in) and that the action sends an external email to real referrers, which cannot be recalled. It does not explain why destructiveHint is true or what state changes alongside the email, leaving some of the mutation's consequences to inference.

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

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

Three short sentences, with the auth and status preconditions front-loaded before the action, and the email side effect called out last. The colon-separated construction in the middle sentence is slightly dense but no sentence is wasted.

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 one-parameter, single-action tool with an output schema, the description covers authentication, ownership, required status, the exact payload sent, and the external-email side effect — everything needed to call it correctly. Only the precise state transition after success (and any rate limits on notifying referrers) is left out.

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 parameter already documents that the id must come from list_referral_requests. The description reinforces ownership and the needs_changes precondition but adds no new identifier format or lookup guidance, so it matches the baseline 3.

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

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

States a concrete verb (sends/resubmits) and specific resource (the user's current primary CV, CV chính) to a specific audience (the referrers at the company), gated on a named request status (needs_changes). That is far more specific than the title alone, though it never names an alternative sibling such as confirm_referral_contact or mark_referral_request_referred, so sibling differentiation is only implicit via the status gate.

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 a clear applicability condition: the request must be one the signed-in user sent and a referrer must have asked to change it, with status needs_changes. It does not state what to do instead when the status is something else (e.g., use confirm_referral_contact or report_referral_request), so there are no explicit exclusions or alternatives.

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

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

Annotations already declare readOnly=false, idempotent=true, destructive=false and openWorld=false, and the description reinforces this consistently with the no-change-no-op rule. It adds real value beyond the annotations: a sign-in requirement, a hard quota of 50 per user, and where saved snapshots appear in the UI. What it omits is the failure behavior at the 50 cap and what the call 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?

Four short sentences, front-loaded with the auth precondition, then purpose, then dedupe caveat, then quota. Every sentence carries information; only the parenthetical UI reference is slightly incidental.

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 zero-required-param write tool with no output schema, the definition covers auth, side effect, dedupe semantics and a quota. The remaining unknowns (behavior when the cap is hit, and whether the response includes the snapshot identifier) are minor but real for a tool whose users will want to reference the snapshot later.

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 optional 'label' parameter already has a description with an example and maxLength, so the description needs to carry no parameter burden. It adds no meaning beyond the schema, which is the expected baseline here.

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: saving the current state of the signed-in user's application funnel, plus the reason (compare response/interview rates over time) and where it surfaces (Apply Tracker flow chart). It is clearly distinct from read-side siblings like get_application_insights, 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?

Gives clear context for when to call (to establish a comparison point across time) and a useful when-not rule: saving again with no changes since the latest snapshot adds nothing. It does not explicitly route the agent to get_application_insights for reading snapshots back, which is the one obvious gap.

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

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

Annotations already declare readOnly=false, destructive=true and idempotent=true, and the description adds real substance on top: one entry per round, re-saving updates rather than duplicates, and only passed fields change. It stops short of stating that removals via clear_fields or tags replacement are irreversible, which matters given destructiveHint=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?

Four tight sentences: prerequisite, purpose, update semantics, sibling routing. Front-loaded with the gating requirement and no filler or repetition 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?

For a 12-parameter mutation tool with rich annotations, the description covers auth, upsert behavior, partial updates and sibling routing, which is most of what an agent needs. With no output schema, it could still say what the call returns or whether the saved entry is echoed back.

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 per-field meaning (omit to keep, empty string clears, tags replace, clear_fields by name) is already fully documented in the schema. The description reinforces the partial-update model and the round-vs-application distinction for interview_id, but adds little beyond what the schema already says.

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 ("Records the user's lessons learned for an interview round, or for a whole application") and enumerates the content captured (questions, went well, improve, red flags, next prep, confidence, tags). It also explicitly separates itself from log_interview, so an agent can route correctly without opening either 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?

Gives an explicit when/when-not split: record reflections here, while "the round's time and result belong in log_interview." It also states the sign-in prerequisite up front, so the agent knows the call is user-scoped.

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 a closed-world, non-destructive profile, so the safety bar is low. The description adds genuinely useful context beyond them: the authentication requirement, the fact that scoring is deterministic fixed-rule (no AI) rather than model-generated, and the shape of the result including an edit link.

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 most important gating fact (sign-in required) and then covers scope and outputs. It is efficient, though the long clause chain makes it slightly harder to scan than a two-sentence split would be.

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 further explanation, and the description still summarizes them usefully. Auth, default scope, and determinism are all covered; the only minor gap is failure behavior (e.g., unauthenticated or user with no CV), which is not described.

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 cv_id schema entry already explains that omitting it scores the primary CV and that ids come from list_my_cvs. The description restates the same default behavior without adding format or constraint detail, so it sits at the baseline for a fully documented single parameter.

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 specific verb and resource (score the signed-in user's CV), states the score range and the fact that it uses fixed rules rather than AI, and enumerates the outputs (per-criterion score, suggestions, edit link). It is clearly distinguishable from siblings like get_cv (retrieval) and match_cv (job matching).

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 establishes the usage context: sign-in is required, and the tool defaults to the primary CV unless a cv_id for another of the user's CVs is supplied. It does not explicitly state when to prefer this over match_cv or get_application_insights, so the routing guidance is contextual rather than exhaustive.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's job is to add context — and it does, disclosing that results carry open-job counts and referrers. It stops short of mentioning the unauthenticated page/limit caps, though the schema carries those.

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: the capability and its return fields come first, the routing advice second. No filler, and the most decision-relevant information is front-loaded.

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

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

For a read-only search with rich annotations, a fully described 3-parameter schema, and an output schema, the description supplies exactly the missing pieces: what the results contain and how this tool chains into get_company and search_jobs. Nothing an agent needs to call it correctly is absent.

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 page, limit, and query are already fully documented, including the omit-to-list-most-jobs behavior. The description only restates that matching is by name, and is actually slightly narrower than the schema, which also matches on slug — so it adds no meaning 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 names a specific verb and resource ('Find companies tracked by techjobs.vn by name') and adds scope detail ('with their number of open jobs and referrers') that separates it from generic listing tools. It also contrasts itself with get_company and search_jobs, so an agent can place it among siblings without opening 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?

It states an explicit workflow: use this to look up a company's slug, then call get_company for the profile or search_jobs for its jobs. That is a when-to-use plus two named alternatives with their conditions, leaving nothing to inference.

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

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

Annotations already declare this a safe, idempotent, read-only lookup, so the bar is lower. The description still adds real behavior beyond them: results are refreshed hourly, ranked by best match with newest first, and each carries a shareable techjobs.vn link — the ranking order and shareability are not derivable from the annotations.

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

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

Three tight sentences: what it is, when to use it, what comes back. Purpose and trigger are front-loaded and 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?

With nine all-optional parameters, full schema documentation, an output schema and complete annotations, the description covers the essentials an agent needs to call it. The one gap is that the anonymous-vs-signed-in limits (page 3 / 10 vs 50 results) live only in the schema and are not surfaced as behavioral context.

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

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

Schema description coverage is 100%, including enum explanations, so the schema carries the parameter burden and a 3 baseline applies. The description only restates the filter facets generically ('by role, skill, seniority, city or company') without adding syntax or matching semantics beyond what each property already documents.

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 ('Search open tech jobs at companies hiring in Vietnam') plus the data source and refresh cadence. Scope facets (role, skill, seniority, city, company) reinforce it, but the description never distinguishes it from overlapping siblings such as search_remote_jobs or suggest_jobs_for_me.

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 the user looks for jobs by role, skill, seniority, city or company' gives a clear trigger condition tied to concrete user intents. It offers no exclusions or named alternatives, so an agent must infer on its own when search_remote_jobs or suggest_jobs_for_me would be a better pick.

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, closed-world, non-destructive behavior, so the description only needs to add operational context. It does so with the ordering rule ('Open programs come first, soonest deadline first'), which tells the agent how to interpret the first results. Pagination/sign-in limits are covered only by the schema, so not a full 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?

Three sentences ordered by importance: what is found, how results are sorted, then when to use it versus siblings. No filler and no repetition of schema detail.

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-shape explanation is unnecessary, and the description covers scope, ordering, and follow-up tool. It is nearly complete; only the unmentioned 'ambassador' type and pagination/sign-in ceilings beyond the schema are minor 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 100%, so the schema already documents every parameter including the three enums. The description adds some framing ('whether applications are open, the deadline and the career field') that maps to status and field, but it omits the 'ambassador' program type present in the enum and says nothing about the query or page/limit parameters. 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?

Opens with a specific verb and resource ('Find internship, fresher, graduate, management-trainee and scholarship programs') and pins the scope (students/new grads, Vietnam, tech and other fields). An agent can distinguish this from search_jobs and get_program from the description 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?

Explicit routing: 'Use when a student asks about internships or programs; for individual job postings use search_jobs. Then get_program for one program's details.' It names both the trigger and the two relevant alternatives with their selection conditions.

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 closed-world, so the safety profile is covered. The description adds genuine context beyond that: the upstream source and the non-obvious default filter that silently excludes country-restricted postings unless open_to_vietnam is false. It does not mention auth or the unauthenticated result caps, but the schema parameters already state those.

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, zero filler. The behavioral scope is front-loaded and the disambiguation to search_jobs comes second, which is the right order for an agent deciding whether to call this at all.

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 rich annotations, the description does not need to explain return values, and it correctly focuses on scope and routing. The only small gap is that it never states how results relate to search_jobs (overlap or exclusivity), which an agent picking between the two might wonder about.

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 page, limit, query, role and open_to_vietnam are all documented in the schema. The description's scope sentence about Vietnam-eligibility merely echoes what open_to_vietnam already explains, adding no new syntax or format guidance. Baseline 3 applies when the schema carries the semantics.

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 (remote roles at foreign companies) and pins the exact source (techjobs.vn /remote). It also clarifies the default scope constraint (only those someone living in Vietnam can take), which distinguishes it from the sibling search_jobs without opening either 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?

Explicitly routes the agent: 'For companies hiring in Vietnam use search_jobs.' That names the primary alternative and the condition that selects it. It stops short of covering other nearby siblings such as suggest_jobs_for_me or search_companies, so it is clear but not exhaustive.

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 flag destructiveHint=true and idempotentHint=true, but the description adds what the annotations cannot: the existing primary CV file is replaced and not kept, sign-in to techjobs.vn is required, and the first call in the replace case is a silent dry-run. That is exactly the behavioral context an agent needs before a destructive write.

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 sentences, front-loaded with the auth prerequisite and the destructive consequence before the procedural detail. No filler and no repetition 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?

For a two-parameter destructive mutation with no output schema, the description covers auth, data loss, the dry-run return behavior, and the confirmation loop. Nothing an agent needs in order to call it safely is missing.

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 baseline is 3, but the description adds the sequencing that gives confirm_replace its meaning (dry-run first, then repeat with true) and constrains cv_id to editable CVs. It stops short of restating the source tools for cv_id, which the schema already names.

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 ("Makes one of the user's editable CVs their primary CV") plus the domain gloss "CV chính, used for matching and referrals", which separates it from update_cv_variant and create_cv_variant in the sibling list. An agent can identify the tool without opening the 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?

Gives an explicit gate ("call it only when the user asked") and a concrete two-step protocol: if a primary CV exists, the first call is a no-op that reports what would be replaced, then repeat with confirm_replace true after asking the user. This is when-to-use and when-not-to-proceed guidance rather than inference.

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

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

Annotations establish the safety profile (not read-only, idempotent, non-destructive), and the description adds real context beyond them: candidates stop seeing the profile while paused, and already-taken requests are retained regardless. It does not mention response shape, but an output schema exists so that burden is reduced.

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

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

Three tight sentences with no filler, leading with the authentication prerequisite and then the two effects. Slightly better if the auth sentence were not first, but overall well front-loaded.

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

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

For a 3-required-parameter mutation with an output schema and good annotations, the description covers prerequisites, both operations, visibility side effects, and retention of existing claims. An agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds meaning beyond it by clarifying that the cap counts requests 'taken, not finished' — i.e., lowering the cap does not drop in-flight claims ('requests already taken are kept either way'). That behavioral nuance is not expressed in 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 specific verbs (pause/resume, set a cap) on a specific resource (one of the user's referrer registrations), and the title-level framing 'cap how many I hold' is restated concretely. It is clearly separable from siblings such as update_referrer_profile, set_referrer_email_notifications, and register_as_referrer.

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 clear context: requires sign-in, and operates on one registration identified via list_referrer_registrations. It does not explicitly name an alternative tool or state when-not to use it (e.g., versus update_referrer_profile), so it stops short of 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, destructiveHint=false, idempotentHint=true, and openWorldHint=false; the description adds the auth requirement and that the operation targets exactly one registration. The restated idempotency sentence partly duplicates the annotation but spells out its practical meaning. It does not mention error behavior for a stale or invalid registration id, which is the main remaining 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?

Front-loads the auth prerequisite, then the core action, then the optional digest modifier — a sensible order with no filler. The closing idempotency sentence is slightly redundant given the annotation, but it is short and clarifies behavior rather than padding.

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, full parameter coverage, and rich annotations, the definition covers nearly everything an agent needs to invoke it correctly. Only the failure/validation path for a bad registration_id and the effect on already-queued emails are left implicit.

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%, including the 'omit to keep' semantics for daily_digest and the origin of registration_id, so the schema already does the heavy lifting. The description restates the account-vs-work-email meaning at a high level without adding format or edge-case detail beyond the schema. 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 precise verb ('chooses') and a scoped resource ('new referral request emails' for 'one of the user's referrer registrations'), and enumerates the two choices: account vs work email and per-request vs daily digest. An agent can distinguish this from siblings like set_referrer_availability or update_referrer_profile without opening the 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?

States a clear prerequisite ('Requires techjobs.vn sign-in') and clarifies repeat-call behavior ('Calling it again with the same values changes nothing'), which tells the agent it is safe to re-invoke. It stops short of explicit when-not guidance or naming alternatives for other referrer settings, which siblings cover.

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?

Goes beyond the annotations by explaining exactly what the destructiveHint destroys — 'calling it for a role that already has one replaces its filters' — and confirms idempotentHint with 'the same call twice changes nothing'. It also discloses the auth requirement and the side effect (techjobs.vn emails a digest), which annotations cannot convey.

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

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

Three tight sentences ordered by importance: precondition, effect, then the replace/idempotent rule. Every clause carries operational information and none is redundant.

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 4-parameter, enum-driven mutation with no output schema, the description covers auth, what is created, what is overwritten, and idempotency. An agent has everything needed to decide whether and how to call 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 description coverage is 100%, so the schema already documents every parameter, enum, and default. The description only adds that matching jobs arrive as a digest, which lightly informs cadence, but it does not explain defaults or enum mapping beyond what the schema states.

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 ('Sets the signed-in user's alert for new jobs in a role') and immediately scopes it with 'optionally filtered by seniority and city' plus the digest delivery mechanism. Nothing in the sibling list offers role alerts, so the tool is distinguishable without reading the 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?

Gives the precondition explicitly ('Requires techjobs.vn sign-in') and clarifies the replacement/idempotency semantics an agent needs before calling. It does not point to a sibling for adjacent intents (e.g. follow_company or track_job), so a small routing gap remains.

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 closed-world, so the safety profile is covered. The description adds meaningful behavior beyond that: an auth requirement, result ordering ('best fit first'), the scoring scale, and parity with the website's for-you ranking.

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. Leading with the sign-in prerequisite is defensible, though it slightly delays the core purpose statement; the trailing website-parity clause is useful but marginally redundant.

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 a single optional parameter, full schema coverage, an output schema, and rich annotations, the description supplies everything else an agent needs: auth requirement, ranking semantics, and what each result contains. Nothing material is missing.

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 'limit' parameter is fully documented in the schema with default and max. The description adds no parameter meaning, 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 and resource ('Suggests open jobs') plus the exact input basis ('fit the signed-in user's primary CV') and output shape ('0–100 fit score and a techjobs.vn link'). This is clearly distinguishable from search_jobs (query-driven) and match_cv (CV-to-job scoring) in the sibling list.

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 concrete precondition ('Requires techjobs.vn sign-in') and implies the use case: personalized, ranking-based recommendations tied to the primary CV. It does not explicitly say when to prefer this over search_jobs or match_cv, so it stops short of full when/when-not 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?

Beyond the annotations it adds two real pieces of context: a sign-in requirement and immediate propagation ('the change shows on techjobs.vn right away'). The idempotency sentence just restates idempotentHint=true, and it never explains the destructiveHint=true flag (e.g. that adding an entry creates persistent tracker state), so the safety profile is not fully illuminated.

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-loads the auth prerequisite, then purpose, then persistence behavior, then the sibling alternative — a sensible order. One sentence ('Calling it again with the same arguments changes nothing') merely echoes idempotentHint and could be cut without losing 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?

For a 19-parameter upsert with no output schema, the description covers auth, create-vs-status-change, idempotency, immediate effect, and the correct alternative tool. It is only slightly short on explaining the destructive flag and whether partial updates merge into an existing entry versus creating 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 schema already documents every one of the 19 parameters, including the omit-to-keep and clear_fields conventions. The description only loosely groups the optional fields ('a note and tracker details (source, salary, next step, outcome reason)'), adding little beyond the schema baseline.

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 specific verb and resource ('Adds a techjobs.vn job to the signed-in user's Apply Tracker or moves it to another status') and immediately contrasts with the sibling update_application for id-based edits. An agent can distinguish it from update_application and list_applications without opening a 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?

It gives a concrete routing rule: use this tool to add a job or change status, and use update_application to edit an entry by id (including hand-added jobs). That is clear context plus one explicit alternative, though it does not spell out the inverse condition (when this tool is the wrong choice for an already-tracked application).

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 the write/destructive/idempotent/local profile, and the description adds two pieces of context the annotations cannot: a sign-in requirement and the patch semantics ('Only the fields you pass change'), which substantiates the idempotentHint. It does not say what happens on invalid status transitions or whether edits are recoverable, which would have pushed this higher.

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-loads the auth prerequisite, then the action, then the routing hint — good ordering in three sentences. The parenthetical enumeration of tracker details is long and duplicates the schema's property list, costing some tightness.

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 19-parameter mutation with no output schema, the description covers the essentials: auth, id provenance, partial-update behavior, and the simpler sibling. It leaves out outcome-shaped constraints (e.g. whether status can move anywhere, what a successful update returns) but nothing that would cause a misinvocation.

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 every parameter already documents its own omit-to-keep and clearing behavior, so the schema carries most of the burden. The description's field enumeration and the 'only fields you pass change' rule restate what the schema already says per-property; it adds no extra syntax or edge-case guidance (e.g. clearing via clear_fields vs empty string).

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 ('Edits one entry of the signed-in user's Apply Tracker by its id') and enumerates the editable field families, so the agent knows exactly what is mutated. It also explicitly separates itself from track_job (add a job / status-only moves) and list_applications (id source).

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 explicit when-to-use routing: take the id from list_applications, and use track_job instead if the goal is adding a job or only changing status. This is a real alternative-plus-condition statement, not just implied context.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, and the description adds the nuance that matters: sections supplied replace their section while "the rest stays," which prevents overestimating the destructive scope. It also discloses the auth requirement and that a review link is returned, adding context beyond the structured hints.

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 the auth requirement, then purpose, then replacement semantics, then out-of-scope tool, then return value — all in four dense sentences with no filler. The single-paragraph packing of the section list makes it slightly less scannable, but nothing is wasted.

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 nested-object mutation tool with no output schema, the description covers auth, replacement scope, sibling routing, the primary-CV exclusion, and the return value (a review link). Nothing an agent needs in order to call it correctly is missing.

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 baseline is 3; the description adds the omit-to-keep contract and enumerates the sections that can be replaced (headline, summary, experience, projects, skills, and "other sections"), which is the key semantic an agent needs when composing a partial update. It does not detail field-level constraints, but those are fully documented in 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: "Saves new content into one of the user's editable CVs." It immediately scopes the objects it can touch (CVs made with create_cv_variant) and names the neighboring tools create_cv_variant and set_primary_cv, so the agent can distinguish it from its siblings without reading schemas.

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

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

Explicitly routes the agent: creation belongs to create_cv_variant, and the primary CV (CV chính) is out of scope with a pointer to set_primary_cv. It also states the prerequisite (techjobs.vn sign-in), so the when-to-use and when-not-to-use conditions are both covered.

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?

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description discloses auth requirements, privacy behavior (name/email never surfaced), content validation that refuses emails, phone numbers, links and @handles, and the crucial full-replacement semantics of omitted fields. The replace behavior is exactly the kind of trait annotations do not cover.

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 sentences, front-loaded with the sign-in prerequisite and the high-risk replace rule, with no filler. The privacy/validation sentence is longer but carries genuine behavioral 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?

For a 5-parameter mutation with an output schema (so return values need not be explained), the description covers auth, replacement semantics, privacy and validation. Minor gaps remain, such as ownership checks on registration_id and error behavior, but nothing essential is missing.

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 80%, so baseline is 3, but the description adds meaning the schema does not: the fields are the anonymous profile candidates see, and omitted fields are cleared rather than left unchanged. It does not add per-parameter detail beyond the schema, which is why it stops at 4.

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 specific verb ('Saves') and resource ('the anonymous referrer profile candidates see') and enumerates the fields it controls (role, team, level, role areas). This clearly separates it from sibling tools like update_cv_variant or set_referrer_availability without needing to open a 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?

It states a prerequisite ('Requires techjobs.vn sign-in') and a critical usage rule ('Omitted fields are cleared, so send the whole profile'), which tells the agent how to call it correctly. It does not explicitly compare against siblings or say when not to use it, keeping it 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 idempotentHint=true and destructiveHint=false; the description adds context they cannot express: sign-in is required, the notification fires once and only in-app, there is a 20-company cap, and repeats are no-ops. That is substantive behavioral disclosure beyond structured fields.

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-loads the auth requirement, then the trigger condition, then the stop mechanism. Dense but every clause carries information; the nested parenthetical around list_company_referrers makes one sentence slightly harder to scan than necessary.

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 it covers auth, scope, limits, and reversibility. Only gap: what happens if the company already has a referrer (error vs. silent no-op) is left implicit.

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 already spells out both slug's source and watch's true/false meaning, so the description mostly restates rather than extends it. The added nuance (watch=false stops an existing watch, 20-company ceiling) is minor.

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 action (register a watch) on a specific resource (a company's referrers) and anchors it to the sibling list_company_referrers as the precondition. An agent can distinguish this from list_company_referrers or follow_company without opening a 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?

Explicit when-to-use ('For a company with no referrer yet (list_company_referrers returned nobody)'), explicit when-to-stop ('Pass watch=false to stop'), plus a stated capacity limit of 20 companies. Alternatives and exclusions are named, not inferred.

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