Civify

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description aligns by framing this as a 'check'. It adds useful specificity by naming what is being verified (30-day unwatermarked pass and unlimited edits), but it does not add additional behavioral details such as authentication needs, response shape, or error 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?

The description is a single compact sentence that starts with the action verb and the target resource. Every word adds relevant meaning, 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?

For a simple read-only entitlement check with one required parameter and an output schema present, the description is sufficiently complete about what is being checked and what the tool does. It could add a brief note about when this entitlement status matters or what the output indicates, but the existing schema and annotations cover the remaining operational context.

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

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

Schema description coverage is 100%, with resume_id already described as 'Resume UUID or ID', so the structured schema carries the parameter meaning. The description adds only the context of 'specific resume' and the entitlement condition, but not anything beyond what the schema already provides.

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 clearly identifies the verb ('check'), the resource ('a specific resume'), and the exact condition being verified ('active 30-day unwatermarked pass and unlimited edits'). It is immediately distinguishable from siblings like civify_purchase_cv_pass or civify_generate_pdf, since it is a read-only entitlement status check.

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

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

The description implies the tool should be used when you need to know whether a resume has an active pass, but it gives no explicit when-to-use guidance, no prerequisites, and no comparison to alternatives such as civify_purchase_cv_pass. The agent is left to infer when this check is the right 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 readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds only 'high-fidelity' and 'template engine,' which describe output quality and mechanism, not deeper behavioral traits such as file handling or overwrite semantics; it does not contradict any annotation.

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 sentence front-loads the action and output, then adds the key input and mechanism without redundancy or filler. Every phrase 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?

With detailed parameter descriptions, defaults, annotations, and an output schema, the definition supplies everything an agent needs to call the tool correctly. The description itself is short but combines with structured metadata to cover the tool's purpose, inputs, and safety profile.

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 each parameter has a meaningful description with defaults and examples for color, filename, and template. The description's mention of 'structured resume data' and 'template engine' lightly echoes resume_data and template but adds no semantic information beyond the schema.

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

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

The description uses a specific action pair — 'Render and generate a high-fidelity PDF' — with an explicit input source ('structured resume data') and engine. It is clearly distinct from sibling tools such as civify_parse_cv, civify_tailor_cv, and civify_score_ats, none of which produce a PDF.

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 'from structured resume data' makes the precondition clear: this tool should be called when fully structured resume JSON is available and a rendered PDF is needed. It does not name alternative tools or state when not to use it, but no sibling tool offers the same PDF-generation capability.

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 readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable context about the specific data returned (subscription tier, token balance, CV credits), and implies the need for an authenticated session. It does not mention potential errors or side effects, but the read-only nature is well-covered.

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 a single, front-loaded sentence that directly states what the tool does and what it returns. No filler or redundant phrasing; every word 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?

The tool is simple with one optional parameter, an output schema is present, and the description lists the key returned data. It is complete enough for an agent to understand the call's purpose and expected output, though it doesn't explicitly mention authentication prerequisites or error handling, which are minor given the output schema and read-only nature.

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%, with the single optional api_key parameter fully described in the schema. The description adds no additional meaning about parameters, so it meets the baseline of 3 without further contribution.

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 ('Get') and the resource ('current authenticated user account profile') plus the exact data returned (subscription tier, token balance, CV credits). It clearly distinguishes from siblings like civify_check_cv_entitlement and civify_get_pay_per_cv_pricing, which target different concerns.

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

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

The description does not provide any when-to-use guidance or mention alternative tools. While the purpose is clear, there is no explicit instruction on when to choose this tool over siblings like civify_check_cv_entitlement or civify_set_api_key, leaving the agent to infer usage context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds two behavioral facts beyond annotations: the endpoint is intentionally public and requires no authentication. It also clarifies exactly what pricing data is returned. No contradiction exists, and the added context meaningfully supplements the structured hints.

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

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

The description is a single, compact sentence that front-loads the core purpose and places the return-content breakdown in parentheses. Every phrase earns its place, with no redundant or vague 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 no-parameter, read-only, idempotent pricing endpoint with an output schema available, the description is fully sufficient. It tells the agent exactly what will be returned glinted and explicitly removes the auth ambiguity that could be inferred from sibling tools requiring login. Nothing needed 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?

The tool has zero parameters)Skip, input schema coverage is effectively 100%, and there is nothing to document. The baseline for zero params is 4, and the description appropriately focuses on output content instead of parameter details, which is the right division of labor.

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 'Get' with a precise resource: 'public localized Pay-Per-CV pricing', immediately listing concrete components (USD base price, converted EGP regional pricing, exchange rates, entitlement details). It also distinguishes itself from siblings by stating 'Public, no auth required', making its role among purchase/entitlement tools unmistakable.

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

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

The description provides clear context with 'Public, no auth required', signaling that this tool is appropriate for unauthenticated pricing lookups and not for actions like purchase_cv_pass or check_cv_entitlement. However, it does not explicitly name an alternative or state a when-not-to-use condition, so it falls just short of full guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the context that the data comes from the candidate's Civify Kanban board, which is useful. However, it doesn't disclose return format, pagination, or whether the list is ordered, but with annotations covering the core behavioral traits, 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 description is a single, clear sentence with no wasted words. It front-loads the action ('List') and the resource ('tracked job applications'), and the source ('Civify Kanban board') is included efficiently.

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 read-only list tool with one optional parameter and a full output schema, the description is nearly complete. It could mention that the list is from the candidate's own board, but that's already implied by 'candidate's Civify Kanban board.' The annotations cover safety, and the output schema covers return values, so nothing critical 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%: the only parameter, api_key, is described as 'Optional API key override.' The description adds no additional parameter semantics beyond what the schema already provides. Baseline 3 is correct when the schema fully documents the parameter.

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

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

The description clearly states the verb 'List' and the resource 'tracked job applications' from the candidate's Civify Kanban board. It distinguishes itself from siblings like civify_track_application (which adds an application) and civify_get_account (which retrieves account info), though it doesn't explicitly name alternatives.

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

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

The description implies usage context: it lists tracked applications from the Kanban board, so an agent can infer it's for reading the candidate's application tracking data. However, it doesn't explicitly state when to use this tool versus alternatives like civify_track_application or civify_get_account, nor does it mention any exclusions or prerequisites.

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 are all false and provide little behavioral information, so the description carries the burden. It usefully discloses that the tool 'automatically exchanges JWT tokens for a personal API key and activates it for the session,' revealing side effects beyond a simple login. This is meaningful transparency, though it stops short of explaining failure modes or key persistence 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?

The description is two sentences with no filler. The core action is front-loaded, and the second sentence adds important behavioral context efficiently. Every phrase 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 two-parameter login tool with an output schema, the description covers the essential flow, side effect, and session activation. It is slightly incomplete in not offering usage direction against sibling authentication tools, but an agent can still invoke it correctly. The presence of an output schema means return values do not need to be described.

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

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

Schema description coverage is 100%, and the schema already defines identifier as 'email address or username' and password as 'Account password.' The description mostly restates these meanings, adding no significant new semantic detail beyond confirming the login use case. Baseline 3 is appropriate because the schema does the heavy lifting.

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 clear, specific action: 'Sign in to Civify with email/username and password.' It also describes the unique post-login behavior (JWT exchange for a personal API key), which clearly distinguishes it from register, logout, and set_api_key siblings. There is no ambiguity about what the tool does.

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 context is implied: use this when a user has credentials and needs an authenticated session with a personal API key. However, it does not explicitly contrast with alternatives such as set_api_key for users who already have a key, or register for new accounts. The guidance is present but left mostly 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 indicate idempotentHint=true and destructiveHint=false, and the description adds meaningful behavioral detail: it clears 'active authentication credentials' and limits the effect to 'this session.' This goes beyond the structured metadata without contradicting it.

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

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

The description is a single, front-loaded sentence with no filler or redundant information. Every word adds meaningful context about the action and its scope.

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 logout tool with annotations covering idempotency and destructiveness, plus an output schema, the description fully covers the information an agent needs to select and invoke it correctly. The side effect and session scope are both explicit.

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 has zero parameters, so parameter semantics are fully handled by the empty schema. The baseline of 4 applies because there are no parameter semantics for the description to clarify.

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: 'Log out and clear active authentication credentials from this session.' This clearly distinguishes the tool from sibling authentication tools like civify_login or civify_register.

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

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

The description provides clear context by scoping the action to 'this session' and identifying what gets cleared, so an agent knows when ending an authenticated session is relevant. It does not explicitly name alternatives or exclusions, but the operation is intuitively distinct from login and registration.

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 idempotentHint=true. The description adds the fact that it exports a new PDF, but does not disclose whether the original file is modified or any side effects. It does not contradict 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?

A single sentence that is front-loaded with the core action and output, with no wasted words. It is appropriately concise.

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 tool's simplicity, the presence of an output schema, and annotations covering safety, the description is adequate. It clearly defines the input type (CV) and output format (PDF), though it could mention authentication or file handling nuances.

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 four parameters are already documented. The description does not add meaningful semantics beyond what the schema provides, such as clarifying the api_key requirement or output_path behavior.

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 clearly states the verb (sanitize/redact), resource (CV document), and output (anonymized PDF), distinguishing it from sibling tools like parse or tailor.

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

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

The description implies usage (sanitize PII) but does not explicitly state when to use this tool versus alternatives or any exclusions. It lacks guidance on prerequisites like authentication or when not to use it.

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 via readOnlyHint, idempotentHint, and destructiveHint. The description adds accepted document types and output contents, but it does not explain failure modes, authentication needs, or the 'image' input claim that is not reflected in the schema.

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 a single, front-loaded sentence with no filler. It conveys the action, resource, input formats, and output content efficiently.

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 rich input schema and the presence of an output schema, the description is largely complete for a parse operation. It falls slightly short by not addressing the image-input discrepancy or clarifying where this tool fits relative to the CV workflow 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 description coverage is 100%, so each parameter is already documented. The description adds no parameter-level meaning and even mentions 'image' support, while the schema's file_base64 parameter only describes PDF/DOCX.

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 ('Parse') and resource ('resume document') and enumerates the output fields (contact details, work experience, education, skills, projects). This clearly distinguishes it from siblings like civify_score_ats or civify_mask_pii.

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 guidance on when to use this tool versus alternatives such as civify_score_ats, civify_tailor_cv, or civify_mask_pii. The description only defines what the tool does, leaving the agent to infer the appropriate context.

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

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

Annotations already indicate readOnlyHint=false, openWorldHint=true, and idempotentHint=false, so the risk profile is partially covered. The description adds that checkout returns a payment URL, invoice ID, and amount, but it does not elaborate on side effects such as invoice creation, gateway auto-resolution, or wallet-specific prerequisites. This is acceptable but not richly transparent.

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

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

The description is two short sentences with no filler. It front-loads the primary action and immediately states the return values, making it easy for an agent to parse and act on quickly.

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

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

For a 7-parameter payment tool, the description plus the fully documented schema and output schema cover the essential invocation details. It lacks an explicit warning that this initiates a non-idempotent financial checkout, but annotations already signal that. Overall, the definition is sufficient for correct tool selection and invocation.

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

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

Schema description coverage is 100%, so the parameter semantics are already fully documented in the schema. The description only lightly reinforces the product choice ('single CV or 3-pack') and does not add meaning beyond the structured field descriptions. 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 clearly states the specific action ('initiate checkout'), the resource ('Pay-Per-CV unlock pass'), the available variants (single CV or 3-pack), and the expected outputs (payment URL, invoice ID, amount). This distinguishes it from sibling tools like civify_get_pay_per_cv_pricing or civify_check_cv_entitlement.

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 use case is implied: this is the tool for starting a Pay-Per-CV purchase. However, the description does not explicitly say when to prefer it over alternatives, nor does it mention related steps like checking entitlement or pricing first. It provides clear purpose but no exclusionary guidance.

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

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

Beyond the annotations, the description discloses the conditional behavior that an API key is provisioned when auto-verification is active. This is meaningful behavioral context for an agent. It does not detail failure modes or email verification flows, but the annotations already cover the basic operational hints.

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

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

Two sentences contain only necessary information: core purpose is front-loaded, and the key conditional behavior follows immediately. No wasteful or redundant wording.

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 registration tool with four documented parameters, an output schema, and basic annotations, the description provides the essential caveat about auto-verification and API key provisioning. It could mention what happens when auto-verification is inactive, but the description is largely complete for selecting and invoking the tool 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%, and all parameters are already documented in the input schema. The description does not add parameter-specific meaning, but given the high schema 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?

Clearly states the action 'Register' and the resource 'brand-new Civify account', distinguishing it from sibling tools such as civify_login by emphasizing new account creation. The description is specific and unambiguous about scope.

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 'brand-new' clearly implies this is for new users, which provides context for when to use it. It does not explicitly state that existing users should use civify_login or that the tool is not for authentication of existing accounts, so it stops short of full exclusion guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the useful behavioral detail that no job description is required, which clarifies the tool's non-dependency. It does not add further behavioral traits like rate limits or error handling, but given the annotation coverage, the description's modest addition is acceptable. No contradiction with 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 a single, well-structured sentence that front-loads the core purpose and then succinctly covers the input modalities. Every phrase adds value—'without needing a job description' is a key differentiator, and the enumeration of input types is efficient. No fluff 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?

The tool has six parameters with full schema descriptions and an output schema (though not shown), so the description does not need to explain return values. It covers all input paths and the specific use case (no JD required). For an agent deciding how to call it, the description combined with the schema is sufficient; nothing critical is missing. A minor gap is that it doesn't hint at the output structure, but the output schema presumably covers that.

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 input schema has 100% description coverage, so every parameter already carries a clear explanation (e.g., 'Base64 encoded content of the resume document', 'Plain text or markdown content'). The tool description does not add extra meaning beyond what the schema provides; it merely summarizes the input choices. With high schema 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?

The description states a specific verb ('Calculate'), a clear resource ('ATS compatibility score and structural audit for a resume'), and a distinct scope ('without needing a job description'). It distinguishes itself from sibling tools like civify_parse_cv (which parses) and civify_tailor_cv (which tailors) by focusing on scoring. The input flexibility (file path, JSON, text) is also mentioned upfront, making the purpose unmistakable.

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

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

The description provides clear context on when to use the tool (when no job description is available) and even gives environment-specific guidance on which input parameter to choose (resume_text for AI agents, file_base64 for remote/cloud, server_file_path for local). However, it does not explicitly name alternatives or state when NOT to use it (e.g., when a job description is available, one might use a different tool). This is good but lacks explicit 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 readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, and the description is fully consistent with them (scraping is a non-destructive, repeatable read of an external resource). The description adds useful context on supported sources and extracted fields, but discloses no failure modes — an agent gets no warning that postings may be expired, login-walled, or blocked by bot protection, which is significant for a scraper that hits third-party sites. No annotation contradiction.

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 sentence that front-loads the action verb and compacts the output fields and supported sources efficiently. Every element earns its place; there is no filler, no repetition of the title, and no redundant restating of schema 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?

An output schema exists, both parameters are fully documented, and annotations cover read-only/idempotent/non-destructive safety, so the description need not restate return values or safety. It covers what is extracted and from which sources. The main remaining gap is failure-mode transparency for a network-touching scraper (expired postings, restricted pages, rate limits), which is the one thing that could surprise an agent during real use.

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% (url: 'The URL of the job posting'; api_key: 'Optional API key override'), so the baseline is 3. The description adds meaning beyond the schema by enumerating acceptable URL sources (LinkedIn, Greenhouse, Lever, Ashby, Wuzzuf), helping an agent judge whether a given URL is a valid input. It adds nothing for api_key, but the schema already describes it fully.

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 ('scrape and extract'), names the resource ('job description from a job URL'), enumerates the extraction targets (job description, company name, requirements, responsibilities), and lists supported platforms (LinkedIn, Greenhouse, Lever, Ashby, Wuzzuf). This clearly distinguishes it from siblings like civify_parse_cv, civify_score_ats, and civify_tailor_cv, which operate on CVs rather than job posting URLs.

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 context is implied: when an agent has a job posting URL from one of the listed platforms, this tool scrapes it. However, the description never explicitly states when-not-to-use it or names alternatives among the 16 siblings; the appropriate-use signal must be inferred from the URL source list rather than stated directly.

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 provide idempotentHint=true and destructiveHint=false. The description adds the useful behavioral detail that the key is 'validated with the server immediately', implying a network call and possible error on invalid keys. No contradiction with annotations.

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

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

Two short sentences with the primary action front-loaded and a relevant side effect immediately after. No filler or redundancy.

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

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

For a single-parameter, idempotent, non-destructive setter with an output schema, the description covers the action, session scope, and validation behavior. Nothing needed for correct invocation is missing.

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

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

Schema description coverage is 100% and the single api_key parameter is fully documented with type and format hint. The description adds no further parameter 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?

The description uses specific verbs 'Set or switch' and names the resource 'active Civify API key', scoped to 'this agent session'. This clearly distinguishes it from sibling tools like civify_login or civify_logout.

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 'for this agent session' gives clear context for when this tool is appropriate. It doesn't explicitly mention alternatives or exclusions, but the intended usage scenario is evident.

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 readOnlyHint=false and destructiveHint=false, so the tool is a non-destructive but mutating operation. The description adds that it uses AI and generates new content, which implies external processing and potential API calls. However, it does not disclose side effects like cost, whether the original resume is preserved, or any rate limits. With minimal annotations, the description provides basic transparency but lacks deeper behavioral context.

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 a single, well-structured sentence that leads with the core purpose and then lists key features. It is front-loaded, contains zero filler, and every clause adds value. The format is ideal for quick agent comprehension.

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 tool's complexity (12 parameters, output schema present), the description is reasonably complete. It conveys the essential purpose and deliverables. The output schema covers return values, and the schema covers parameter details. It does not mention prerequisites like API key requirements or the distinction between local vs. remote file inputs, but these are addressed in the schema. Minor gaps exist, but the description is sufficient for an agent to call the tool 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%, so every parameter is already documented in the schema. The description's mention of 'optional cover letter' merely echoes the generate_cover_letter parameter. It does not add new meaning or clarify parameter interplay beyond what the schema already provides, so 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?

The description states a specific verb and resource ('Tailor a candidate's resume against a target job description') and enumerates concrete outputs (optimized bullet points, matching skills, ATS keyword audit, optional cover letter). This clearly distinguishes it from siblings like civify_score_ats (which only scores) and civify_parse_cv (which parses), leaving no ambiguity about what the tool accomplishes.

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

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

The description implies its usage context by listing features (tailoring, ATS audit, cover letter), but it does not explicitly state when to choose this tool over alternatives. For instance, an agent wanting just an ATS score might not know to use civify_score_ats instead. No exclusions or when-not conditions are provided, so guidance is implicit rather than explicit.

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

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

Annotations already indicate a non-read-only, non-idempotent write; the description aligns with that and adds the destination ('Kanban tracker board'). It does not disclose consequences like duplicate entries on repeat calls or whether an existing application can be updated, so it adds limited behavioral context beyond 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?

Single sentence, grammatically direct, with no filler. It front-loads the action before the destination, and nothing needs to be cut or rearranged.

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 6-parameter create-style write tool with full schema documentation, annotations, and an output schema, the core invocation contract is clear. It lacks explicit when-to-use guidance and duplicate/update behavior, but these are not fatal given the schema and sibling list.

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 input schema provides 100% descriptions for all six parameters, so the baseline applies. The description adds no meaning about company_name, job_title, or status beyond what the schema already documents.

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

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

Clearly states a specific action ('Record') and resource ('job application') plus destination ('Civify Kanban tracker board'), which distinguishes it from civify_list_applications and other CV/candidate siblings. The title 'Track' is clarified by the description.

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?

No statement of when to use this tool or when to prefer an alternative. It never mentions civify_list_applications for viewing existing applications or conditions such as having a logged-in account or API key. The only context is the destination board, which implies but does not explain usage.

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 provide no safety or idempotency hints, so the description carries the burden. It discloses the sequence dependency and the code channel, but it does not mention that the OTP may be single-use, that failed attempts could invalidate it, or that verification establishes an authenticated session.

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 states the operation, the input, and the prerequisite with no filler or redundancy. Every word 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 low-complexity tool with one required parameter and an output schema, the description plus schema is sufficient for correct invocation. It states the prerequisite and what to submit; the only missing details are edge-case behaviors like failure handling, which are not critical here.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces that 'code' is the OTP sent via email, but it adds little beyond what the schema already documents for the optional username 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 uses the specific verb 'Complete' tied to two-factor authentication and identifies the exact artifact being submitted (the OTP code). It clearly separates this from civify_login, which initiates authentication, and from other account-related sibling 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 'after login' gives clear sequencing context, telling an agent this is the post-login 2FA step and implying civify_login should happen first. It does not explicitly name alternatives or exclusion conditions, but the context is unambiguous enough.

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