Startup Jobs

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

Annotations already declare the operation read-only, idempotent, and non-destructive. The description supplements this by revealing that the response includes the startup.jobs URL and live listing count, which is not present in annotations and adds useful 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, tightly-constructed sentence that front-loads the action and includes both the endpoint and key response details. There is no filler or redundant phrasing.

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 tool with one well-documented parameter, the description adequately covers what the tool does and what it returns. The absence of an output schema is mitigated by explicitly naming the included fields, making the description complete for this complexity level.

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

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

The schema covers 100% of the single parameter with a meaningful description ('Company slug, as returned in job payloads'), so the baseline is 3. The tool description does not add any new parameter semantics beyond the schema's own documentation.

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 'Fetch a company profile by slug' and goes beyond by listing specific return contents (startup.jobs URL and live listing count). This distinguishes it from siblings like get_company_jobs and get_job.

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

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

The phrase 'by slug, as returned in job payloads' gives concrete context for when to use the tool. It does not explicitly name alternatives or exclusions, but the usage context is clear and aids in selecting this tool over others.

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 state readOnlyHint, idempotentHint, and destructiveHint. The description adds useful context beyond annotations: 'no recency window' clarifies the time scope, 'Returns compact summaries' informs return format, and 'newest first' specifies ordering. This enriches the behavioral model without contradicting 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 concise sentences with no filler. The first sentence states the core purpose, the second adds return format and an alternative tool. Every clause adds value.

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 list tool with full schema parameter coverage and no output schema, the description is nearly complete. It explains the output type and ordering. It doesn't explicitly mention pagination, but the cursor parameter in the schema covers that, so the description is adequate.

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 clear descriptions for slug, limit, and cursor. The description itself does not add parameter-specific details, but the schema already handles the heavy lifting; 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 specifies a clear verb ('List'), resource ('live job listings for one company'), and scope ('no recency window'). It also mentions ordering ('newest first') and distinguishes from get_job and implicitly from search_jobs by scoping to a single company.

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 an explicit alternative: 'use get_job for full descriptions.' It implies get_company_jobs is for when you need all live jobs for a company. It doesn't explicitly mention when not to use search_jobs, but the 'for one company' scope offers sufficient 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 and destructiveHint false, so the safety profile is known. The description adds behavioral context by noting the response includes the full description and that the agent should share the startup.jobs URL with the user. 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 sentences, front-loaded with the core action, and every sentence earns its place. No extraneous details 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 get-by-id tool with read-only annotations, the description covers the key return item (full description) and provides an action to take with the result (share URL). It doesn't detail error cases or return format, but the output schema is absent and the tool is simple. Slightly more could be said about the URL being part of the response, hence 4.

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% for the single parameter. The description says 'by id' but the schema already explains id comes from search_jobs results. The description adds no meaningful param semantics beyond what the schema provides, so 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 'Fetch a single job listing by id, including the full description', identifying the specific verb, resource, and scope. It distinguishes from siblings like search_jobs (which searches) and get_company_jobs (which lists jobs for a company).

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 for retrieving a specific job's details and instructs the agent to share the startup.jobs URL for application. While it doesn't explicitly name alternatives or provide exclusions, the context (single job by id) is clear and the sharing instruction is a practical usage guideline.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds meaningful context about access tiers: free returns a 12-month summary with YoY change, while full access unlocks up to 36 months of monthly data. This goes beyond annotation defaults by disclosing rate/access limitations and output granularity.

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 deliver the core purpose and key access-tier behavior without waste. The most important information (what and where) is front-loaded, and the optional filters are mentioned succinctly.

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

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

With no output schema, the description appropriately explains the return format (12-month summary with YoY vs monthly time series). It covers filters and access limits but omits minor details like the units of 'volume' (though implicitly job counts) and any potential pagination behavior. Overall, it is adequate for 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 description coverage is 100%, so the schema already documents all three parameters. The description mentions role and country as filters and months via the access-tier discussion, but it does not add any new semantic detail beyond what the schema provides or clarify parameter formats beyond the schema's 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 provides job posting volume trends on startup.jobs, with optional filters by role and/or country. This verb+resource+scope formulation distinguishes it from sibling tools like get_job (specific posting) and search_jobs (current listings).

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 this tool is for historical trend analysis, but it does not explicitly state when to use it versus alternatives or mention any exclusions. No sibling tool alternatives are referenced, 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 establish read-only and idempotent behavior, so the description adds value by specifying that only countries with jobs are returned and that output includes name and ISO code. This is useful context beyond the annotations, though it does not detail ordering or pagination.

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, front-loaded with the action and resource. Every sentence contributes: the first defines the output, the second instructs on usage. 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?

For a simple list tool with no parameters and no output schema, the description provides all essential information: what is listed (countries with jobs), the fields (name and ISO code), and how to use the results. It is complete for its 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?

The tool has zero parameters, so the baseline is 4. The description adds clarity about the output format (ISO country code), which helps users understand how to use the result, even though there are no input parameters to document.

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 countries, specifying the verb 'List' and the resource 'countries with jobs'. It distinguishes itself from siblings by focusing solely on countries as reference data, not jobs, companies, or trends.

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 tells users to use the resulting ISO codes as the country filter in search_jobs, job_trends, and salary_benchmarks, providing clear application context. It does not explicitly name alternatives to avoid, but since this is the only country list tool, the guidance is sufficient.

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 establish readOnlyHint, idempotentHint, and destructiveHint. The description adds useful context by naming the exact output fields (title, slug, parent_slug) and indicating a hierarchical structure via parent_slug, which goes beyond the minimal safety profile. No contradictions or hidden side effects are disclosed, but the added field detail justifies a strong score.

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 extremely concise: two sentences, no redundant wording. The first sentence states the action and output fields; the second provides cross-tool usage guidance. 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 zero-parameter, read-only listing tool without an output schema, the description is completely sufficient. It covers what fields will be returned and how to use them across sibling tools. No additional context is needed for an agent to invoke and leverage this 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?

The tool has no parameters, so the baseline is 4. The description correctly avoids discussing parameters since there are none, and the empty schema is fully covered. The focus on output semantics (role taxonomy) is the relevant semantic content here.

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

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

The description clearly states the tool's function: 'List the role taxonomy (title, slug, parent_slug)'. It uses a specific verb and resource, and distinguishes from siblings by focusing on role taxonomy rather than companies, jobs, or countries.

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 usage guidance: 'Use slugs as the role filter in search_jobs, job_trends, and salary_benchmarks'. This tells the agent not only what the tool does but how to apply its output in conjunction with sibling tools, clearly positioning it as a supporting look-up 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?

The description adds context beyond the readOnly/idempotent annotations by specifying the data source, the free tier 12-month aggregate, and full access unlocking time series and company-level benchmarks. No contradictions 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 concise, well-structured sentences cover purpose, source, filters, and tier differences with no redundant text, making it highly scannable for an agent.

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 read-only benchmark tool with no required parameters, the description covers essential aspects: data source, units, filters, and access tiers. It doesn't detail return format, but annotations and schema compensate adequately.

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

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

The schema already documents all 4 parameters with descriptions (100% coverage), but the description adds meaning by stating the output is yearly USD and clarifying the free tier vs full access constraints for months/company parameters, which goes 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 computes yearly USD salary benchmarks from startup.jobs listings, with optional filters by role and/or country. This makes it distinct from siblings like job_trends and search_jobs, which focus on other aspects.

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 when to use the tool for compensation benchmarks and clarifies the free vs full access tiers, providing clear context. However, it does not explicitly mention alternatives or exclusion cases, so it stops 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 and idempotentHint, but the description adds valuable behavioral context: it returns 'compact job summaries' (output style), sorts 'newest first', and exposes access-tier limitations ('free tier covers the last 14 days; full access unlocks archive and posted_before'). These are non-obvious runtime behaviors not captured in 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 the core verb and resource, then adding output format, sibling alternative, and access constraints. Every clause adds value with no repetition of schema 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?

The description gives enough to understand the tool's role in the family: search returns summaries, get_job gives details, and access tiers affect archive range. Missing explicit return-field details is mitigated by the pointer to get_job and the schema's parameter descriptions, but for a search tool with no output schema, a bit more detail on response shape would help. Overall, it is adequate.

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 80% of parameters with descriptions; the description compensates by explaining the access-tier restriction on posted_before and the 14-day search window, which clarifies how date filters behave. It does not elaborate on q, role, or other params, but those are already well-described 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 a specific action and resource: 'Search live startup job listings, newest first.' It also distinguishes itself from get_job by noting it returns compact summaries and that get_job provides full descriptions, so the purpose is unambiguous and differentiated from a key sibling.

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 tells the user when to use get_job instead ('use get_job for the full description') and gives context criteria ('live startup job listings', 'newest first'). It does not contrast with other siblings like get_company_jobs or job_trends, but the provided guidance is clear and useful.

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