FoundRole — AI Job Search & Application Tracker MCP for Claude & ChatGPT

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

Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds useful behavioral details: returns pagination info, summary of job search, and a system_instruction for presentation. 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?

Three well-structured paragraphs: purpose, input parameters (bulleted), output description. Every sentence is necessary and concise. No fluff.

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 output schema exists (context signal), description adequately explains output structure (pagination, system_instruction). No rate limits or error handling mentioned, but not required for basic completeness.

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

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

Schema coverage is 100%, so baseline is 3. Description repeats parameter details but adds default for status ('all statuses') not in schema. Minor value added beyond 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?

Description clearly states 'Lists the authenticated user's job alerts across all subscription sources', specifying verb (list), resource (job alerts), and scope (all sources). This distinguishes it from sibling tools like job_alert_subscribe or job_alert_unsubscribe.

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 explicit guidance on when to use this tool versus alternatives (e.g., reminder_list, tracker_list). The description only lists parameters without explaining context 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?

The description discloses idempotency (though annotation already hints this) and output structure. It adds acceptable formats for job_search_id. It does not discuss error cases or permissions, but given annotations, it's 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 concise, with a clear front-loaded purpose, followed by input details, output, and idempotency note. No unnecessary text.

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, annotations, and output schema, the description covers purpose, input formats, output, and idempotency. It lacks details on error handling but is otherwise complete.

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 description adds value beyond schema by specifying acceptable formats for job_search_id (UUID or composite) and confirming defaults. Since schema coverage is 100%, it improves clarity.

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 subscribes the authenticated user to job alerts for a specific saved job search, using specific verb and resource. It distinguishes from sibling tools like job_alert_list and job_alert_unsubscribe.

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 explains the idempotent nature, allowing updates. It does not explicitly exclude alternatives, but the context of siblings is clear. Some guidance on when to use list vs subscribe would improve 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?

The description discloses key behavioral traits: it confirms the action is unsubscribed, is idempotent, and returns success even if the user was not subscribed. These details add value beyond the annotations, which only indicate destructiveHint: true. 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 concise with a clear Input/Output structure, and an idempotency note. It is well-organized and front-loaded. Minor redundancy (repeating 'Input:' and 'Output:' labels) could be trimmed, but overall efficient.

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 tool with one parameter, the description covers all necessary context: what it does, what input it expects, and what output to expect (confirmation, idempotent behavior). The output schema is present, so additional detail on return values is not required. Complete for an agent to invoke correctly.

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

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

Schema coverage is 100%, meaning the input schema already describes job_search_id as 'Job search UUID or composite job id...'. The description mirrors this but does not add new meaning beyond what the schema provides. 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 tool's purpose: 'Unsubscribes the authenticated user from job alerts for a specific job search.' It uses a specific verb ('Unsubscribes') and resource ('job alerts for a specific job search'), and distinguishes itself from siblings like job_alert_subscribe and job_alert_unsubscribe_all by targeting a single alert.

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 implicit usage context (e.g., when you want to unsubscribe from a specific alert), but lacks explicit guidance on when not to use it or alternatives. For example, it does not mention that to unsubscribe from all alerts, one should use job_alert_unsubscribe_all instead. No explicit when-to-use or when-not-to-use statements.

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?

Clearly states destructive nature (unsubscribes), idempotency (returns success even with no active alerts), and the confirm safety mechanism. Adds significant value beyond annotations by detailing idempotency and the guard rail.

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, focused paragraphs: purpose, input explanation, output and idempotency. Front-loaded with core action. No redundant or unnecessary sentences.

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

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

The description covers all essential aspects: purpose, required input, output behavior, and idempotency. With a simple schema and output schema referenced, the description is fully 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?

Schema coverage is 100%, so baseline is 3. The description adds context that confirm 'guards against unintended bulk unsubscribe', reinforcing the parameter's purpose beyond the schema description.

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 uses specific verb 'unsubscribes' with clear resource 'job alerts' and scope 'ALL' across all sources. Clearly distinguishes from sibling tool 'job_alert_unsubscribe' by indicating bulk action.

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 use case for bulk unsubscribe by stating 'ALL' and 'at once'. No explicit when-not or alternative mention, but the guardrail (confirm=true) provides usage context. Sibling tool names suggest alternatives.

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

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

Annotations are all false and provide little safety context, so the description carries the burden. It goes beyond the annotations by disclosing that FoundRole validates evidence, stores the client extraction separately, derives facts, and reports provenance. It also includes a caveat that analysis is not a guarantee. This is strong but doesn't fully clarify the permanence or user-visible side effects of storing the extraction.

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

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

The description is front-loaded with the core purpose and alternative tool, followed by input requirements and validation behavior, then output and caveat. Every sentence contributes new information; no fluff or repetition. Despite its length, it is dense and well-organized for a complex tool.

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

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

Given the tool's complexity (16 parameters, nested client_extraction, validation workflow) and the presence of both detailed input schema and output schema, the description fully covers the decision-relevant aspects: what it analyzes, input provenance, required fields, validation/storage behavior, output reference, and limitations. No major gaps remain.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining that the five text identity fields are required, that optional structured facts are omitted/null when unknown, and by elaborating on the client_extraction object's role. This gives meaningful semantic guidance beyond the raw 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 verb ('Analyzes') with a specific resource ('one job found outside FoundRole') and enumerates the exact signals used (resume match, missing skills, H-1B history, etc.). It clearly distinguishes from sibling tools by explicitly naming tracker_add_external as the alternative when no analysis is desired.

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 gives explicit when-not guidance: 'Use tracker_add_external only when the user asks to save without analysis.' It also implies the primary use case (analyzing external jobs) and references jobs_compare for later, providing clear decision 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?

The description goes beyond the readOnlyHint/destructiveHint annotations by explaining behavioral constraints: order preservation ('keep the user's requested order'), deduplication ('do not send duplicates'), and the prerequisite that unanalyzed external URLs are invalid. It also clarifies that the comparison uses the same FoundRole analysis fields, which sets expectations for output. This is substantial behavioral context not available from annotations or 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 front-loaded with the core purpose in the first sentence, then dedicates the second sentence to input requirements and constraints. Each clause provides necessary information (sources, ordering, duplicates, prerequisite analysis) without redundancy or filler. The length is appropriate for the tool's complexity, and the two-paragraph structure improves scannability.

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 a single parameter with full schema coverage, readOnly annotations, and an output schema, the description covers all necessary dimensions: purpose, input sources, prerequisites, ordering, duplicates, and the fields compared. It leaves no critical gap for an agent to misinterpret. The description is fully self-contained 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?

Even though the schema covers the parameter with 100% description, the tool description adds critical semantics: it specifies that IDs must be exact results from jobs_search, URLs must be exact comparisonRef values from jobs_analyze_external, and it imposes ordering and duplicate prohibitions. This meaningfully extends the schema's bare item description to actionable input guidelines, ensuring the agent formats and selects references correctly.

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

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

The description opens with 'Compares 2 to 4 jobs side by side,' clearly stating the verb (compares), resource (jobs), and scope (2-4, side by side). It lists the specific analysis fields (resume match, missing skills, etc.), distinguishing it from sibling tools like jobs_search and jobs_details. This is a precise, resource-focused purpose statement.

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 defines when to use the tool: after obtaining exact FoundRole job IDs from jobs_search or exact external comparisonRef URLs from jobs_analyze_external. It states a clear precondition ('Analyze each outside job first') and a when-not condition ('a bare URL that has not been analyzed cannot be compared'). This gives the agent concrete guidance on how to prepare inputs and when the tool is applicable.

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

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

The description provides useful context about output fields and entitlement-dependent variability. However, the annotation readOnlyHint=false conflicts with the read-only nature of 'fetches', and the description does not disclose any side effects or error behavior, leaving some ambiguity.

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 efficiently organized with a one-sentence purpose, then Input and Output sections. Every sentence earns its place, and there is no fluff or repetition.

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

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

For a simple one-parameter tool with an output schema, the description is quite complete. It enumerates output categories and notes entitlement-driven variability. It lacks error-case handling but overall is sufficient given the tool's simplicity.

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

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

Schema coverage is 100%, so the schema already fully documents job_id. The description reinforces it by specifying 'the exact ID string from the id field of a jobs_search result', which adds a bit of precision but little 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 the action ('fetches full details'), the resource ('one job'), and differentiates it from jobs_search as 'the deeper view behind a search result'. This is a specific verb+resource+scope that unmistakably identifies the tool's 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?

It explicitly ties usage to a prior jobs_search by referencing the 'id returned from jobs_search', giving clear context for when to use it. However, it does not name alternative tools or explicitly state when not to use it, so it falls short of a perfect score.

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?

Even though annotations already mark the tool as idempotent and non-destructive, the description adds meaningful behavioral context beyond those flags: it explains that a 'processing status' indicates the feed is still being prepared and that later calls return the completed feed. It also clarifies that page numbers fetch additional recommendations from the same feed, and that the payload matches job search. This is valuable disclosure that the annotations do not cover.

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 compact, with four sentences, each earning its place: the first states the core function, the second describes ranking and payload characteristics, the third explains the processing status, and the fourth clarifies pagination. No redundancy or filler, and 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?

The description covers the essential context for this moderately complex tool: what it returns, how results are ranked, what payload is included, how to handle the processing status, and how pagination works. An output schema exists, so the description need not explain return values in detail. It could mention error cases or the effect of the location parameter, but the provided information is sufficient for an agent to use the tool effectively.

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%: both 'page' and 'location' already have descriptions in the schema. The description adds only a small nuance about page numbers fetching from the same feed, which is a minor enhancement. The parameter semantics are therefore adequately covered by the schema, and the description adds no significant meaning beyond it.

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

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

The description opens with a specific verb and resource: 'Returns the authenticated user's personalized job recommendations built from their resume, skills, target roles, and preferred location.' This clearly distinguishes the tool from sibling jobs_search (general search) and jobs_details (specific job details) by emphasizing the personalized feed for the authenticated user.

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 conveys the usage context: this is for the authenticated user's personalized recommendations, which is distinct from the general job search tool. It does not explicitly name alternatives or state when not to use it, so it stops short of a 5, but the context is clear enough for an agent to infer when to select this tool.

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?

Despite annotations declaring readOnlyHint false, the description adds substantial behavioral context: account-tier differences (Pro vs non-Pro), inclusion of resume match data, employer signals, and system_instruction in responses. It also explains pagination semantics and advanced filter scoping. No contradiction with annotations; the description enriches the agent's mental model significantly.

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 longer than average, and somewhat repetitive when listing advanced filters ('remote, h1b_sponsors_only...' after the schema already defines them). However, the content density is high, covering query formation, pagination, eligibility tiers, and response contents; it is well-structured with the core purpose front-loaded. A 4 balances its useful thoroughness against 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 10-parameter tool with an output schema, the description covers input semantics, output elements (nextCursor, id), account-dependent behavior, and system_instruction. It leaves no major gaps for an agent to invoke correctly, making it effectively complete.

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 covers 100% of parameters with descriptions. The tool description adds value by explaining cross-param behavior (constraints only apply if passed), cursor re-use semantics, and the effect of salary_floor on jobs without salary data. Because the schema already documents each parameter, this is a 4 rather than 5.

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

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

The description opens with a specific verb+resource ('Searches a database for real-time job listings') and clarifies scope by distinguishing from sibling jobs_details, which consumes the returned id. This clearly differentiates the tool from related job 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?

Provides explicit guidance on query formulation (full title vs bare keyword), pagination via nextCursor, and the rule that only passed constraints are applied. It also references jobs_details for full job descriptions. However, it does not explicitly state when not to use this tool relative to jobs_recommendations or other alternatives, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds transparency about returning empty groups for irrelevant queries, that results are closest matches not a full index, and that each response includes a system_instruction for presentation. 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 fairly long but well-structured, front-loading the main purpose, then detailing facets, then behavioral notes. Every sentence adds value, though it could be slightly more compact without losing 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?

With 5 parameters (1 required), an output schema, and moderate complexity, the description covers what the tool does, facet usage, exclusions, and return behavior. It is complete enough for an agent to use correctly, though some minor details like default limit are left to the schema.

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?

Input schema has 100% description coverage, so baseline is 3. The description adds value by explaining how facets (company, job_title, location) interact and what they return, and gives context on when to use each, going beyond the schema descriptions.

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 searches FoundRole's published content by semantic similarity for job-search questions, returning articles and site pages. It distinguishes from siblings by explicitly mentioning that jobs_search handles live listings and knowledge_topics covers overall topic coverage.

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 explicit guidance: use for job-search questions about career guidance and product features, and not for job listings (which belong to jobs_search) or topic coverage (knowledge_topics). It also explains when the optional facets are appropriate, e.g., company facet for employer-focused questions.

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

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

Annotations already indicate read-only and idempotent; description adds that it is parameterless and reflects the live corpus.

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 key info, 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?

Fully covers purpose, usage, and output for a parameterless tool with annotations and output schema.

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, so baseline 4 applies; description offers no additional param info but none needed.

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

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

States that the tool lists categories, tags, counts, and total articles for the blog, and explicitly differentiates from knowledge_search.

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 it is the source for blog topic questions and that knowledge_search handles article retrieval.

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 signal destructiveHint=true. Description adds that it returns the updated tracked job with 'reminderAt cleared', providing 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?

Concise, with one sentence for purpose and structured input/output sections. No unnecessary 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?

For a simple tool with one parameter, it covers purpose, input source, and output format. Complete given the tool's 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 coverage is 100%, so the description repeats the parameter description. However, it adds context on where the ID comes from and its distinction from other IDs.

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 'Deletes a reminder from a tracked job' with a specific verb and resource, clearly distinguishing from sibling tools like 'reminder_set' and 'reminder_list'.

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

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

Provides guidance on where to obtain the tracked_job_id and clarifies it is distinct from other IDs. Lacks explicit when-to-use vs. alternatives, but purpose and name imply 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 and destructiveHint=false, indicating safe read-only operation. The description adds ordering behavior (soonest first), which is useful and consistent.

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?

Extremely concise: one sentence for purpose plus minimal input/output details. Front-loaded with the main action, 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?

For a simple tool with one optional parameter and an output schema, the description covers the essential behavior and output structure. Slightly lacking about empty result handling but generally complete.

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% – the schema already describes the limit parameter. The description repeats the same information (default 20, max 50), adding no new 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?

The description clearly states the tool lists tracked jobs with reminders, ordered by soonest reminder time. It distinguishes from siblings like tracker_list (all tracked jobs) and reminder_set/delete (mutations).

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 explicit guidance on when to use this tool versus alternatives. The description does not mention when not to use or provide context for selecting among siblings like tracker_list.

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?

Description discloses sending confirmation email with .ics attachment, which is beyond annotations. Annotations indicate mutation (destructiveHint=true) but description adds valuable 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?

Well-structured with clear input and output sections, concise yet informative, no unnecessary 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?

Given 2 parameters, full schema coverage, and output schema, the description covers all necessary behavioral context (email, ID source, format) and is complete for agent decision-making.

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%, but description adds meaning by specifying the source of tracked_job_id (trackedJobs[].id) and providing an example format for remind_at, going beyond schema descriptions.

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 'Sets a reminder for a tracked job' and distinguishes from siblings like reminder_delete and reminder_list by specifying the email confirmation with .ics attachment.

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?

Implicitly clear when to use (setting a reminder), but lacks explicit guidance on when not to use or alternatives among siblings.

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 minimal info (readOnlyHint=false, destructiveHint=false). The description adds significant context: tracking behavior, duplicate handling, restoration, and return of tracked job 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 well-structured with bullet points and front-loads the main purpose. While slightly lengthy, every sentence adds value and it remains clear.

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 4 parameters and an output schema, the description covers purpose, parameter details, edge cases (duplicate, restoration), and return behavior comprehensively.

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 descriptions, but the description adds value by grouping sub_status options hierarchically per status and clarifying defaults, exceeding the schema's detail.

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 tracks a job from jobs_search results using its job_id, and distinguishes it from tracker_add_external for jobs found elsewhere.

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

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

Explicitly states when to use this tool vs tracker_add_external, and describes behavior on repeated saves and restoration of removed jobs.

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

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

Discloses key behaviors: repeated saves return the existing tracked job (idempotent), optional fields can be omitted, FoundRole's extractors derive missing facts from description. Adds context beyond annotations (readOnlyHint=false, destructiveHint=false) by detailing extraction and idempotency.

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 introduction, usage contrast, required fields, optional fields, and a detailed bullet list. However, it is somewhat lengthy; could be slightly more concise while maintaining completeness.

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 complexity of 19 parameters, nested client_extraction object, and no output schema shown, the description covers all essential aspects: required fields, optional fields, extraction behavior, idempotency, and evidence backing. It is fully sufficient for correct tool 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?

Adds significant context beyond the input schema descriptions. For example, clarifies that url must be a direct job posting URL (not homepage), description can be a short summary, and client_extraction fields are evidence-backed. Leverages full schema coverage (100%) to provide extra meaning.

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 it saves a job posting from the open web into the tracker. Distinguishes from sibling tool tracker_add by specifying that this tool is for jobs found anywhere on the web, not from jobs_search results.

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 guidance on when to use this tool versus tracker_add (which takes a job_id for jobs from jobs_search). Also notes that no prior jobs_search call is needed for jobs seen elsewhere in the conversation.

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 destructiveHint=false, confirming safe read. The description adds behavioral details: results are grouped by status, pagination is supported, and each response includes a system_instruction for presentation. 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 short, uses bullet points for input, and front-loads the purpose. Every sentence adds 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?

The description covers all aspects: purpose, input parameters with defaults, output structure (grouped by status, pagination, system_instruction). No obvious gaps remain.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description repeats this info without adding new semantic meaning beyond what is in 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 the tool lists tracked jobs with filtering and pagination. It uses a specific verb-reource pair and distinguishes from sibling tools like tracker_add or tracker_remove.

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 implicitly indicates this is for viewing jobs, not modifying them. However, it does not explicitly mention when not to use it or provide alternative tools for other actions.

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 mark destructiveHint=true. The description adds context that the tool confirms removal and distinguishes the tracked_job_id from other IDs, enhancing transparency 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?

The description is concise, with two sentences and a structured input section. No extraneous text, and the action 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 simple one-parameter destructive tool with annotations and an output schema, the description covers input and output adequately. It could mention error scenarios or user access requirements, but it's sufficient.

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%, but the description adds value by clarifying that tracked_job_id is distinct from trackable.id and job.id, which aids correct usage.

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 removes a job from the user's job tracker using the verb 'removes' and resource 'job from tracker'. It distinguishes from sibling tools like tracker_add (adds) and tracker_list (lists).

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 explicit when-to-use or when-not-to-use guidance is provided. The purpose is implied by the name, but alternatives are not mentioned. The parameter guidance on sourcing the tracked_job_id from tracker_list output provides some 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?

The annotation destructiveHint=true is consistent with the update verb. The description adds useful behavioral details such as the future constraint on reminder_at and the distinction of tracked_job_id from other IDs, compensating for the lack of annotation 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 well-structured with a brief introductory sentence and bullet-point parameter details. It is concise but covers all necessary input information 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?

The description adequately covers input semantics and notes the output (updated tracked job). Given the presence of an output schema, no further detail on return values is needed. However, it omits prerequisites (e.g., job must exist) and error handling, which would enhance completeness.

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 100% schema coverage, the description still adds value by clarifying the tracked_job_id source, providing ISO 8601 format examples, and specifying the future requirement for reminder_at. These enhancements go beyond the schema descriptions.

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 'Updates details of a tracked job' and lists the specific fields (notes, deadline, salary, tags). This distinguishes it from siblings like tracker_update_status (status updates) and tracker_remove (deletion).

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 explicit guidance on when to use this tool versus alternatives. It implies that it is for updating job details, but no exclusions or context are given, leaving agents to infer from sibling names.

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, and the description adds context: it returns the updated tracked job and explains the conditional nature of sub_status. 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 well-structured with a summary line followed by parameter details and output note. It is slightly lengthy but every sentence is informative.

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 mutation nature and parameter complexity, the description adequately covers all aspects: required vs optional params, valid values, conditional logic, and output. Missing output schema details but output is described as 'updated tracked job'.

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%, but the description adds value by clearly listing all valid status and sub-status options with conditional logic, and clarifying the tracked_job_id origin from tracker_list output.

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

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

The description clearly states it 'Updates the status of a tracked job', using specific verb and resource. It distinguishes from sibling tools like 'tracker_update' and 'tracker_remove' by focusing solely on status changes.

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 detailed parameter guidance including valid values and conditional sub-statuses, but lacks explicit when-to-use or when-not-to-use guidance compared to siblings. Usage is implied by the tool name and context.

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