Homerun MCP by usefulapi

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

Goes well beyond the annotations by disclosing that the note becomes visible to the hiring team, cannot be removed with this server, and is not sent to the candidate. These side-effect and persistence facts are exactly the context an agent needs for an irreversible-looking write, and they are consistent with destructiveHint=false.

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?

Leading 'WRITE:' tag front-loads the critical operation class, and every subsequent clause carries distinct information (visibility, removability, candidate impact, endpoint/scope). No filler.

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

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

For a mutation tool with no output schema, it covers the important behavioral facts (team visibility, non-removability, no candidate notification, endpoint and scope). It omits the is_sensitive parameter's effect and any response shape, but the core call-correctly information is present.

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 four parameters including the 1-2000 char limits and display_name default. The description restates the character range and author semantics but adds no syntax or format detail beyond what the schema provides, so the baseline 3 applies.

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

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

Opens with a specific verb and resource ('WRITE: add ONE note to one application'), and the 'ONE' / 'one application' framing plus the sibling set (list_notes, get_application) makes the single-write semantics unambiguous. An agent can tell this apart from the read/list siblings instantly.

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 'WRITE:' prefix signals the operation class and the note-creation intent is clear, but there is no explicit when-to-use/when-not, no mention of the list_notes alternative, and no prerequisites stated. Usage is implied rather than guided.

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?

Goes well beyond the readOnly/non-destructive annotations: it names fields that are never returned (date of birth, photo URL, file download links), states the required OAuth scope, and cites the underlying endpoint. These are exactly the constraints an agent cannot infer from structured fields.

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

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

A single dense paragraph that front-loads what the tool returns and pushes exclusions and scope to the end. The field enumeration is long but each element is load-bearing, so little is wasted.

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 carries the return-value burden and does so thoroughly, listing returned fields, withheld fields, and an optional expansion. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented. The description restates the effect of include_answers in prose, adding no syntax or format detail beyond the schema, which is the baseline case.

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 a specific verb and resource ('One job application in full') and enumerates the fields it returns, which cleanly distinguishes it from homerun_list_applications and homerun_get_vacancy.

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?

Routes the agent to a sibling for related data ('notes: use homerun_list_notes') and gives a privacy-driven usage rule ('fetch only the candidate you need'). It does not explicitly contrast with homerun_list_applications, but the singular-vs-list framing makes the choice clear.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is clear. The description adds useful context beyond annotations by listing the returned fields (description, location, department, hiring stages, salary indication, candidate count, URLs), the HTTP endpoint, and the required scope, though it does not mention error behavior or pagination (not relevant for a single fetch).

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 tight sentence followed by the endpoint and scope, with no filler. Every phrase earns its place by clarifying either the returned data or the invocation context.

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?

There is no output schema, so the description carries the burden of explaining what is returned, and it does so by enumerating the key fields. Combined with annotations that already cover the safety profile and the scope note, an agent has everything needed to call this read-only endpoint correctly.

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

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

Schema description coverage is 100%, and the single vacancy_id parameter is fully documented with a pattern and example in the schema. The description adds no additional syntax or constraints beyond what the schema already provides, so the 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 states a specific verb (Get) and resource (vacancy), scoped to a single record by id, which naturally distinguishes it from the sibling list_vacancies. It also enumerates key return fields, giving an agent a precise sense of what will be returned.

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

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

The description implies the tool is for retrieving one vacancy when its id is known, and it names the required scope (vacancies:read) as a practical prerequisite. However, it does not explicitly state when to prefer this over alternatives like list_vacancies or get_application, leaving usage inference to the agent.

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 cover the safety profile (readOnly, non-destructive, openWorld), but the description adds real behavioral value: the API's ordering convention (newest page first), the required OAuth scope (job-applications:read), and notably what is deliberately NOT returned (phone, DOB, photo, files). That privacy boundary is the kind of trait an agent cannot infer from structured fields.

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?

Front-loaded with purpose and ordering, then the return fields, then the privacy caveat and routing advice. The mid-sentence field enumeration is slightly list-heavy, but it earns its place because there is no output schema to carry that 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?

With no output schema, the description compensates by enumerating returned fields and explicitly calling out the omissions, and it covers pagination, filtering, auth scope and sibling routing. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100% and each parameter already carries its own doc string, including units, defaults, ranges and filter syntax. The description's mention of filtering by vacancy, stage or disqualified state only restates what the schema already defines, 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?

States a specific verb+resource ('List job applications') and immediately distinguishes itself from the sibling read path by name-dropping homerun_get_application for single-record fetches. An agent can pick between the two without opening either schema.

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?

Explicit routing ('ask for one application with homerun_get_application'), explicit filtering guidance ('filter by vacancy, stage name or disqualified state and page through') and an explicit exclusion ('do not use it to export all candidates'). When-to-use, alternative and anti-use are all present.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description usefully adds the OAuth scope required (job-application-tags:read), which an agent needs for auth, but says nothing about the returned shape or pagination behavior.

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

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

Two short sentences, zero filler, with the resource described first and the endpoint/scope appended. Every clause carries 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 read-only list tool, the annotations cover safety, the schema covers all three parameters with pagination semantics, and the description names the resource, endpoint and required scope. No output schema exists, so return values are only loosely gestured at ('the tags attached'), which is the one small gap.

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

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

Schema description coverage is 100%, and the schema already documents page (with next_page chaining guidance) and perPage (1-100, default 15). The description adds no parameter detail beyond what the schema provides, so the baseline of 3 applies.

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

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

States the resource and its scope precisely — the tags attached to ONE application — and pins it to the concrete endpoint GET /job-applications/{job_application_id}/tags. It implicitly distinguishes itself from the sibling homerun_list_tags (account-wide) by scoping to a single application, but never names that alternative explicitly.

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

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

Usage is only implied by the resource scope: an agent infers this is the per-application variant rather than the account-wide homerun_list_tags. There is no explicit when-to-use statement, no prerequisites, and no exclusions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real value beyond that by naming the required auth scope (job-application-notes:read) and confirming the response includes a sensitive flag, which an agent may need to treat carefully.

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

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

One front-loaded sentence covering purpose and payload, followed by a compact endpoint/scope line. No filler, no repetition of schema content, and the most decision-relevant information (what is listed, on what) comes first.

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 compensates well by enumerating the returned fields, and the schema handles pagination and the required id. It stops short of noting ordering or behavior on an unknown/invalid application id, which would fully close the loop.

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 page, perPage and job_application_id are already documented in the schema. The description adds no syntax or format detail beyond restating that the id targets an application, so the baseline of 3 applies.

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

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

States a specific verb (List) and resource (notes on one application), and enumerates the returned fields: id, author display name, text, sensitive flag, timestamps. This clearly separates it from the write-side sibling homerun_add_note and from other list tools in the family.

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 'on one application' implies the required scoping context, so an agent can infer this is the per-application notes reader. However, there is no explicit when-to-use/when-not guidance and no routing to alternatives (e.g., when to prefer a general application fetch). Usage is implied rather than stated.

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, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds genuinely new context: the required auth scope tags:read and the shape of the response (id + name), which matters since there is no output 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?

One compact sentence with the resource and return shape front-loaded, followed by endpoint and scope. No filler or redundancy.

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

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

For a simple paginated read with no output schema, the description supplies the return fields and auth scope the schema cannot. Pagination is handled by the schema; the only mild gap is that it does not flag the sibling application-tags tool.

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

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

Schema description coverage is 100%: both page and perPage are fully documented in the schema, including defaults and next_page chaining. The description contributes nothing about parameters, so the baseline 3 applies.

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

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

States a specific verb (List) and resource (the company's candidate tags), plus the return fields (id + name) and the underlying endpoint. It implicitly separates itself from homerun_list_application_tags by scoping to the company-wide tag catalog rather than a single application, though it never names that sibling explicitly.

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 scope hint (tags:read) and endpoint imply when the tool is usable, but there is no guidance on when to prefer it over homerun_list_application_tags or any prerequisite/dependency. Usage is inferable rather than stated.

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, and the description usefully adds the transport and auth requirement: 'GET /vacancies (scope vacancies:read)'. That scope requirement is context the annotations do not convey, though rate limits and pagination semantics are left to the schema.

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

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

Two tight sentences: the resource and returned fields come first, the optional enrichment and the auth/endpoint footnote follow. Nothing is redundant and nothing could be cut without losing 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?

With no output schema, the description compensates by enumerating the fields returned and the optional includes, and it names the auth scope. Pagination mechanics live only in the schema's next_page hint, so an agent relying on the description alone would not learn how to page through results.

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, but the description adds intent beyond the schema by tying the 'stages' include to a consuming tool (homerun_move_application_to_stage) and by spelling out what the enriched response contains. It does not add format detail for status or page beyond the schema's own wording.

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 a specific verb and resource ('List job vacancies') plus the exact fields returned (title, status, type, location type, expiry) and enumerates the status values. An agent can tell this apart at a glance from the singular sibling homerun_get_vacancy and from homerun_list_applications, which targets a different resource.

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?

Clearly frames the operation as a list with optional enrichment via 'include', and gives a concrete downstream reason to use one option ('stages ... their ids are what homerun_move_application_to_stage needs'). It never states when NOT to use it (e.g., vs homerun_get_vacancy for a single record), so it stops short of explicit alternatives.

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

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

Goes well beyond annotations by disclosing that only the stage id changes, that Homerun-side automations (e.g. configured e-mails) may fire as a side effect, that this tool itself sends no e-mail, and that it does not reject or delete anyone. It also cites the write scope (job-applications:write), which the annotations do not convey. These side-effect details are exactly what an agent needs before mutating a record.

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?

Front-loaded with the 'WRITE:' signal and the core action, then progressively adds constraints, side effects, and the endpoint. Every clause carries information, though the automations/e-mail caveat plus the endpoint line make it longer than strictly minimal.

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 covers everything needed: the mutation, the single field changed, the id source, the write scope, the endpoint, and the key side effect (stage automations). Nothing material is missing 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?

Schema coverage is 100%, so baseline is 3, but the description adds meaning: stage_id must be sourced from the vacancy's stages via homerun_get_vacancy, and the PATCH sends only that field. The creation source of the id is richer than the schema's own note.

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 a specific verb (move) plus resource (ONE application to another hiring stage of its vacancy), with explicit singular scope that distinguishes it from any bulk sibling. The parenthetical clarifying it is a PATCH touching only the stage id makes the action unambiguous.

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

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

Tells the agent where stage ids come from (homerun_get_vacancy) and frames the tool as a WRITE operation, which is clear routing context. It stops short of naming an alternative tool for the same action or stating when NOT to use it, so it is clear guidance without exclusions.

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