Graphlog Career

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

Annotations already declare read-only, idempotent, non-destructive, so the description does not need to re-litigate safety. It instead adds real behavioral detail annotations cannot: an invalid record is rejected with the same refusal a save would produce, and the response is a hints list plus a sparse per-entry emptiness map that omits fully populated entries.

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

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

The core behavior is front-loaded in the first sentence and the return shape is spelled out in the last, with no filler. A few phrases are awkwardly inverted ("It serves a check of a draft", "to the schema fields it holds no value in"), which costs some readability but not correctness.

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

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

No output schema exists, and the description compensates by describing both returned members, including the path notation (roles[0].projects[2]) used as map keys. The only thin spot is deferring the structure of hints entirely to save_career_record, which is acceptable given that sibling is available, but leaves a small gap for an agent that never calls it.

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

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

With one parameter and 100% schema description coverage, the schema already states the record must be in the shape get_career_record returns. The description reinforces that it is the whole record rather than a fragment, but adds no syntax or structural guidance beyond the schema, which is the expected 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?

"Check a whole career record without storing it" names a specific verb and resource and immediately rules out the save sibling. The follow-on clauses (schema fit, what a save would drop, what entries leave empty) pin down the three checks performed, so an agent can distinguish it from save_career_record and get_career_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?

"It serves a check of a draft" implies the pre-save validation use case, and the parallel with save_career_record ("refused as a save is", "hints as save_career_record gives them") hints at the ordering. But it never explicitly says to call this before save_career_record or names any tool to avoid, leaving the routing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the return shape: a one-line summary naming file, size, and record version, plus the file payload with its top-level keys.

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 action and scope, then the return contract. Dense but every clause carries information; the inline JSON key list is slightly heavy but justified since no output schema exists.

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

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

With no output schema, the description carries the burden of explaining the return value, and it does so concretely (summary line plus file with tenantId, exportedAt, schemaVersion, record, applications). Minor gaps remain, such as whether the file is returned inline or as a download reference and any size limits.

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; there is nothing for the description to disambiguate. It instead spends its words on the output contract, which is a reasonable use of the space.

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 ('Export the whole career record and the job applications') and scopes it as a single JSON file, which cleanly separates it from siblings like import_career_record, get_career_record, and show_career_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?

It gives clear usage contexts — a request for a copy, a backup, or moving the person to another account — which tells the agent when this is the right tool. It does not explicitly name the alternative tools (e.g. get_career_record for a single read), so it stops short of full when-not guidance.

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

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

Annotations already cover the read-only, idempotent, non-destructive, closed-world profile, and the description adds real value on top: it discloses the failure mode for unknown ids, the ordering of the update log, and the absence semantics for parts not included or not held. It does not mention pagination or size limits, but for a single-record read that is a minor gap.

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

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

It is front-loaded and dense with no filler, but the phrasing is often garbled ('It serves a reply from that company, an interview for that role'), and terms like 'kept' and 'holds' are used without definition, forcing the agent to infer meaning.

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

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

With only two parameters and no output schema, the description carries the burden of describing the return shape and does so field by field, plus failure behavior and absence handling. Only the undefined 'kept'/'holds' vocabulary leaves a small unresolved gap.

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

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

Schema coverage is 100%, so the baseline is 3, and the description earns an increment by explaining what 'include' actually does – 'the parts include names' and that a part not included or not held is absent from the response. That meaning is not derivable from the schema alone.

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

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

States a specific verb and resource ('Read one kept job application') and scopes it to a single record, which contrasts with the sibling list_career_applications. It does not explicitly name any sibling, so the differentiation is implied by 'one' rather than stated.

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 use contexts – answering a company reply, an interview, application history, or questions about what was sent – and implicitly directs the agent to obtain the id from list_career_applications by saying it 'refuses an id it does not keep'. It stops short of naming alternative tools or stating exclusions.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds real value beyond that: the return shape, the meaning of version 0 with empty sections, and how 'experience' is computed including uncounted dates. It stops short of describing pagination or size limits, but for a zero-param read this is solid.

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

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

Front-loaded with the core action, then the return contract. Sentences are dense but each carries information. The phrase 'anything written from it' is slightly vague, but overall there is 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?

With no output schema, the description correctly takes on the burden of explaining the returned fields (version, updatedAt, experience, record) and the empty-state signal. It is nearly complete for a simple read tool; only the relationship to overlapping siblings 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 no parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description instead spends its words on return-value semantics, 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 and resource ('Read this person's whole career record') with clear scope ('whole'). It does not, however, distinguish itself from close siblings like show_career_record, check_career_record, or export_career_record, so an agent cannot tell from the description alone which of these to pick.

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

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

'It serves any question about their work and anything written from it' gives a broad usage context, but there is no explicit when-not guidance and no mention of the alternative sibling tools that overlap with it. Usage is implied rather than routed.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the description's marginal burden is low. It does add value by disclosing the shape of the payload (all sections and fields, with formats and absence rules), which matters because there is no output schema. However, it says nothing about the response envelope, size, or cost of returning a full schema, so it stays at a moderate level.

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

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

Two sentences, no filler, with the return content front-loaded before the use-case clarification. Every clause adds information the agent did not already have from the tool name.

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

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

For a no-parameter, read-only schema-introspection tool with no output schema, the description covers what comes back well enough to decide whether to call it. The only gap is that it never states the size or granularity limit of the returned schema nor confirms there is no filtering, which a caller reasoning about context cost might want.

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; baseline 4 applies. The description correctly makes no parameter claims and does not invent options that the empty schema would contradict.

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: 'Return the career record's JSON Schema', followed by an enumeration of what that schema contains (sections, fields, formats, absence conditions). The clause 'It serves questions about what the career record can keep' implicitly separates it from data-returning siblings like get_career_record or show_career_record, but none of those siblings are named explicitly.

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

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

The second sentence gives a clear use context: questions about what the career record can hold and what a field accepts. This is a usable when-to-use signal without naming the alternative tools or stating exclusions (e.g., 'use get_career_record for actual values'), so it stops short of the 5 bar.

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 read-only, idempotent, and non-destructive annotations, it discloses significant cross-tool behavior: when access is false, every tool that stores something is refused while the rest still work. It also explains Stripe status sourcing, null and date conventions, and the behavior of the manage, withdraw, and subscribe links, including the 14-day full-refund condition.

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 use cases are front-loaded, followed logically by the return shape and field semantics. The single paragraph is dense and contains several compressed clauses, reducing scannability, but nearly all of its content 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 zero-argument read with no output schema, the description supplies the returned keys, date and null conventions, field-by-field meanings, and actionable-link behavior. It also documents the access=false effect on other tools, leaving no material gap for invocation or result interpretation.

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 are no input parameters, so no parameter syntax or semantics require explanation; the zero-parameter baseline applies. The explicit current-account scope also makes it clear why no account or subscription identifier is needed.

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 the specific verb "Read" and scopes the resource to "this account's Graphlog Career subscription as stored." It further identifies the subscription, price, renewal, cancellation, refund, and payment questions it answers, distinguishing it from the sibling record and application 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?

The phrase "It serves questions about..." provides clear when-to-use guidance across several billing and subscription-lifecycle topics. It does not explicitly state when not to use the tool or route mutations to another tool, though it explains that management, withdrawal, and subscription actions are available through returned links.

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 destructive, non-idempotent, non-read-only, but the description goes further: it discloses the replacement semantics (not a merge), the conditional write of applications only "when it carries them", the all-or-nothing refusal on unreadable files ("nothing changes"), and the return payload including a changed flag. That is exactly the extra 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?

Front-loaded with the destructive action, then usage, then failure mode, then return value. The final sentence packing the return shape into a list is a bit dense but every clause carries information; nothing is filler.

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

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

For a destructive import with an opaque nested-object parameter and no output schema, the description supplies the failure behavior and the return fields, which the schema cannot. It stops short of stating prerequisites (e.g., whether the current record must exist or be valid, and whether the import is transactional across both stores).

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

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

Schema coverage is 100% and the single parameter is already documented as "The whole file exactly as export_career_record produced it." The description's "when it carries them" adds a small hint that the applications section is optional inside the file, but otherwise it restates the schema. Baseline 3 applies.

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

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

States a specific verb and resource ("Replace the stored career record") plus the cascade into job applications, which distinguishes it from save_career_record (partial save) and restore_career_version (version-based restore). An agent can pick this off the shelf 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 serves restoring or moving in an export file" gives a clear use context, and the pairing with export_career_record implies the round-trip. It never explicitly excludes restore_career_version or save_career_record as the alternative when you have discrete fields rather than a file, so the routing is implied rather than 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 read-only, idempotent, non-destructive, closed-world behavior, and the description adds substantial context beyond that: sort order, what is omitted, the exact return envelope {today, applications}, and the meaning of lastUpdate, updateCount, holds, noResponse, keptUntil, and undated-entry sorting. It even documents the empty-list case.

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 purpose and ordering, then return details. It is dense and slightly run-on in the field-definition clause, but nearly every sentence carries information an agent needs given the absence of an output 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 no output schema and no parameters, the description carries the full burden of explaining returns, and it does so field by field, including edge cases (undated entries, empty list). Nothing an agent needs to interpret the response is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline is 4. The description instead spends its space on return-value semantics, which is appropriate here.

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

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

States a specific verb and resource ('List the person's kept job applications') plus ordering ('newest first') and explicit exclusions ('without their log of updates or the texts of the posting, CV and letter'). This clearly separates it from the singular get_career_application and from save_career_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?

Gives concrete use cases: 'questions about where their applications stand and finding one by company or role.' It does not explicitly name when to prefer a sibling (e.g., get_career_application for a single entry), so it stops short of full routing guidance.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds useful behavioral context beyond annotations: seven versions are kept, older ones are gone, ordering is newest first, and the return envelope includes current with an empty-state value of 0.

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 resource and ordering, then adds retention, use case, and return shape. Each sentence contributes useful information without unnecessary repetition.

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

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

For a zero-parameter list tool with no output schema, the description provides the return shape, retention limit, ordering, and empty-state behavior. Nothing material is missing for an agent 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?

There are zero input parameters, so the baseline is 4. The description correctly adds no parameter details because none exist.

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: list kept versions of the career record, newest first, including version number, save time, and note. It also explicitly links the output to restore_career_version, distinguishing it from the sibling restore tool.

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

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

Names the question type it serves (what changed and when) and the restore workflow it supports by supplying version numbers. It does not explicitly say when not to use it or contrast it with other read siblings, 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?

Goes well beyond the annotations (which only say destructive, non-idempotent, non-read-only) by disclosing that the restore writes a new version labeled 'restored version N' and is therefore itself undoable, and by describing refusal behavior for non-kept versions with the valid range returned. It also documents the return shape ({version, stored, changed}) which no output schema provides.

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

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

Three tight sentences with the state change front-loaded, then usage intent, then edge-case and return behavior. The final clause about 'save_career_record's result without hints' is terse to the point of being slightly opaque, but it earns its place given there is no output schema.

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

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

For a single-parameter mutation with no output schema, the definition covers the mutation's effect, the recoverability of that effect, input constraints, refusal behavior, and the response shape. 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 coverage is 100% and the schema already ties numbering to list_career_versions, so the baseline is 3. The description adds real meaning beyond the schema by constraining valid input to *kept* versions and explaining the refusal payload for out-of-range requests.

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

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

Uses a specific verb+resource ('Make a kept version the current career record again') and immediately distinguishes itself from sibling write tools like save_career_record and listing tools like list_career_versions. An agent can tell exactly what state transition this performs.

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 the intent it serves: 'undoing a change or going back to an earlier state,' which is clear when-to-use guidance. It also states the exclusion — non-kept versions are refused — but never names a sibling as an alternative for the cases this tool cannot handle.

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 past the annotations (destructiveHint=true, idempotentHint=false) by disclosing field-replacement semantics, that null clears an optional field, that remove:true deletes, that status changes are logged onto the last added or own update, that the write is all-or-nothing ('nothing stored'), and retention rules (90 days after last change, 500 entries, 5 MB of text). It also flags the privacy transformation of other people's names, which no structured field conveys.

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 add/change/remove rule are front-loaded, and nearly every sentence carries load-bearing information about limits, atomicity or the return shape. Some sentences are dense and comma-chained (the update-log sentence in particular), costing a little readability for a batch-mutation tool with this much conditional behavior.

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

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

Despite no output schema it describes the return object precisely ({saved, kept} with each saved entry's id, company, role and outcome), and covers error behavior, retention caps, deletion timing and privacy handling. An agent has everything needed to construct a correct call and interpret the result.

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 would be 3, but the description adds conditional semantics the schema cannot express: an item without id is an add requiring company, role and status, while an item with id mutates, with supplied fields replacing stored ones and null clearing optionals. The addUpdates/removeUpdates log mechanics and the status-change-to-log rule are likewise only in the prose.

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 (store) and resource (job applications) with batch scope ('many in one call'), then enumerates the three jobs it does: keeping a sent application, updating status, and importing applications kept elsewhere. It also separates itself from the career record explicitly, so an agent can distinguish it from save_career_record and list_career_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?

Gives clear conditions for use (when an application is sent, when its standing changes, when importing from elsewhere) and spells out when the save is refused (unknown id, missing field on a new entry, a value or the total over its limit). It does not name a sibling alternative for the case where the agent should be reading rather than writing, so it stops short of explicit routing.

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

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

Annotations already flag destructive=true, idempotent=false, but the description goes well beyond: it discloses optimistic concurrency (refused when the record changed since baseVersion), refusal on unknown paths or schema violations, the atomicity guarantee ("a refused save stores nothing"), that unknown fields are silently dropped, null removes a target, and that out-of-range indices append. These are precisely the destructive and non-idempotent behaviours an agent must anticipate.

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

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

The purpose is front-loaded, but the body is a dense run of semicolon-chained clauses ("...indexes from one past a list's last item add items there, in turn, a null value removes what the path names, and no path lies inside another") that forces re-reading. Nearly every clause carries information, but paragraph-level structure is poor for a description of this length.

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 tool with an enormous nested record schema and no output schema, the description does the heavy lifting: it defines the change model, the refusal model, and describes the return shape ({version, stored, changed, hints}) in enough detail to be usable. The one gap is routing relative to the other write/import/restore siblings.

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, and the description adds real meaning the schema does not: path grammar (header, a whole section, comments[3], roles[0].projects[2]), append-on-out-of-range-index, null-for-delete, and the no-overlapping-paths constraint. It also explains baseVersion's role and what the note is for, though the note's purpose is largely restated from 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: "Store changes to the career record", and specifies that changes are path/value pairs against a baseVersion. An agent knows exactly what operation this is. However, it never names the near neighbours (import_career_record, restore_career_version) that also write the record, so the distinction is by inference rather than stated.

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

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

Usage is implied by the mechanics (supply baseVersion from get_career_record, paths from the returned record), which effectively tells an agent when this tool is applicable. But there is no explicit when-to-use versus import_career_record or restore_career_version, and no statement of prerequisites such as needing a fresh read first, which is exactly the situation where an agent would pick the wrong sibling.

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

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

Annotations already cover readOnly, idempotent, non-destructive and closed-world, so the bar is lower, yet the description adds genuinely useful behavior: it renders an interactive card with buttons that copy pasteable requests, and it returns a specific one-line fact set (version, save time, comment count, kept applications by status, noResponse count). That is real disclosure beyond the structured fields, though it does not say how statuses are enumerated or what the card renders on non-client surfaces.

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

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

The purpose is front-loaded, but the middle clause — 'a card in the conversation on clients with interactive views' — is grammatically tangled and takes effort to parse, and the description runs long for a zero-parameter tool. Roughly half the text earns its place; the rest could be tightened without losing meaning.

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

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

With no output schema, the description carries the burden of describing the return value, and it does so concretely by enumerating the facts in the summary line. Annotations cover the safety profile and there are no parameters to document, so the only shortfall is that terms like 'kept' and 'noResponse' are used without definition.

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

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

The schema takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly implies the tool needs no input to produce its summary.

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 ('Show the person Graphlog Career's home') and clarifies that this renders an overview card plus a one-line facts summary, so the agent knows it is a dashboard-style read rather than a record fetch. It never contrasts itself with close siblings like show_career_record or get_career_record, which is the remaining gap.

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 one concrete trigger: 'It serves a message that is just "Graphlog"', which tells the agent when this tool is the expected handler. Beyond that there is no guidance on when to prefer it over list_career_applications or get_career_record, and no exclusions or prerequisites are 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?

Beyond the annotations, the description explains the UI behavior, what sections appear, that edits happen inside the opened view, that each save creates a new version, and what is returned. It also covers the fallback HTML output for clients that do not show interactive views.

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 a clear first sentence, but it becomes wordy and nested, especially around the card/view behavior. Some phrasing is redundant, such as 'Show the person their whole career record. Calling it shows it to them.'

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

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

With no parameters and no output schema, the description carries the burden well: it explains the interactive display, the versioned editing behavior, and the returned summary plus HTML fallback. An agent has enough information to understand both the side effects and the output.

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

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

The tool takes no parameters, and schema coverage is complete, so there is nothing parameter-specific to clarify. The baseline for a zero-parameter tool is 4.

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

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

The description states a specific verb and resource: 'Show the person their whole career record.' It clearly explains what calling the tool does, but it does not explicitly distinguish it from siblings such as get_career_record or check_career_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?

It gives clear usage context: 'It serves a request to see their record, and their check that the record is true and complete.' It does not, however, state when not to use it or name alternative tools for similar requests.

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