Skip to main content
Glama
freehire

freehire

by strelov1

similar_jobs

Read-only

Find job postings similar to a given posting by slug, returning nearest matches first for 'show me more like this' recommendations.

Instructions

Postings most similar to one posting, by its slug, nearest first — for "show me more like this". Empty for the newest postings, whose neighbours are not computed yet.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "slug": "<slug>"
    },
    "name": "similar_jobs"
  }
}

Input Schema

NameRequiredDescriptionDefault
slugYesThe job's public slug (from search or facets results).
limitNoHow many to return, up to 20.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.8.0

TDQS

A3.8/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true, so safety is covered; the description adds real value by disclosing result ordering ('nearest first') and an edge case ('Empty for the newest postings, whose neighbours are not computed yet') that an agent could not infer from 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.

Conciseness5/5

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

A single tight sentence with the core purpose front-loaded and the edge-case caveat appended after a dash; nothing is wasted.

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 two-parameter read-only lookup with no output schema, the description covers the purpose, ordering, and the main failure mode (empty for new postings). Only the meaning of the returned fields is left implicit, which is low-risk for a 'similar items' list.

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%, so slug and limit are already documented in the schema. The description only restates that the lookup is by slug and adds no format or constraint detail beyond the schema, so baseline 3 applies.

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 specific verb and resource: postings most similar to a given posting identified by slug, with ordering (nearest first). This clearly separates it from generic siblings like search or job, though it doesn't name an alternative explicitly.

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 'for "show me more like this"' implies the use case, but there is no explicit when-not guidance or named alternative (e.g., search for keyword-based discovery). The empty-result caveat is behavioral, not a usage rule.

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