Hosco Hospitality Jobs

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description usefully enumerates the payload (description, programme details, provider, price, duration, delivery type, languages), but says nothing about failure behavior for an invalid/unknown slug or how locale affects the response.

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, zero waste, with the core action front-loaded and the usage cue second. Nothing needs trimming.

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 listing the returned fields, which is the right move. It is nearly complete for a simple two-param read tool, missing only error behavior and the role of the locale parameter in the returned link.

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%, with both slug and locale fully documented including the locale default and allowed values, so the schema carries the burden and the baseline of 3 applies. The description adds no format or constraint detail beyond the schema; 'exactly as returned by the search tool' is already in the slug 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?

States a specific verb+resource: 'Fetch the full details of a single Hosco course by its slug.' It is clearly distinct from search-courses-tool, though it never names that sibling explicitly; the differentiation comes from 'single course by its slug' vs. a 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?

'Use this after a search result' gives clear sequencing context for when to invoke it. It stops short of naming the alternative tool or stating when not to use it (e.g. for multiple courses, use search-courses-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 annotations already declare readOnlyHint and idempotentHint, covering safety. The description adds meaningful context about what the response contains (full description, requirements, benefits, all fields), going beyond the annotations without contradiction.

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 resource. The second sentence gives practical usage context. No wasted words.

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

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

For a simple read-only detail fetch, the description provides sufficient context about purpose, usage, and return content. Annotations cover safety and idempotency. It doesn't mention error cases, but that is not critical for this 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%, so both parameters (id and slug) are already well documented. The description adds minimal extra meaning beyond restating that either slug or numeric id can be used, matching the baseline.

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 ('Fetch') and clearly identifies the resource ('full details of a single Hosco job'). It distinguishes itself from list/search siblings by focusing on retrieving one job's details, including description, requirements, and benefits.

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 states to use this after a search/list result, providing a clear when-to-use context. While it doesn't name alternatives directly, the intended workflow is unambiguous and the sibling tools are implicitly distinguished.

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, so the safety profile is known. The description adds context about ordering ('most recently published') and pagination, which goes beyond the annotations and helps the agent understand the tool's 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?

The description is two sentences long, front-loaded with the primary action, and every word earns its place. It avoids fluff and clearly communicates the tool's function and when to use it.

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, the annotations covering safety, and the schema covering parameters, the description is sufficient for an agent to select and invoke the tool correctly. No critical information 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?

The schema already provides 100% coverage with descriptions for both limit and offset. The description does not add parameter-specific semantics beyond what the schema offers, so the baseline of 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 uses a specific verb ('List') and resource ('Hosco jobs') with a clear scope ('most recently published, paginated'). It also distinguishes itself from the sibling search tool by explicitly noting the difference, making the purpose unambiguous.

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

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

The description explicitly states when to use this tool ('when no semantic search is needed') and directs users to the alternative ('use the search jobs tool instead') for natural-language queries. This is clear, actionable 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, covering the safety profile. The description adds meaningful behavioral context beyond annotations: it guarantees that hidden and deleted courses are never returned, and that every result carries a canonical url. It does not cover rate limits or pagination behavior, but the added constraints are valuable.

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

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

Four sentences that are front-loaded with the core purpose and filter capabilities. No wasted words, though the last sentence about the canonical url is somewhat tangential and could be integrated more tightly.

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 search tool with 11 optional parameters and no output schema, the description provides a solid overview: domain scope, filter support, exclusion of hidden/deleted courses, and a guarantee about result URLs. It lacks detail on pagination behavior (offset/limit) and result ordering, but the schema compensates.

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 all 11 parameters are fully documented in the schema itself. The description only summarises filter dimensions (category, language, learning type, price) without adding syntax, default values, or edge-case semantics beyond what the schema already provides.

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 (Search) and resource (Hosco's catalogue of hospitality courses and training programmes), with examples of domains. It clearly distinguishes itself from siblings like course-details-tool (which retrieves one course) and search-jobs-tool (jobs, not courses).

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 by describing supported features ('free-text query plus filters') but never explicitly says when to use this tool versus alternatives, nor does it state when not to use it or name a sibling. Context is implied rather than prescribed.

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 significant behavioral context beyond the readOnly and idempotent annotations by disclosing that private, expired, and inactive postings are hard-excluded, and by explaining the default ordering logic. This provides useful insights into how the tool behaves beyond what annotations offer.

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 core purpose, and every clause provides meaningful detail about filtering, ranking, and exclusions. There is no filler or redundant 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?

Given the tool's complexity (17 optional parameters, no output schema), the description covers key behaviors including exclusions, filtering, ranking, and return type. It does not specify the full return payload structure, but the detailed schema compensates, making the description sufficiently 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 input schema already contains detailed descriptions for all 17 parameters (100% coverage). The description adds a high-level summary of filtering capabilities and the default 'suggested' ordering, but these are already captured in the schema descriptions, so the added value is marginal.

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 performs semantic and structured search over Hosco hospitality jobs and returns ranked matches with relevance scores. However, it does not explicitly contrast this with sibling tools like list-jobs-tool or job-details-tool, making sibling differentiation implicit rather than explicit.

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 clear context for when to use the tool—for semantic or structured search with filtering and ranking—by detailing supported filters and ordering options. It does not explicitly state alternatives or exclusions, but the context is strong enough for an agent to infer appropriate usage.

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