Carbon

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

Annotations already cover the safety profile (write, non-destructive, non-idempotent). The description adds genuinely new behavior: 'Only what the ad states is filled in' (partial extraction from a pasted/scraped ad) and 'The draft is private until you post it' (staged visibility). Both are traits 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?

Four short sentences, front-loaded with the core action, and each adds something (input modes, extraction scope, visibility). No padding, though it could tighten by naming the alternative explicitly.

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?

Purpose and behavior are well covered, and there is no output schema to explain. However, for a 13-parameter tool with 0% schema coverage, the near-total silence on per-parameter meaning leaves an agent guessing about required context, currency format, and the confirm flag.

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

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

Schema description coverage is 0% across 13 parameters, so the description must carry the burden. It loosely maps to title, description, ad_text, and ad_url, but leaves years, skills, location, salary_min/max, location_type, employment_type, salary_currency, and especially the unexplained 'confirm' flag entirely undocumented.

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 ('Saves a new role as a draft') and the 'draft...until you post it' framing implicitly separates it from post_role. It does not name the sibling outright, so an agent still has to infer that the draft/post distinction is the divider, but the purpose itself is unambiguous.

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

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

It lists three invocation modes ('Give a title and details, paste a job ad, or pass a link to one'), which tells the agent how content can be supplied, but gives no when-to-use vs alternatives guidance and never mentions when to prefer post_role or list_roles. Usage is implied 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 readOnly, idempotent, closed-world and non-destructive, so the safety profile is covered. The description adds genuinely non-annotated behavior: the exact field set returned and an explicit exclusion list (contact details, CV files, rates), which prevents the agent from expecting PII or compensation data. No auth or rate-limit context, but that is not needed for a simple read.

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. The scope statement leads and the returned-field inventory follows, so the most important information is front-loaded.

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

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

For a two-parameter read tool with no output schema, the enumeration of returned fields effectively substitutes for a return-value spec, and the exclusion clause closes the main expectation gap. Nothing an agent needs in order to call this correctly is missing.

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

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

Schema description coverage is 0%, so the description carries the burden for role_id and application_id. 'One applicant on one of your roles' does imply the two-part key (a role plus that applicant's application to it), which is real semantic value, but it gives no format, ID source, or distinguishing detail for either parameter.

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

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

The description names a specific verb ('Summarises') and a precisely scoped resource ('one applicant on one of your roles'), then enumerates the exact contents returned (stage history, source, headline, skills, experience, location, test/interview status, team notes). This clearly separates it from list_applicants (plural listing) and get_talent_profile (global talent, not role-scoped) without the agent 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?

Usage is only implied: the scoping to a single role/application tells the agent this is a per-application drill-down rather than a search. The note that contact details, CV files and rates 'stay in the portal' draws a data boundary but names no sibling tool or alternative, so the agent gets no explicit when-to-use/when-not routing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds the returned field inventory, which is useful context absent an output schema, but it discloses no additional behavioral traits such as auth requirements, error behavior, or rate 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?

A single front-loaded sentence with the verb and resource first and the field inventory after. The enumerated list of nine fields is slightly long but each item is informative for a detail-fetch tool with 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?

With no output schema, the description usefully enumerates what is returned, and annotations cover the safety profile, so an agent has what it needs to call the tool. It falls short on how to obtain a role_id and what happens if the ID is invalid.

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 role_id parameter has 0% schema description coverage, so the description must compensate and it does not — role_id is never mentioned, nor is its UUID format or required status. 'One of your roles' hints at identification but adds no usable syntax 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?

States a specific verb ('Shows') and resource ('one of your roles') and enumerates the fields returned in full. The singular 'one of your roles ... in full' implicitly distinguishes it from list_roles, but no sibling is named explicitly.

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

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

Usage is only implied: fetch the complete detail for a single role. There is no explicit when-to-use guidance, no statement of when to prefer this over list_roles, and no mention of prerequisites such as needing a valid role_id.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds return-shape context that annotations cannot supply: the record contains the same fields as search results plus a full overview, which is meaningful given no 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?

A single front-loaded sentence with no filler. Both clauses earn their place: one establishes identity/scope, the other establishes return content.

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

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

For a one-parameter read tool with full annotations, the main remaining gap is the return shape, which the description partially covers by relating it to search fields plus an overview. Missing are failure behavior (unknown id) and any note on field expansion, but nothing critical to calling it correctly is absent.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it does: it explains that profile_id is an identifier obtained from search output. That addresses provenance but not format details (e.g., string shape), so it falls just short of fully compensating for the coverage gap.

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

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

States a specific verb (Shows), resource (talent catalog profile), and cardinality/scope (one, by id), which clearly separates it from the list-style siblings. It references 'search' rather than naming the exact sibling 'search_talent', so the differentiation is slightly weaker than it could be.

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 'by the id that search returned' implies the intended workflow (call search first, then fetch a specific profile) but never states when to prefer this over search_talent or what to do if the id is unknown. Usage is implied rather than explicitly prescribed, and no exclusions are given.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine value by bounding scope — contact details and CVs stay in the carbon.talent portal — which tells the agent what this call will NOT return. It says nothing about pagination or the cursor/limit behavior despite the tool being paginated.

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 what is listed and followed by the useful scope caveat. No filler, though the second sentence could be folded in more economically.

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 five undocumented parameters, no output schema, and a paginated result set, the definition leaves the agent without the input semantics it needs. The scope note is helpful but far short of complete for a tool of this shape.

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

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

Schema description coverage is 0% across 5 parameters, so the description carries the full burden — yet it documents none of them. It never explains role_id, limit, stage filtering, cursor pagination, or include_rejected; 'stage' appears only as an output field, which is ambiguous against the input parameter of the same name.

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

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

States a specific verb (Lists) and resource (people who applied to / were added to one of your roles), plus the fields surfaced (stage, application date). It does not, however, distinguish itself from the sibling get_applicant_summary, which an agent must choose between.

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

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

There is no statement of when to use this tool versus alternatives such as get_applicant_summary, search_talent, or get_role, and no prerequisites or exclusions are given. Usage is only implied by the phrase 'one of your roles'.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered by structured data. The description adds the company-scoping constraint, which is genuinely useful context, but says nothing about pagination behavior despite limit/cursor parameters.

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

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

Two short sentences with no filler, and the scoping constraint is front-loaded right after the core action. Efficient, though it is arguably too terse given the undocumented parameters.

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, 0% parameter coverage, and an undocumented pagination scheme, the definition leaves an agent guessing about how to page results and how the status enum affects output versus filtering. For a list tool with three parameters, this is incomplete.

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

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

Schema description coverage is 0% across three parameters, so the description carries the full burden and fails it: it never explains limit, cursor pagination, or whether 'status' is a filter argument (the enum suggests it is, but the description reads as a returned field). This ambiguity could lead an agent to use status incorrectly.

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

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

States a specific verb and resource ('Lists your company's roles') and describes the returned fields (status, location, applicant counts), which clearly separates it from the singular get_role. It does not explicitly name sibling alternatives, so it stops short of a 5.

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

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

The phrase 'Only your company's roles are included' implies when this tool is appropriate (scoped to the caller's own company), but there is no explicit statement of when to use it versus get_role, search_talent, or why you would list instead of fetch one. Usage is implied 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 the safety profile (readOnly=false, destructive=false, idempotent=true, openWorld=true), and the description adds genuine behavioral context beyond them: the applicant receives the same notification the portal sends, and hiring is deliberately excluded because of a fee. It does not, however, explain what the undocumented 'confirm' flag guards against.

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 action and stages before the secondary portal/fee note. The fee sentence is slightly tangential but still earns its place as routing context; no 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 4-parameter mutation with no output schema and zero schema coverage, the description covers the headline effect (the portal notification) but omits what 'confirm' does, what the parameters reference, and what the caller gets back on success or failure. Adequate but with clear gaps.

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

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

Schema description coverage is 0% for 4 parameters. The description only restates the stage values, which are already given as an enum, and says nothing about role_id, application_id, or the 'confirm' boolean, leaving half the parameters completely undocumented.

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 precise verb+resource (moves an applicant's stage) and enumerates the exact target stages, so the agent knows exactly what the call accomplishes. No sibling tool (list_applicants, get_role, post_role, etc.) performs this action, making it cleanly distinguishable.

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

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

Implies the tool is for stage transitions while hiring itself belongs in the portal ('Hiring is done in the portal because it can involve a fee'), which is a soft when-not note. But it never states explicit prerequisites (e.g., must the role be posted, must there be an application) or names a real alternative tool, leaving the routing guidance partial.

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

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

Annotations already declare readOnly=false, idempotent=true, destructive=false and openWorld=true, so the description is not required to carry the safety profile. It adds genuinely useful context beyond the annotations: a review step by the Carbon team before going live, and an email notification on publish. It does not, however, confirm the idempotency claim or describe what happens to the role while it is under review.

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 action, then the review consequence, then the notification. Every sentence earns its place with 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?

For a simple one-required-parameter mutation with annotations covering the safety profile and no output schema, the core behavior is covered. Gaps remain around the unexplained `confirm` flag and whether the action can be undone or what state the role enters during review.

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

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

Schema description coverage is 0% and the description explains neither parameter. "one of your draft roles" loosely implies role_id identifies the draft, but the boolean `confirm` parameter is entirely unexplained in both the schema and the description, leaving a real ambiguity for a mutation 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?

The description states a specific verb (submits) and resource (a draft role) with a clear outcome (publishing). It is readily distinguishable from the sibling create_role_draft, since this tool acts on an existing draft rather than creating one.

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?

"Submits one of your draft roles" implies the precondition that a draft must already exist, which implicitly routes the agent away from create_role_draft. However, no alternatives are named explicitly and no when-not-to-use guidance is given.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and a closed-world scope, so the safety profile is covered. The description adds one genuinely useful behavior: results are partially anonymized ('first name and last initial'). It says nothing about pagination limits, empty-result behavior, or cost, so it only modestly exceeds the annotation bar.

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

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

Two sentences, zero filler, with the search dimensions front-loaded before the result-shape sentence. Nothing could be cut without losing information.

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

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

There is no output schema, so the description's enumeration of returned fields is necessary and welcome. However, with 0% schema coverage on 6 params, pagination (page/page_size, capped at 25) and result-set limits are left entirely undocumented, which is a real gap for a search tool.

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

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

Schema description coverage is 0% across 6 parameters, so the description must compensate. It maps meaning onto four of them (keywords→q, skills, years, location) but says nothing about page or page_size, and the schema's maxItems/maxLength/min-max bounds are undocumented anywhere. Partial compensation only.

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 ('Searches the carbon.talent talent catalog') and enumerates the filterable dimensions (skills, years, location, keywords), which distinguishes it from a single-record fetch. It does not, however, name the sibling it contrasts with (get_talent_profile) or state that it returns multiple candidates.

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 filter list implies when the tool is useful ('find talent matching criteria'), but there is no explicit when-to-use versus when-not, and no routing guidance to get_talent_profile for a specific person or to list_applicants for a role pipeline. 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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without the description. The description adds that the result is the account 'you are connected as' and highlights email-verification status, which is mildly useful context, but there is no pagination, caching, auth-requirement, or error behavior disclosed.

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

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

A single front-loaded sentence naming the action first and the returned fields second, with no filler or redundancy.

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

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

With no parameters, full annotation coverage, and an output schema that already documents the return shape, the description need not explain return values further. It is complete for correct invocation, though it could have added one line on when an agent should reach for it versus other tools.

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

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

The schema declares zero parameters (100% coverage), so there is nothing for the description to compensate for. Baseline 4 applies for a parameterless 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 operation on a specific resource — showing the connected carbon.talent hiring account — and enumerates the fields returned (name, email, company, email-verification status). This makes it easy to tell apart from the role/applicant siblings, though it never explicitly names or contrasts those 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?

Usage is implied by the identity-scoped nature of the tool (verify which account/session you are operating as), but there is no explicit when-to-use statement, no exclusions, and no mention of alternatives. Minimum viable for a zero-param tool.

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