lookup_roles_and_companiesTypeahead over job roles and companies on Jobily.gr. Returns up to 7 role and 7 company suggestions whose slugs feed the role/company filters of search_jobs. Works with Greek, English and greeklish input (min 2 characters).
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Partial role or company name, Greek or English (min 2 characters), e.g. 'προγραμ', 'account'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, and the description adds meaningful behavioral context: returns up to 7 role and 7 company suggestions, supports Greek/English/greeklish, enforces a 2-character minimum, and explains that the returned slugs feed search_jobs filters. This goes well beyond the 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?
Three short sentences, front-loaded with the core purpose, and every sentence adds useful information: what it returns, how it integrates with search_jobs, and input constraints. 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 one-parameter typeahead tool with strong annotations and full schema coverage, the description is complete: it covers purpose, return limits, language support, minimum input length, and downstream usage. No output schema is needed for this level of 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%, and the schema already documents the query parameter with min characters and language examples. The description adds 'greeklish' and the downstream slug purpose, but this is marginal value over the schema, 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 uses a specific verb and resource: 'Typeahead over job roles and companies on Jobily.gr.' It clearly distinguishes this from sibling tools like lookup_locations and search_jobs by stating it returns role/company suggestions whose slugs feed search_jobs filters.
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 when to use it: before search_jobs, to obtain slugs for role/company filters. It also gives input constraints (min 2 characters, Greek/English/greeklish). However, it does not explicitly state when not to use it or name alternatives like lookup_locations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
Each tool targets a distinct resource and action: get_job retrieves details, search_jobs performs queries, list_sectors and lookup_locations provide filter facets, and lookup_roles_and_companies handles role/company suggestions. There is no overlap in purpose, and the descriptions clearly differentiate the roles.
All tool names follow a consistent verb_noun pattern in snake_case (get_, list_, lookup_, search_). Although the verbs vary, the pattern is uniform and predictable, matching the style of well-organized RESTful or MCP naming conventions.
Five tools form a compact, well-scoped set for a job-search read API. This falls comfortably within the ideal 3-15 range, and each tool serves a necessary purpose without redundancy.
The tool surface fully covers the core job-listing workflow: facet discovery (sectors, locations, roles/companies), searching/filtering, and retrieving full details. No missing operations are apparent for a read-only job board; common gaps like update/delete are out of scope for this server.