Search live Upwork job postings ingested by JobsPipe. Returns normalized rows with budget, skills and client signals.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | ||
| limit | No | Maximum rows to return (1-200, default 25). | |
| order | No | ||
| offset | No | Pagination offset. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as read-only, non-destructive, and open-world. The description adds value by specifying inputs (parameter mentions in schema but not description), outputs (normalized rows with budget, skills, client signals), and data freshness (live, ingested by JobsPipe). The description does not contradict 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?
The description consists of two front-loaded sentences with no wasted words. It efficiently conveys the core purpose and key output characteristics.
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 and four parameters (all optional), the description gives a general idea of the output but lacks details about default behaviors, sorting/ordering mechanics, and full response structure. Adequate but not comprehensive.
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 50% (only 'limit' and 'offset' have descriptions). The tool's description does not mention any parameters or provide additional meaning beyond the schema. Since half of parameters lack documentation and the description offers no compensation, the semantic value is low.
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 verb 'search', the resource 'live Upwork job postings', and gives specifics about the data source and returned fields (budget, skills, client signals). This distinguishes it from siblings like 'search_jobs' and 'list_job_sources'.
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 Upwork-specific job searches with certain data, but does not explicitly state when to use this tool versus alternatives or provide any exclusions. The context signals mention sibling tools, but they are not referenced in the description.
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.
Most tools are clearly distinct: listing sources and pricing plans are not easily confused with searching jobs. The only overlap is between search_jobs and search_upwork_jobs, since Upwork is presumably one of the 30+ sources, but the Upwork-specific tool provides unique budget and client signals that differentiate it.
All tool names follow a consistent verb_noun pattern in snake_case: list_job_sources, list_pricing_plans, search_jobs, search_upwork_jobs. The naming makes the action and target resource predictable across the entire set.
Four tools is a tightly scoped set for a job-aggregation server, covering source discovery, plan information, general search, and specialized Upwork search. No tool feels redundant or unnecessary, and the count is neither thin nor bloated.
The core read-only domain is covered: agents can list sources, view pricing plans, search across all sources, and search Upwork specifically. Minor gaps such as a dedicated job-detail fetcher or source-filtered search could be workoundable, but they do not break the primary workflow.