GigHQ.ai

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

Annotations already declare a non-destructive, closed-world write, so the description focuses on the useful extra context: `experience_id` is optional but degrades downstream resume/interview utility, and `type` defaults to 1. It also gates the call on collecting all four STAR parts first. It does not discuss duplicate entries or validation failures, but the output schema covers the response shape.

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

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

The purpose and routing tip are front-loaded and well-structured, but a substantial portion restates the schema verbatim — the four entry types, the three-number metrics definition, and the STAR format all already appear in the field descriptions. The STAR/Result guidance is also long enough that an agent may skim past the actionable routing tip.

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 7-parameter write tool in a multi-step career-journaling workflow, this covers everything the agent needs: entry-type taxonomy, the role-confirmation prerequisite, content-quality requirements per type, follow-up routing to update_career_entry, and reliance on the output schema for return values.

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 3 is the baseline, but the description earns more: it explains why `experience_id` matters downstream rather than just what it is, and specifies that Result quantification should be mirrored into `metrics` rather than buried in `description`. The STAR-in-`description` requirement and the note that `metrics` is omittable for skill/reflection types add real semantic guidance.

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 ('Saves a new career journal entry to the user's GigHQ profile') and immediately scopes the content domain (achievements, projects, skills, reflections tied to a role). That framing separates it cleanly from update_career_entry, list_career_entries, and the job-application note siblings without needing 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?

Explicitly states when to use it, then adds a concrete prerequisite workflow: if no role is specified, call `list_experiences` first, present options, and confirm the ID. It also names `update_career_entry` as the follow-up path when Result numbers are unavailable, which is exactly the alternative-routing an agent needs.

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, and openWorldHint=false, so the write-but-non-destructive profile is covered. The description adds the useful behavioral fact that the entry surfaces in the contact's interaction timeline in GigHQ. It says nothing about permissions, duplicate handling, or failure modes, so with annotations carrying the safety load a 3 is appropriate.

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

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

The core action and the required-field warning are front-loaded, and the enum bullet list is long but each line earns its place by disambiguating a value. Slightly verbose formatting, but no filler sentences.

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 full schema coverage, annotations covering the safety profile, and an output schema, the description supplies everything else the agent needs: what qualifies as an interaction, how to pick the type, and how to obtain the required contact UUID.

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%, which sets a baseline of 3, but the description goes beyond the schema's one-line enum description by defining each of the ten `type` values with a concrete meaning. That materially improves correct enum selection. `body`, `occurred_at`, and `contact_id` are left to the schema, which documents them adequately.

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 ("Logs a touchpoint with one of the user's job-search contacts") and lists concrete examples of what counts. It also distinguishes itself from search_contacts, which is the lookup tool, so an agent can tell what this tool does versus its 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?

Explicitly routes the agent to `search_contacts` to obtain the contact UUID and instructs it to infer the best-fit `type` from what happened, which is the main ambiguity for this tool. It lacks an explicit when-not-to-use statement, so it falls short of a 5.

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

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

Annotations already establish this is a non-destructive write (readOnlyHint=false, destructiveHint=false, openWorldHint=false). The description adds real behavioral context beyond that: notes are appended to a timeline, category must be inferred from content, and ambiguous cases require user confirmation. It does not mention auth, rate limits, or what a failed/invalid category returns, so it stops 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?

Purpose and the critical 'category is required' constraint are front-loaded, and the bulleted mapping is functional rather than filler. The list is long, but each entry earns its place by disambiguating otherwise adjacent categories; only the final sibling-tool pointer feels slightly like an appendix.

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 described. With three required parameters fully covered, the category taxonomy supplied in prose, and the prerequisite lookup tools named, an agent has everything it needs to invoke this correctly on the first attempt.

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 a baseline of 3 would apply — but the description is the sole source of the category taxonomy, enumerating all ten accepted slugs with definitions and an 'other' fallback. Without this text the agent could not reliably populate the category field, so the description contributes meaning far 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 and resource ('Adds a note to a job application's timeline') and gives concrete examples of what counts as a note. It does not explicitly distinguish itself from the sibling add_contact_interaction, which appears to overlap in purpose, so an agent still has to infer when a touchpoint belongs to an application timeline versus a contact record.

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 what to use it for ('log any touchpoint or interaction'), provides a full category decision map, and specifies the escalation path when category is ambiguous — ask the user before calling. It also names the sibling tools (get_recent_applications, search_job_applications) needed to obtain the required application_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=true, destructiveHint=false and closed-world scope, so the safety profile is covered. The description adds something annotations cannot: that the tool computes a per-application follow-up suggestion, meaning it returns derived analysis rather than raw rows. It does not say what happens when nothing is stale or how the default threshold behaves at call time.

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 defining behavior, no filler. The second sentence is mildly redundant with the first but earns its place by naming the user-facing motivation.

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, one-parameter, output-schema-backed tool, the description covers what the tool returns and what 'stale' means. The only real gap is routing against sibling listing tools, which is not required for correct invocation but would improve selection.

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 single parameter is fully documented in the schema, including its meaning, the default of 14, and the exclusiveMinimum constraint. The description only echoes this as 'a configurable number of days' and adds no syntax or edge-case guidance, so the schema is doing all the work.

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

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

States a specific verb and resource ('Returns job applications') plus the exact filter semantics ('haven't had a status update in a configurable number of days') and the derived output ('suggested follow-up action for each'). It never names a sibling such as get_recent_applications or search_job_applications to bound the difference, so it stops short of a 5.

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

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

'Useful for surfacing applications the user may have forgotten about' implies the use case but gives no explicit when-to-use rules, no exclusions, and no alternative tools for other application-listing needs. An agent must infer whether to call this or get_recent_applications.

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 PROSPECTING-only initial state, the best-effort secondary save with a warning rather than an error on failure, and that reuse can overwrite an existing application's source URL or job description (which explains the destructiveHint). Missing only auth/permission or rate-limit details.

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 create-or-reuse semantics, then sequencing, then optional parameters — a logical order. Three paragraphs is slightly long, but each sentence carries operational information an agent needs.

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, yet the description still flags the two response fields an agent must act on (`alreadyExist` and the warning), and it covers ordering with update_job_application_status. 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 coverage is 100%, so the baseline is 3; the description adds real meaning by explaining that source_url and job_description are attached best-effort after create/find and may replace stored values on reuse — behavior the schema does not convey. It does not add format or length guidance for the two required string fields.

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

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

States a specific verb and resource ('Creates a new job application entry in GigHQ') plus the non-obvious upsert behavior (reuses an existing active one for the same company+job). This clearly separates it from find_job_application and update_job_application among the siblings.

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 routing rules: call find_job_application first if you want to inspect a possible match; call update_job_application_status with 'APPLIED' immediately after if the user has already applied. It also states an exclusion — there is no way to create directly into APPLIED/INTERVIEWING.

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 readOnlyHint=false, so the mutation profile is covered; the description reinforces it with 'cannot be undone' and adds a useful procedural requirement (user confirmation). It does not describe failure behavior for an unknown UUID, which is why this stops 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?

Three short sentences, front-loaded with the destructive action and its outcome, followed by the safety instruction and a fallback for obtaining the UUID. 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 one-parameter destructive tool with an output schema (so return values need not be explained), the description covers purpose, irreversibility, confirmation, and UUID sourcing. Only edge-case behavior (e.g., nonexistent UUID) is absent, 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% and the single uuid parameter is fully documented in the schema itself, including its provenance. The description's mention of list_career_entries only partially overlaps that, adding no new syntax or format detail, 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 ('permanently deletes') and resource ('career journal entry') plus the identifier type (UUID). This clearly separates it from siblings like update_career_entry and delete_job_application_note without needing to open any schema.

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

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

Gives concrete pre-call guidance: confirm with the user first, and use list_career_entries to obtain the UUID if missing. It does not explicitly contrast with update_career_entry (the non-destructive alternative), but the 'cannot be undone' framing makes the distinction inferable.

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, so irreversibility is known; the description reinforces it ('cannot be undone') and adds a workflow obligation (user confirmation) not present in structured fields. That confirmation requirement is genuine added value for a destructive tool.

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

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

Three short sentences, front-loaded with the destructive nature and the confirmation requirement. Every sentence carries actionable information; nothing is 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 only 2 required params, full schema coverage, existing annotations, and an output schema, the description supplies everything needed: what it destroys, that it is irreversible, the confirmation step, and how to resolve the UUID. 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 coverage is 100% and both parameters are documented there, so the baseline is 3. The description points to list_job_application_notes for the UUID, which slightly duplicates what note_uuid's schema description 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?

Specific verb+resource ('Permanently deletes a note') with scope ('from a job application's timeline') that clearly separates it from update_job_application_note and list_job_application_notes. An agent can identify the operation 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?

Explicitly states a prerequisite workflow ('confirm with the user before calling') and names the sibling (list_job_application_notes) to obtain the note UUID. It does not contrast delete vs. update as alternatives, but the use case 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?

Annotations already declare a safe read (readOnlyHint=true, destructiveHint=false, openWorldHint=false), yet the description adds non-obvious server-side behavior the annotations cannot express: matches are restricted to APPLIED, INTERVIEWING, and PROSPECTING status, so REJECTED/OFFER/withdrawn applications will not appear. It also discloses matching semantics (case-insensitive substring on both fields, which keeps two roles at one company distinct).

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 core purpose and the call-order rule, then layered caveats, then outcome handling; the paragraph breaks map cleanly to decisions an agent must make. The standalone line 'Both `company` and `job` are required' restates the schema's required array and is the one sentence that does not fully earn its place.

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

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

An output schema exists, so return shape needs no explanation, and the description instead covers what the agent actually needs: when to call, what match semantics apply, which statuses are invisible to it, and what to do for each result. Nothing required to invoke this correctly or act on its result 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 both parameters already document case-insensitive substring matching, so the baseline is 3. The description adds the conjunction semantics — both fields must match, and both are required — which is a real constraint beyond reading either property in isolation.

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 (checks whether a saved job application exists for a specific posting) and precisely scopes the operation to company + job title matching. It explicitly distinguishes itself from search_job_applications and create_job_application by naming both siblings and the gap each leaves.

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 call-order rule ('call this before create_job_application to avoid creating a duplicate') and branch instructions for both outcomes: if found is false, proceed to create; if true, prefer reusing the UUID via update_job_application or add_job_application_note. It also rules out search_job_applications with a concrete reason (it cannot filter by job title).

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 indicate read-only, non-destructive, closed-world behavior, and the description adds important operational context beyond them: the call runs four parallel AI completions server-side, is expensive, and persists nothing. That persistence note is especially valuable because it explains why a separate save step and explicit user authorization are required.

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

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

The description is front-loaded with what the tool produces, then immediately clarifies cost, non-persistence, and the required follow-up flow. Despite being dense, every sentence carries actionable information for choosing and invoking the tool.

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 still covers the missing behavioral essentials: expensive one-time execution, no persistence, and explicit review before saving. An agent has enough context to select the tool, set expectations, and follow the correct post-call flow.

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 two parameters, including the nested career-switch details, are fully documented in the schema. The description does not add parameter-specific semantics beyond what the schema already provides, so a 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?

The description names a specific verb and resource: it runs the CareerCompass AI pipeline to generate defined artifacts such as objective statements, a positioning statement, categorized skills, and target market. It clearly distinguishes itself from get_career_compass and save_career_compass, so an agent can identify the tool's purpose 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?

It explicitly says to prefer get_career_compass first for existing saved data and to use save_career_compass afterward only with the user's explicit review and authorization. It also warns that the call is expensive and one-time rather than a cheap repeatable lookup, giving clear when-to-use and when-not-to-use guidance.

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

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

Annotations already establish that this is a read-only, non-destructive, closed-world operation, so the description does not need to restate safety. It adds useful behavioral context by calling the operation a 'Cheap read' and describing the saved-data scope, though it does not cover auth requirements or what happens when no data 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?

Two tight sentences, front-loaded with the retrieval purpose and then the routing guidance. Every clause carries useful information and there is no filler.

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

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

An output schema exists, so the description need not explain return structure. Annotations cover safety profile, and the description supplies the data categories and sibling routing needed to call this 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?

With zero parameters, there is no parameter semantics burden. The baseline for a no-param tool is 4, and the description appropriately focuses on what data is returned rather than inventing input details.

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 ('Retrieves the user's saved CareerCompass data') and enumerates exactly what is included: objectives, positioning statement, skills, and target market. This clearly distinguishes it from mutate/generate siblings such as generate_career_compass and save_career_compass.

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 names the alternative tool and the condition that selects this one: prefer it over generate_career_compass when the user just wants to review saved data. That is a direct when-to-use and when-not-to-use instruction.

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, openWorldHint=false), the description discloses the data dependencies that drive output: it reads GigHQ experience records and existing career entries, then surfaces the relevant role, estimates tenure, and flags roles with sparse documentation. That is meaningful disclosure of internal behavior an agent could not infer from the read-only hints alone. It stops short of saying whether repeated calls produce identical or re-tailored questions.

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 first sentence states what is returned, the second states when to call, the third explains the tailoring inputs, and the session types are a scannable list. Every sentence carries distinct information with no repetition of the schema.

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

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

With an output schema present, the description needn't explain return values, and with 0 required parameters the call is low-risk. It covers purpose, timing, data sources, and the meaning of every enum value; the only minor omission is whether output is persisted or regenerated per call.

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

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

Schema coverage is 100% and the enum values are named, so a baseline of 3 already applies. The description goes further by giving each session type a purpose ('wrap-up — leaving a role or wrapping up an internship', 'job-search — synthesise story and close gaps'), which resolves ambiguity in shorthand enum names and tells the agent how the choice changes the output.

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 opens with a specific verb and resource: it returns context-aware reflection questions for a career journaling session. It is clearly distinguishable from every sibling (which are entry CRUD, application tracking, and compass generation tools) — no other sibling produces prompting content.

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 exactly when to invoke it ('at the start of any journaling conversation to orient the discussion'), which is a clear sequencing cue. It does not name a when-not condition or an alternative path, but none of the siblings plausibly compete for this 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?

Annotations already declare readOnly, non-destructive, closed-world, so safety is covered; the description adds useful behavioral context — that it returns GigHQ's *recorded* data plus community metrics, and that the metrics window defaults to the last 30 days. It stops short of describing pagination or data staleness.

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 efficient sentences; the resource and its fields are front-loaded, followed by the windowing behavior. Slight redundancy with the schema's default-date text keeps it from a 5.

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

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

With an output schema present, return-shape explanation isn't required; the description covers purpose, data scope, and windowing. Only the explicit sibling routing and any read-freshness caveat are 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 baseline is 3, but the description adds meaning: startDate/endDate define a 'metrics window' that scopes the community metrics, not just a generic date filter. It also implicitly frames companyId as the UUID key for lookup.

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 ('Get detailed information about a company') and enumerates the data returned (applicants by status, Community Signal, H1B status, employee count, website). This is more specific than the generic name alone, though it never explicitly contrasts itself with search_companies in the prose.

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

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

Implies usage (fetch detailed company info once you have an identifier) and explains the metrics-window default, but gives no explicit when-to-use/when-not or routing to siblings like search_companies in the description text. The UUID-acquisition hint lives in the schema, not the description.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered by structured data. The description adds value by scoping the result to a single contact and disclosing the UUID prerequisite and its source tool. It doesn't discuss cost/latency or what happens on an unknown UUID, so it stops 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?

Three tight sentences: what it returns, when to use it, and how to obtain the argument. The most important information (purpose) is front-loaded and 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?

An output schema exists, so return-value detail is handled structurally; the description still summarizes what the agent will see. With one fully documented parameter, explicit use cases and a prerequisite pointer, 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% and there is only one parameter, so the schema already defines contact_id as a UUID. The description adds provenance guidance ('Find the UUID with `search_contacts`') that the schema does not contain, which is real value beyond the field definition.

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 full details for one of the user's job-search contacts') and enumerates the payload (profile, outreach status, linked applications, interaction history). It is clearly distinguishable from siblings like search_contacts, which it explicitly names as the lookup path.

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

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

Gives two concrete when-to-use triggers: before drafting outreach/follow-up messages so the message reflects prior conversation, and before interviews to recall who the user knows. It also routes the agent to search_contacts for the required UUID, so the whole call path is 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context by describing the returned content, though it says nothing about authorization, workspace scoping, or failure behavior for a missing UUID.

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, front-loaded blocks: purpose, exclusion, and prerequisite tip. Every sentence carries actionable information with no repetition or 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 annotations covering safety, an output schema covering return values, and the sole parameter fully documented, the description only needs purpose, routing, and prerequisites — all of which are present. Nothing an agent needs 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 description coverage is 100% and the schema already disambiguates 'uuid' from the numeric 'id'. The description restates the UUID requirement and the tip implies how to obtain one, but adds no format or syntax detail beyond the schema — 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 specific verb ('Fetches') and resource ('full details of a single job application by its UUID') and enumerates what the payload contains (status history, correspondence dates, job description, metadata). This is clearly distinguishable from search_job_applications (list/search) and find_job_application (likely lookup by other keys).

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 do-not-use case naming the exact sibling to use instead (list_job_application_notes) with sample user phrasings. It also supplies a prerequisite path — call search_job_applications first when only a company name is available — which is exactly the routing guidance an agent needs.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is fully covered elsewhere. The description adds the default 30-day window, but that same default is already stated in the startDate/endDate schema descriptions, so most of the behavioral content is duplicative; nothing is said about result freshness, metric definitions (what 'Community Signal' means), or empty-window behavior.

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 paragraphs, front-loaded with the purpose and followed by the one non-obvious calling behavior (computing explicit dates). The second paragraph re-explains defaults already in the schema, which is mild redundancy but not bloat.

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

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

With an output schema covering return values, annotations covering the safety profile, and full schema parameter coverage, the description only needs to explain purpose and the date-window calling convention — both are present. It is complete for the call, though a one-line distinction from get_job_application would close the remaining gap.

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

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

Schema description coverage is 100%, so all three parameters are already documented, including the exact ISO 8601 formats and the 30-day default. The description's date-window sentence largely restates the schema and adds no format or constraint detail for jobId; 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 uses a specific verb and resource — 'Get detailed community metrics for a specific job listing' — and even enumerates the metrics (applicants by status, average days per status, Community Signal). It is clear against most siblings, though it never explicitly contrasts with get_job_application, the closest name-neighbor in the 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 concrete usage context: the window defaults to the last 30 days, and when a user asks for a longer range the agent should compute startDate/endDate explicitly, with worked phrasings ('last 6 months', 'since January'). It stops short of naming when to prefer a sibling tool, so it earns a 4 rather than 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?

Goes well beyond the annotations by disclosing the ranking dimensions (keywords, competency coverage, quality, recency, diversity), the grouping by competency bucket, the default of 20 entries, and the missing-job-description fallback that returns the application link plus substantive/recent evidence. These are real behavioral traits an agent could not infer from readOnlyHint/destructiveHint alone.

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 identity of the tool and its contents are front-loaded in the first sentence, followed by ranking/grouping behavior, the read-only disclaimer, and the fallback case. Four sentences with minimal waste, though the ranking list is dense enough to 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 read-only retrieval tool with an output schema and full annotation coverage, the description covers the remaining gaps an agent needs: what is included, how evidence is ordered and grouped, what it will not do, and how it degrades when job description data 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 both parameters are already documented, which sets the baseline at 3. The description reinforces the 20-entry default and explains the grouping the limit controls, but adds no new syntax or constraint detail for application_uuid or the limit's max of 50.

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 (Retrieves) and a concrete composite resource: the saved job application, candidate profile, and ranked Career Journal evidence. This clearly separates it from single-resource siblings like get_job_application or list_career_entries, though no sibling is named explicitly, which is why it stops short of a 5.

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

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

Gives clear negative scoping — 'supplies evidence and retrieval metadata only', 'does not assess the candidate, calculate a fit score, or modify records' — which tells the agent this is a fetch step, not a scoring step. It does not explicitly name when to prefer get_job_application or list_career_entries instead, so the alternative routing is left implicit.

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

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

Annotations already declare readOnly/non-destructive/closed-world, so the safety profile is covered. The description goes beyond them by disclosing the totalCount-vs-list-length mismatch and the required follow-up behavior, which is real behavioral context an agent could not infer elsewhere. Minor gap: no note on ordering beyond 'most recent' or pagination limits.

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

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

Front-loaded with what is returned and its scope in the first sentence, with the totalCount caveat second. Slightly dense but every clause carries information; the field list is near-redundant with the output schema but earns its place as a quick summary.

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

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

Output schema exists, so return values needn't be re-explained, yet the description usefully flags the one non-obvious semantic (totalCount vs returned list) and the recommended follow-up. For a zero-parameter read tool with full annotation coverage, nothing an agent needs 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 the baseline is 4. The description correctly implies no inputs are needed and spends its words on output semantics instead, which is the right allocation.

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 (retrieves), resource (job applications) and precise scope (10 most recent, with the listed fields). An agent can immediately tell this apart from search_job_applications or get_job_application 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 the exact alternative (search_job_applications) and the condition that should route the agent there — when more than the 10 returned exist. It also instructs the agent to surface totalCount when it exceeds the list, which is actionable usage guidance rather than mere description.

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

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

Annotations already declare readOnly, non-destructive, closed-world, so the safety profile is covered. The description adds useful behavior beyond that: result ordering ('newest first') and the fact that filters are optional and narrow results — details an agent would otherwise have to infer.

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 summary followed by scannable use-case bullets; every line is purposeful. The entry-type value mapping is repeated verbatim in the schema, which is the only mild 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?

With an output schema present, the description needn't explain return values, and it covers ordering and filters adequately. A brief note on pagination/total-count behavior would fully close the loop, but an agent has enough 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 description coverage is 100%, including pagination bounds and date formats, so the schema already carries parameter semantics. The description's entry-type mapping duplicates the schema's own enum explanation rather than adding new meaning, making this baseline-adequate.

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 the user's career journal entries from GigHQ') and adds the ordering ('newest first') and filter scope. It is clearly distinguishable from siblings like list_experiences and list_job_application_notes, which target different resources.

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?

A 'Use this tool to' list gives four concrete scenarios (review before journaling, find entries to update, identify gaps, synthesise into bullets), which is strong guidance. It stops short of naming alternatives or when-not conditions (e.g. use list_experiences for work history), so it falls short of 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 read-only, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely new context: it returns integer IDs, is the tool-based substitute for the `gighq://experience` resource, and works in voice mode. No output-shape detail is needed 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 short paragraphs, each with a distinct job: what it returns, when to call it and what to do with the result, and how it relates to the resource. The most important information (returns experience records with IDs) is front-loaded, and nothing is padded.

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

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

For a zero-parameter read tool with annotations and an output schema, the description covers return semantics, workflow placement, and an alternative access path. The only missing piece is a one-line differentiation from `list_career_entries`, which would remove the last ambiguity in tool selection.

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 nothing for the description to disambiguate and no risk of incomplete parameter guidance. Baseline 4 is appropriate for a no-arg tool.

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 the user's work experience records along with their integer IDs. That is concrete and actionable. However, the sibling set contains `list_career_entries`, which reads like an adjacent list of the same domain, and the description never distinguishes the two — a meaningful gap for an agent choosing between list tools.

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 sequencing: call this before `add_career_entry` or `update_career_entry` to resolve the correct `experience_id`, and confirm the role with the user before saving. That is well above typical guidance. It still leaves the `list_career_entries` vs `list_experiences` choice unaddressed, so it is not fully complete.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral detail beyond that: the result set is all notes for one application, ordered by date, with the exact fields returned. It does not discuss pagination or behavior when no notes exist, which keeps it just 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?

Front-loaded with the decision trigger, then output contents, then follow-up routing — a sensible order. The quoted example phrases are slightly repetitive but they serve the routing function, so waste is minimal.

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 with an output schema and full annotation coverage, the description supplies more than enough to call it correctly. The only unaddressed edge is empty-result behavior, but with an output schema present that is a minor omission.

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 is already documented as the application UUID. The description reinforces the scoping ("for a job application") but adds no syntax or format information beyond the schema, so the baseline 3 applies.

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

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

The description states a specific verb and resource — list user-authored notes for a single job application — and enumerates the returned fields (UUID, body, category, timestamp). It is clearly distinguishable from add/update/delete_job_application_note, which are named as separate follow-up steps.

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 trigger phrasing ("do I have any notes", "show me my notes") and routes the agent onward: use the returned UUIDs with update_job_application_note or delete_job_application_note. That is a concrete when-to-use plus named alternatives, leaving little 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=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: it discloses that 'unknown' is returned when a flag is unavailable and that results reflect only data recorded in GigHQ, which tells the agent not to treat a negative as authoritative.

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 the tool does and what it returns, followed by the availability caveat. The closing sentence ('These results describe the data recorded in GigHQ') partly repeats the earlier data-provenance caveat, so a small amount of redundancy keeps it from a 5.

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

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

An output schema exists, so the description need not enumerate return fields, and it correctly focuses on the caveats an agent must know (unknown values, GigHQ-recorded provenance). For a single-parameter read lookup with full annotation coverage, this is essentially complete; only explicit sibling routing 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 there is a single required parameter with its own description and example ('Google'), so the schema carries the parameter documentation. The tool description restates the company-name input but adds no matching or format semantics beyond it, 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 ('Looks up a company by name') plus precisely what is returned: GigHQ's recorded H1B sponsorship and concurrent H1B flags. This distinguishes it from generic company lookups by its data focus, though it never names the closely related siblings (search_companies, get_company_details) to make the boundary explicit.

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

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

Usage is only implied: an agent can infer this is the tool for checking H1B sponsorship status, but there is no explicit when-to-use guidance, no comparison to search_companies or get_company_details, and no prerequisites stated. The gap is modest because the tool's narrow purpose is fairly self-evident from the name and description.

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

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

The annotations already establish read-only, closed-world, non-destructive behavior. The description adds useful behavioral context by disclosing the assembled categories and framing the tool as context-only. It does not mention permissions, rate limits, or response format, but that is less critical given the existing output schema and 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?

The description is front-loaded with the core action and then enumerates the assembled contents. It is dense but purposeful, with the second sentence clearly separating scope from non-goals. It is slightly long, but the detail is relevant to a multi-source aggregator.

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 aggregates data from several sources, and the description fully identifies what is assembled and what the tool does not do. An output schema exists, so return structure need not be explained, and the annotations already cover safety characteristics. Nothing essential for correct selection 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?

There is one required application_uuid parameter, and the schema description already explains that it identifies the saved GigHQ job application. The description reinforces that this is tied to a saved application but does not add syntax or format details beyond the schema. With 100% schema description coverage, the baseline of 3 is appropriate.

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

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

States a specific verb and resource: it assembles interview-preparation context for a saved GigHQ job application. The description enumerates exactly what is included (job/company context, profile, Career Journal by role, evidence matches, weak competencies, company briefing), making its purpose distinct from sibling getters.

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

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

Clearly says when to use it: preparing for an interview on a saved GigHQ job application. It also states when not to expect more from it, explicitly noting that it does not generate questions, write STAR/CAR answers, or assess the candidate. It does not name specific alternative sibling tools, so it falls short of explicit 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 read-only, non-destructive, closed-world behavior, and the description adds important context beyond that: it assembles context only, does not validate against live market demand or hiring volume, and leaves tiered recommendations to the client model. This prevents the agent from expecting tool-generated recommendations or market validation.

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 definition is front-loaded with purpose and then adds the key scope boundaries and division of labor. The sentences are dense but each contributes routing or expectation-setting information, with little waste.

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 the annotations and output schema, the description supplies everything an agent needs: what context is assembled, how it differs from get_job_fit_evidence, that it is read-only, that recommendations are client-produced, and that live market validation is out of scope.

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

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

Schema coverage is 100%, so all four optional parameters are documented in the schema. The description does not map or elaborate on those parameters beyond the general profile context, so it appropriately stays at the baseline for high schema coverage.

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

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

The description states a specific action — assembling profile, experience, career journal evidence, and CareerCompass data — to recommend role titles, and explicitly contrasts this with get_job_fit_evidence. An agent can distinguish it from the sibling evaluator tool 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?

It names the key alternative, get_job_fit_evidence, and explains the inverse selection condition: start from the candidate profile rather than evaluating one specific job. It also clearly limits scope to role taxonomy and excludes live job-market validation.

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 destructiveHint=true annotation by explaining exactly what destruction means: omitted array fields are saved as empty rather than left unchanged, and the full record is replaced. The review-and-authorize precondition is operational context annotations cannot express.

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 front-loaded sentences: what it does, then the destructive semantics, then the precondition. The parenthetical enumeration of seven array fields is somewhat redundant with the schema, but it earns its place as an explicit warning against silent data loss.

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

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

For a 17-parameter destructive upsert with an output schema, the description covers the two things an agent could get wrong: clobbering fields by omission and saving without user authorization. Return values are handled by the output schema, so 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 coverage is already 88%, so most parameters self-document. The description still adds value by grouping the clear-on-omit array fields and framing the pass-through pattern (read current state, resend unchanged fields), though it does not touch the single-value fields like target_industry vs target_industries or career_switch_type.

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 ('Persists') and resource ('CareerCompass data to the user's GigHQ profile'), which cleanly separates it from read siblings like get_career_compass and generative siblings like generate_career_compass. An agent can place 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?

Explicit sequencing: 'Call get_career_compass first and pass through every field the user isn't changing,' and a hard precondition that the user must have reviewed content (e.g. from generate_career_compass) and explicitly authorized saving. Names the alternative tools and the gating condition.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety and closed-dataset scope are covered. The description usefully adds that the return is identifiers rather than full records, but says nothing about match semantics (exact vs partial, case sensitivity, zero/multiple results), which are the behaviors an agent actually needs to know.

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

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

One tight sentence that front-loads the action and the payoff (UUIDs) with zero 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?

An output schema exists, so return-value explanation is unnecessary, and the description correctly signals IDs as the result. However, for a search tool it omits the one thing that matters operationally — whether matching is exact or fuzzy and whether multiple companies can come back — leaving a real gap.

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

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

Schema description coverage is 100% and the single `name` parameter is documented with an example, so the schema carries the burden. The description only restates 'by name' without clarifying matching rules, so baseline 3 applies.

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

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

The description gives a specific verb ('Search') and resource ('companies') and states the output goal (UUIDs), which distinguishes it from get_company_details. It does not explicitly name or contrast with the closest sibling, so it stops short of a 5.

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

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

The purpose implies a resolve-name-to-ID workflow before calling get_company_details, but the description never states when to use this versus get_company_details or other search_* tools. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description usefully reinforces this by saying the MCP connection cannot create or delete contacts and that records originate in the app or browser extension. It adds origin and immutability context beyond the annotations, though it says nothing about result ordering or pagination behavior.

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?

Purpose is stated in the first sentence before any detail, and the bullet list is scannable. The enumerated status values are somewhat redundant with the schema enum, which is the only real 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?

An output schema exists, so return-value explanation is not required, and the description covers origin, scope, and the read-only constraint. The main omission is any relationship to the sibling get_contact for single-record retrieval, which matters given the agent’s tool selection task.

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 name, skip, take and status are already fully documented. The description merely restates the six status values that already appear in the enum, adding no new meaning such as what “cold” or “connected” signify. 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?

Specific verb (searches) and resource (job-search contacts) with a clarifying inventory of who those contacts are: recruiters, hiring managers, referrals, networking. It does not explicitly distinguish itself from the sibling get_contact, so an agent must infer that one is search and the other is single-record fetch.

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 bulleted “Use this tool to” list gives three concrete situations (pre-outreach lookup, pre-interview company research, stage review), which is clear positive guidance. It also states the negative constraint that creation/deletion happens elsewhere, but never names an alternative tool such as get_contact, so the routing is not fully resolved.

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 and non-destructive behavior, and the description adds substantial context: returned UUIDs, totalCount semantics versus pagination, case-insensitive substring matching, duplicate handling, and disambiguation 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 description is front-loaded and organized from purpose to usage to return behavior to matching rules. It is somewhat long, but most sentences carry useful operational 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?

Given an output schema and safety annotations already present, the description still supplies the key behavioral details an agent needs: matching semantics, pagination count behavior, UUID usage, and duplicate disambiguation.

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 useful meaning beyond the schema by explaining the company/status relationship, the status-only requirement to omit company, and how totalCount relates to take/skip.

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 job applications by company name, status, or both. The search scope is clear, but it does not explicitly distinguish itself from nearby retrieval tools such as find_job_application or get_job_application.

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 usage contexts: finding a company's application, locating an application to view or update, and counting applications by status. It also states the status-only omission rule for company, but does not explicitly name when to use 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?

Goes well beyond destructiveHint=true by spelling out the concrete side effects of each branch: stamping appliedEndDate/interviewingEndDate/offerEndDate, setting status to CANDIDATE_WITHDREW and endDate=now, or clearing endDate and resetting to APPLIED. It also notes the app-button equivalence, which helps the agent reason about user intent. No contradiction with the mutation 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?

Front-loaded with trigger phrases, then clearly bulleted per branch, so an agent can scan it quickly. Slight redundancy: the 'check current isActive first' instruction appears in the description and again in the schema's parameter description.

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 triggers, both branches' effects, prerequisites, and the sibling it replaces; an output schema exists so return values need no explanation. Nothing material 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 coverage is 100%, so baseline is 3, but the description adds value by mapping each value of currentIsActive to its full consequence chain rather than just restating the boolean meaning. The pre-call verification instruction ('check isActive before calling') is a semantic constraint the schema only weakly implies.

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 (deactivate/reactivate interest) and resource (job application), and explicitly distinguishes itself from the sibling update_job_application_status. The trigger-phrase list at the top makes the tool's identity unambiguous at a glance.

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?

Enumerates the exact user phrasings that select this tool, names the wrong alternative ('do not use update_job_application_status as a proxy'), and requires checking current state via get_job_application or search_job_applications first. Both when-to-use and when-not-to-use are 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?

With destructiveHint=true, readOnlyHint=false and openWorldHint=false already declared, the description adds meaningful patch semantics ('only fields provided will be changed; all other fields remain as-is'), which is the key behavioral fact an updating agent needs. It still omits irreversibility, permission requirements, and what happens if a field is sent as empty.

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 core action and patch semantics before the use cases. Everything is relevant, though the use-case list partially repeats the metrics guidance that the schema also supplies.

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 covers action, partial-update behavior and target scenarios. A uuid error case or the fact that the entry must exist first would round it out, but nothing essential to invoking 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 description coverage is 100%, so every parameter is already fully documented in the schema, including the type enum mapping and the three-number metrics rule. The description's mentions of metrics, entry_date and description largely restate that, adding no syntax or edge-case detail 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 opens with a specific verb and resource ('Updates an existing career journal entry'), which cleanly separates it from add_career_entry, delete_career_entry and list_career_entries without needing careful reading. The follow-up sentence about only changing provided fields further scopes it as a partial update rather than a create or replace.

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 names concrete usage scenarios (refine descriptions, backfill metrics, correct the date, re-type an entry) and explicitly states it is the right tool for backfilling the three-number metrics breakdown. There are no explicit when-not-to-use statements, and it assumes the agent has already found the entry via a sibling tool rather than saying so.

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 and destructiveHint=false, so the safety profile is covered; the description adds real value by disclosing the side effect that a status-change entry is auto-logged into interaction history. It stops short of saying whether non-adjacent or reverse transitions are permitted, which matters for a lifecycle-mutating tool.

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

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

Four short sentences, front-loaded with the action, then the side effect, then the value semantics, then how to get the ID. Every sentence carries information an agent would otherwise have to guess.

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

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

With an output schema present and full schema coverage, the description covers the action, its side effect, enum semantics, and the prerequisite lookup. The only gap is whether invalid transition ordering is enforced or rejected by the server.

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 both parameters are already documented; the baseline would be 3. The description earns above baseline by explaining the ordering semantics of the status enum values and when 'cold' applies, information the enum list alone does not convey.

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 ('Updates a contact's outreach status in GigHQ') and names the exact field being changed, which separates it from read-only siblings like get_contact or search_contacts. An agent can tell immediately this is a mutation of outreach state.

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 status lifecycle order (not_contacted → reached_out → responded → in_conversation → connected), a specific rule for the otherwise-unexplained 'cold' value ('when the thread has gone quiet'), and points to search_contacts as the way to obtain the required contact_id. Nothing 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 declare destructiveHint=true; the description earns that flag by disclosing exactly what is destroyed ('job_description REPLACES the previously saved description — pass the full text, not a diff') and what is preserved ('omitting a field leaves it unchanged'). It also states the validation constraint that at least one field is required, which the 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?

Front-loaded with what it does, then triggers, then exclusions, then behavioural rules — a clean decision-first structure. Every sentence carries information the agent needs; nothing is restated from the schema or 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?

Three parameters, all documented; an output schema exists so return values need no explanation; annotations cover safety. The description fills the remaining gaps (trigger conditions, sibling routing, replace semantics) so an agent can call this correctly without further exploration.

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 real meaning on top: the mutual-requirement (at least one of source_url or job_description) and the full-text-not-diff instruction for job_description, which tells the agent how to format the value, not just what it is.

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 (enrich/correct) and resource (an existing job application's saved posting details) plus the exact fields touched. It explicitly bounds scope ('only touches source_url and job_description'), which separates it from the many status/interest siblings.

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 triggering situations (user finds the JD later, wants to add the link, wants to correct the description) and two explicit 'Do NOT use' exclusions that name the correct alternative tools (update_job_application_status, toggle_job_application_interest). Nothing 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 flag destructiveHint=true and readOnlyHint=false, but the description adds the crucial reason: both body and category are required because the backend replaces the full note on update. That tells the agent omitted fields are overwritten, which annotations alone cannot convey. It doesn't cover permissions or error behavior, hence a 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-loads the most important operational fact (full replacement) in the first two sentences, then the inference rule, then the fallback retrieval. The ten-item category list is long but justified because the schema supplies no enum. Slightly verbose but every block earns its place.

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

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

For a destructive mutation with an output schema, the description covers what matters: replacement semantics, the required-field constraint, category inference, ambiguity handling, and UUID retrieval. Return values are handled by the output schema, so no description gap remains.

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 a baseline of 3 is warranted, but the description goes beyond it: the category mapping effectively defines the value domain as an enum, which the schema lacks (0 params with enums) and explicitly delegates back to the description. It also clarifies the body/category joint requirement. The remaining parameters are left to their schema entries.

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 ('Updates the body or category of an existing job application note') and immediately scopes it against the sibling add_job_application_note by emphasizing 'existing' and the full-replacement semantics. An agent can tell this apart from add/delete/list note tools 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?

Gives explicit procedural guidance: infer category from note content when unstated, ask the user when ambiguous, and call list_job_application_notes first if the UUID is unknown. Both the when-to-use and the prerequisite retrieval step are named.

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?

Discloses a non-obvious behavioral trait: invalid transitions are silently ignored by the API, so the caller must validate. It also clarifies that REJECTED records a company rejection internally, and that UNKNOWN blocks all transitions — none of which the annotations (readOnly=false, destructive=false, openWorld=false) 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?

Front-loaded with the critical warning, then status meanings, then the transition table — a sensible order. The transition matrix is long but each line is load-bearing; the duplicated withdrawal warning is the only mild 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 mutation tool with three required params, an output schema, and full annotation coverage, the description supplies everything an agent needs: valid inputs, transition rules, silent-failure behavior, and routing to the alternative 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 enums already constrain status values, so the schema carries most weight. The description nonetheless adds meaning beyond the schema: it explains why currentStatus exists (transition validation) and clarifies the semantic distinction between REJECTED and candidate withdrawal.

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 ('Updates the status of a job application by its UUID') and immediately contrasts itself with the sibling toggle_job_application_interest. An agent can distinguish this tool from the withdrawal path 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?

Opens with an explicit STOP condition listing trigger phrases, names the alternative tool, and warns against using REJECTED as a proxy. It also spells out valid source→target transitions, which is exactly the when-to-use guidance an agent needs.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds a genuinely useful behavioral constraint beyond the schema — that it aggregates 'up to 30 active applications' — which tells the agent the summary is bounded and sampled rather than exhaustive. It stops short of noting how 'active' is defined or whether results are cached/stale.

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, the purpose front-loaded in sentence one and the deliverable breakdown in sentence two. No filler, no repetition of the name, and every listed item corresponds to a distinct output dimension.

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 zero parameters, an existing output schema, and annotations covering the safety profile, the only remaining burden is telling the agent what the summary covers and how large the sample is — both of which the description does. Nothing needed 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?

The tool takes zero parameters, so the baseline is 4; the description correctly implies no input is required and instead spends its words on output contents. There is no parameter ambiguity to resolve.

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 opens with a specific verb+resource ('Generates a weekly job search health summary') and then enumerates exactly what the summary contains: status distribution, conversion rates, longest-open applications, pipeline clustering, and a suggested focus area. That level of specificity clearly separates it from list-oriented siblings such as get_recent_applications or the narrower check_stale_applications.

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 word 'weekly' hints at a periodic cadence, but the description never states when to choose this over check_stale_applications, get_recent_applications, or search_job_applications, nor does it note any preconditions or exclusions. Usage is inferable rather than stated.

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