Server Quality Checklist

Tool Scores

• yc_search_jobsC
  2.8/5.0
  Behavior2/5

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

  With no annotations, the description carries the full burden, yet it only says 'API-only' and fails to mention the default fetchCompanies behavior, the required WAAS_COOKIE, or that a POST is made. It doesn't describe result shape 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.

  Conciseness3/5

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

  Two sentences, front-loaded with verb and resource; no filler. However, the phrase 'API-only' is vague and the inaccurate filter list makes the brevity less useful.

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

  Completeness2/5

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

  Given 5 parameters, no output schema, no annotations, and siblings, the description leaves out auth requirements, side effects (fetchCompanies), result format, and pagination defaults. It is not complete enough for an agent to call safely.

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

  Parameters2/5

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

  Schema coverage is 100%, so the baseline is 3; but the description actively contradicts the schema by advertising filters (jobType, remote, batch, industry) that are not in properties and are blocked by additionalProperties=false. This makes parameter selection riskier than if the description had stayed silent.

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

  Purpose4/5

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

  States a clear verb+resource (Search ... jobs) and gives an example query ('backend intern'), making it distinguishable from sibling startup search tools. However, it lists filters that aren't present in the schema, which slightly muddies the scope.

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

  Usage Guidelines3/5

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

  Provides an explicit trigger example ('Use for backend intern') but no guidance on when to prefer this over yc_get_job or yc_search_startups, and doesn't mention that mirror filters are unsupported or that search results are only company_ids unless fetchCompanies is used. The usage context is clear but lacks exclusions.

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

• yc_fetch_companiesB
  3.4/5.0
  Behavior3/5

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

  With no annotations, the description carries the burden and does disclose the endpoint, POST method, required auth tokens, and data source. It does not mention whether the call is read-only, how errors surface, or any rate/limit behavior, which matters for a POST-based fetch tool.

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

  Conciseness4/5

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

  Three short sentences pack in endpoint, body shape, auth, and sourcing with no filler. The odd parenthetical '(your curl)' and 'No Algolia' are terse but not redundant.

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

  Completeness3/5

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

  For a one-parameter tool the description covers the essential call mechanics and auth, but there is no output schema and no mention of the return shape or failure modes. It is also not explicit about how this tool relates to sibling startup retrieval tools.

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

  Parameters3/5

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

  Schema coverage is 100% and already documents the ids array, type, min/max, and an example. The description reinforces that ids are WAAS numeric ids and the call uses POST directly, but adds no meaningfully new parameter semantics beyond the schema.

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

  Purpose4/5

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

  The description names a specific verb, resource, and HTTP operation ('POST https://www.workatastartup.com/companies/fetch with {ids:[...]}'), so an agent knows exactly what the tool does. It gestures at differentiation with 'Direct WAAS API' and 'No Algolia,' but it does not explicitly compare itself to yc_get_startup or the other siblings.

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

  Usage Guidelines3/5

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

  The phrase 'Authoritative source for YC startup page' and 'No Algolia' imply this is the direct data source rather than a search path, and the auth requirement is a clear precondition. However, it never states when to prefer this over yc_get_startup or when not to use it, leaving usage context mostly implicit.

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

• yc_get_jobA
  4/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the behavioral disclosure burden. It adds 'API-only' as a behavioral trait and names the returned fields, but it does not mention edge cases such as not-found behavior, authentication, or response shape beyond the listed fields.

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

  Conciseness5/5

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

  The description is one concise sentence that front-loads the main action, specifies the lookup key, and lists relevant return fields. Every part adds value with no repetition or filler.

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

  Completeness4/5

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

  For a simple single-parameter lookup tool, the description provides enough context to call it correctly: the operation, the identifier format, and the expected returned fields. The absence of an output schema is partially compensated by listing the key returned data.

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

  Parameters3/5

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

  The schema already documents jobId as 'Work at a Startup job ID' with 100% coverage. The description reinforces this with 'WAAS jobId' but does not add meaningful detail beyond the schema.

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

  Purpose5/5

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

  The description states a specific verb ('Get'), a specific resource ('detailed job info'), and an exact lookup key ('WAAS jobId'). It also lists the kind of information returned (description, tags, salary), which helps distinguish this direct-fetch tool from the sibling search tools.

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

  Usage Guidelines4/5

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

  The description clearly implies this is the tool to use when you already have a WAAS jobId and need detailed information. It does not explicitly name alternatives or exclusions, but the context of a single required jobId parameter makes the intended usage clear.

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

• yc_get_startupA
  4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses the dual-path behavior (authoritative POST /companies/fetch vs. Algolia+yc-oss fallback) and that batch ids[] hits the direct endpoint. It does not mention read-only nature explicitly, but 'get' strongly implies it. Overall, meaningful behavioral context beyond the schema is present.

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

  Conciseness5/5

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

  The description is three tight sentences with no filler. The primary purpose is front-loaded, followed by auth behavior and supported input formats. Every sentence contributes a distinct piece of information, making it easy to scan and parse.

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

  Completeness4/5

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

  For a simple retrieval tool with three fully described parameters and no output schema, the description covers the key context: what it gets, how resolution works, and what identifiers are accepted. It could add a note about the return shape or explicitly distinguish from yc_fetch_companies, but the current level is sufficient for an agent to call it correctly.

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

  Parameters3/5

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

  Schema description coverage is 100%, so parameter meanings are fully documented in the schema. The description only restates that slug, companyId, or ids[] are supported, adding little to what the schema already provides. This meets but does not exceed the baseline for full schema coverage.

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

  Purpose4/5

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

  The description states a specific verb and resource: 'Get full YC startup profile by slug.' It also enumerates supported input modes (slug, companyId, ids[]), clarifying the tool's scope. However, it does not explicitly differentiate itself from the sibling yc_fetch_companies, which may also involve fetching company data, so the distinction is inferred rather than stated.

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

  Usage Guidelines4/5

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

  The description provides clear context on when direct API resolution is used ('If WAAS_COOKIE set') and when the non-auth fallback applies. This gives the agent actionable conditional guidance. It stops short of naming alternative tools for specific cases (e.g., using yc_search_startups to find a slug), but the auth-dependent usage is well specified.

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

• yc_apply_to_jobA
  4.2/5.0
  Behavior4/5

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

  With no annotations, the description carries the burden and does well: it reveals the default dry-run behavior, the human-approved second call, the resume location prerequisite, and the no-browser mode. Minor gap: the approval email recipient is called APPROVAL_EMAIL here but NOTIFY_TO in the schema, and there's no statement about the outcome/return after real submission.

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

  Conciseness5/5

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

  Three sentences, front-loaded and compact; each sentence adds a distinct piece of workflow knowledge. The only minor flaw is the email-recipient name inconsistency, which doesn't affect structure.

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

  Completeness4/5

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

  Despite 16 parameters and no output schema, the description covers the critical workflow, prerequisites, and modality. It doesn't mention how to obtain companyId/jobId (though schema covers those) and omits the post-submit response/return, leaving slight ambiguity for an agent about what success looks like.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the baseline is 3; the description adds workflow-level context around dryRun but doesn't add per-parameter meaning beyond what the schema already provides.

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

  Purpose5/5

  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 – 'Apply to a YC job' – and immediately adds the per-startup customized cover message. The human-in-loop workflow and API-only scope further distinguish it from sibling search/list/get/fetch tools, so an agent can select it without confusion.

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

  Usage Guidelines4/5

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

  It lays out the exact sequence: default dryRun=true sends approval email and does not submit, then after APPROVE re-call with dryRun=false. It also sets the constraint that the resume must be in ./resumes/ and that it is API-only, no browser, but it does not explicitly say 'use yc_search_jobs first' or name alternatives.

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

• yc_list_resumesA
  4.2/5.0
  Behavior3/5

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

  With no annotations, the description carries the full burden. It discloses the local folder path and implies a read-only directory listing, but it does not mention the output format, behavior when no resumes exist, or accepted file types.

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

  Conciseness5/5

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

  A single sentence with no filler. The key facts—what is listed, where, and why—are front-loaded and concise.

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

  Completeness4/5

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

  For a zero-parameter local listing tool, the description covers the essential context: what it lists, the folder location, and its purpose. The lack of output structure details is a minor gap since no output schema exists.

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

  Parameters4/5

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

  The tool has zero parameters, so there is nothing for the description to add beyond what the empty schema already provides. Baseline 4 applies for a parameterless tool.

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

  Purpose5/5

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

  The description states a specific verb (List), a clear resource (resumes), and the exact location (./resumes/ folder). It also ties the tool to its consumer (yc_apply_to_job), which distinguishes it from the sibling search/get/apply tools.

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

  Usage Guidelines4/5

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

  The phrase 'for yc_apply_to_job' gives clear context for when to use this tool, namely before applying to a job. It does not explicitly list alternatives or exclusion criteria, but the intended use is reasonably clear from the context.

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

• yc_search_startupsA
  4.4/5.0
  Behavior4/5

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

  With no annotations present, the description carries the behavioral burden and does meaningful work: it discloses that the operation is API-only, public, requires no auth, relies on Algolia as a fallback, and returns enough of a record to pass ids onward. It could add output-shape or pagination details, but it is substantially transparent for a search tool.

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

  Conciseness5/5

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

  Three sentences, front-loaded with the core purpose, followed by the fallback behavior and the alternative-tool routing. Every sentence earns its place; there is no filler or repetition.

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

  Completeness4/5

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

  Despite having no output schema and no annotations, the description covers the essential behavior, auth model, filters, and the explicit follow-up path to yc_fetch_companies. It is slightly light on what the response object actually looks like, but for a search tool whose full schema documents parameters, this is close to complete.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the parameters are already fully documented in the schema. The description only re-lists filter names without adding beyond-schema usage details, landing at the baseline score of 3.

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

  Purpose5/5

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

  States a specific verb and resource ('Search Y Combinator startups') and differentiates itself from siblings by naming the follow-up tool (yc_fetch_companies) and by scoping to startups rather than jobs. An agent can immediately tell this is a search-first tool, not a detail-fetch tool.

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

  Usage Guidelines5/5

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

  Explicitly routes the agent: search here, then use yc_fetch_companies with returned ids for full details. It also names the public, no-auth fallback and available filters, giving clear context for when this tool is appropriate versus alternatives.

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