jobctl

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

Annotations indicate readOnlyHint=false (mutation) and destructiveHint=false. The description adds value by explicitly stating that the tool creates a new application and returns possible-duplicate warnings, which is useful context beyond annotations. No contradictions observed.

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 remarkably concise, using 2-3 sentences to convey purpose, usage modes, and behavioral notes. It is front-loaded with the core action and contains no redundant information. Every sentence 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?

Given the tool's complexity (19 parameters, no output schema), the description adequately explains the two input modes, mentions required fields, and covers return value behavior. However, it could briefly indicate when to use specific structured fields (e.g., status, url) for completeness, but overall it is sufficient for an agent to use correctly.

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

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

With 74% schema description coverage, baseline is 3. The description adds significant value by explaining the raw parameter format in detail and indicating that 'company' and 'role' are required in structured mode (despite schema not marking them required). This helps the agent understand usage beyond schema constraints.

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 tool's purpose as tracking a new job application. It distinguishes two input modes (raw line or structured fields) and implies the action of creation. The tool name itself is self-explanatory, and the description reinforces it, differentiating it from siblings like update_application or list_applications.

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

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

The description provides usage guidance on how to input data (raw vs structured) and what to do on duplicate detection. However, it lacks explicit comparison to sibling tools like update_application for existing entries or list_applications for viewing, so the agent must infer context from the name alone. The guidance is present but not exhaustive.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false. Description adds that input is 'free-text' and 'multiline markdown', but no additional behavioral traits beyond that.

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 concise sentences plus an example. Front-loaded with purpose, no wasted words.

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

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

For a simple two-parameter tool with no output schema, the description fully covers what the agent needs: action, resource, input format, and example. No missing 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 has 0% description coverage, so description compensates by explaining 'free-text note' and giving an example with both parameters, clarifying that application_id is a UUID and text accepts multiline markdown.

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 action (append note) and resource (application timeline). Examples like 'recruiter call summaries' distinguish from sibling tools like add_application and log_interview.

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?

Provides specific use cases (call summaries, instructions, messages). Implicitly suggests when not to use (structured data should go to log_interview), but lacks explicit alternatives.

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

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

Beyond annotations (destructiveHint=true), description adds key details: replacement on new call, max size 100KB, and markdown format. No contradictions.

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 plus example, every sentence adds value. Front-loaded with purpose. 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 tool with 2 params and no output schema, description covers all: purpose, behavior, size limit, example. Leaves no ambiguity for correct 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?

With only 50% schema coverage, description compensates by explaining markdown purpose and size limit, and includes example showing both parameters. Application_id is only described via schema, but UUID format is clear.

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?

Description clearly states the tool attaches a markdown company analysis to an application, and distinguishes from siblings like add_note or attach_file by specifying it's for research and single document replacement.

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?

Description explains when to use (attach analysis for dashboard reading before interview) and implicitly when not (due to replacement behavior), but does not explicitly contrast with sibling tools.

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 indicate destructiveHint=true; description reinforces this by stating a new call 'REPLACES the previous one'. Adds behavioral details beyond annotations: max 5 MB size, supported formats (pdf/doc/docx/txt/md), MIME inference from filename. 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?

Description is 3-4 sentences, front-loaded with main action and purpose. Includes a concrete example call. Could be slightly more concise without the example, but structure is effective and easy to parse.

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

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

Covers input parameters and behavior well, but lacks any description of return values (no output schema). For a file upload tool, mentioning what is returned (e.g., success indicator or updated application) would improve completeness. Otherwise adequate for agent selection.

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

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

Schema description coverage is 40%; description adds meaningful context: clarifies kind enum values ('cv' or 'cover_letter'), explains data_base64 as base64-encoded bytes, and documents that filename extension infers MIME. Does not detail application_id format beyond schema's regex, but overall adds significant value.

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

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

Clearly states verb 'Attach or replace' and resource 'file on an application', specifies two kinds (cv, cover_letter). Explicitly differentiates from sibling tools like attach_analysis by stating when to call: 'whenever you generate a tailored CV or cover letter for an application'.

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

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

Provides explicit usage context: call when generating a tailored CV or cover letter. Mentions replacement behavior and constraints (one per (application, kind)). However, does not explicitly state when not to use or name alternatives like attach_analysis, leaving minor ambiguity.

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

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

Annotations declare readOnlyHint=true, and the description adds value by detailing what the tool returns (fields, contacts, timeline events, analysis presence). It does not disclose any potential side effects, which is appropriate for a read-only tool. No contradictions.

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 sentence that efficiently conveys the tool's output and related actions. It is front-loaded with the main purpose. Minor improvement could be breaking into two sentences for clarity.

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 no output schema, the description adequately explains the return content (fields, contacts, timeline events, analysis flag). It also mentions related tools for analysis retrieval. It does not cover potential pagination or limits on timeline events, but that is acceptable for a tool of this complexity.

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 has one required 'id' parameter with 0% coverage in description. The description adds no explanation of the parameter, despite low coverage requiring compensation. The schema itself provides type and format, but the description could have clarified how to obtain the application ID.

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 'Full detail of one application: all fields, contacts, recent timeline events, and whether a company analysis is attached.' It specifies the verb (get detail) and the resource (one application), and distinguishes from siblings like list_applications and attach_analysis.

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 alternatives for fetching analysis ('fetch it via the dashboard or attach_analysis to replace'), which indirectly guides when to use this tool vs. others. However, it does not explicitly state when not to use this tool or exclusion criteria.

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 (readOnlyHint=true) indicate no mutation. Description adds that it filters by due/overdue next_action_due, providing 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?

Two sentences, front-loaded with purpose, no 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?

Zero parameters and readOnlyHint annotation mean this simple filtered list tool is fully described in two sentences.

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?

No parameters (0 params), baseline score of 4 applies as description does not need to add parameter information.

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?

Description clearly states the tool returns applications with next_action_due today or overdue, distinguishing it from sibling tools like get_planned or list_applications by focusing on urgency.

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

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

Explicitly says to call when user asks 'what should I do today?' about job search. Implies urgency but doesn't explicitly state when not to use.

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=true, so safety is clear. The description adds behavioral details about what data is returned (interviews with attendees, links, actions). It does not mention error handling or edge cases, but for a simple read tool this is sufficient.

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 plus an example, front-loading key information without any wasted words. Every part contributes to understanding the tool's use and 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?

Although there is no output schema, the description lists the components of the return (time, attendees, links, actions). Combined with the read-only annotation and clear distinction from get_due, the description is fairly complete for a simple tool with one optional parameter.

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% with a clear enum description for range. The description provides an example call but does not add significant new meaning beyond the schema. Baseline 3 is appropriate as schema carries the parameter semantics well.

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 it returns scheduled interviews with time, attendees, meeting links, and actions falling due for a specified range. It distinguishes itself from the sibling tool get_due, making the purpose specific and 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?

The description explicitly advises when to use this tool: when users ask about plans, day/week overview, or before proposing a time. It also contrasts with get_due, noting that get_due only knows action deadlines, providing clear guidance on tool selection.

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=true. Description adds context about filter capabilities and view semantics, beyond what annotations provide. No contradictions.

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 concise sentences plus example. Front-loaded with purpose, then filters. Every sentence provides value without 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 5 parameters and no output schema, description covers the main filtering aspects. Missing pagination/limit details, but acceptable for a list tool. No return format but not required.

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 40%, but description compensates by detailing view values, search field (q), status list, and priority. Missing explanation for limit, but overall adds significant meaning beyond the schema.

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

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

Clearly states 'List job applications' with specific verb and resource. Distinguishes from siblings like get_application (single retrieval) and add_application (creation) by focusing on listing and filtering.

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?

Examples show typical usage patterns (e.g., filtering by view, searching). Explains view meanings ('active = default working set, archive = rejected/withdrawn/no-response'). Could explicitly state when to use alternatives like get_application, but overall clear.

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 (readOnlyHint=false, destructiveHint=false) indicate a non-destructive write operation. The description adds behavioral context by noting the 10-per-application limit and the syncing of next-interview date. No contradiction with annotations, and the additional details are helpful for understanding side effects.

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 well-structured with a clear lead sentence, followed by parameter details and an example. It covers all essential information without verbosity. The example is compact and illustrative. Every sentence contributes to understanding the tool's function and constraints.

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 has 6 parameters (83% schema coverage), no output schema, and moderate complexity, the description comprehensively covers inputs, constraints (max 10), side effects (date sync), and provides a concrete example. An agent can correctly invoke the tool based on this description alone.

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 83% with descriptions for most parameters. The description adds meaning by explaining links as 'prep materials' or 'meeting URL', attendees as 'who attends with profile link', and recap as 'short recap'. The example further clarifies parameter usage, adding value 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 clearly states it logs an interview for an application, specifying key fields (scheduled_at, status, attendees, links, recap) and a constraint (max 10 per application). It also mentions a side effect of syncing next-interview date, making the tool's purpose unmistakable. This distinguishes it from sibling tools like add_application or add_note.

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 by detailing what the tool does and its limit (max 10 per application). It provides an example that demonstrates typical use. While it does not explicitly state when to avoid this tool or mention alternatives, the context is clear enough for an agent to decide.

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 indicate readOnlyHint=false and destructiveHint=false. The description adds that 'Status changes are logged to the timeline automatically', which is a behavioral trait beyond the annotations. It does not mention other side effects, but the added context is valuable.

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 sentence plus an example, with no verbosity. Every word is functional, and the key 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?

Given the tool has 19 parameters and no output schema, the description covers the essential behavior (updates fields, logs status changes) and provides a working example. It does not explain return values or error handling, but the context is sufficient for a mutation tool.

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

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

Schema description coverage is 68%, meaning many parameters already have descriptions. The description adds guidance with an example and notes that match_notes should be saved 'here so it is not lost'. This adds value but does not fully compensate for the remaining undocumented parameters.

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 'Update' and the resource 'application', and distinguishes it from siblings like list_applications by specifying how to get the id. The example reinforces the purpose.

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 a prerequisite ('get the id from list_applications') and implicitly contrasts with add_application and list_applications. It does not explicitly state when not to use it, but the context is clear enough.

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