AI-agent-first job platform. Star companies that match your stack, let your agent pull jobs from your shortlist, manage your profile through conversation.
Scored across 24 tools
Most tools have clearly distinct purposes, and descriptions explicitly differentiate overlapping job-related tools (search_jobs vs get_starred_jobs vs get_feed vs get_digests). However, get_feed and get_starred_jobs both surface jobs from starred companies, which could cause occasional misselection despite the clarifying text.
Tools consistently use snake_case with a verb_noun pattern (e.g., get_profile, save_job, star_listing, delete_linktree). Minor deviation: apply_to_job includes a preposition, and update_saved_job_note has a three-part noun, but overall the naming is predictable and readable.
With 24 tools, the set is on the heavy side but each tool covers a distinct operation across job search, profile management, link trees, and account status. No redundant tools stand out, though the count is at the upper boundary of what feels well-scoped.
Core CRUD is well covered: profile items (save_* upserts, delete_profile_item), jobs (save, unsave, update note), companies (star, unstar), and link trees (create, get, delete). Notable gaps: no update_linktree operation and no way to list a user's submitted applications beyond the immediate response from apply_to_job.
Apply to a job on behalf of the user, or get its application link. Two outcomes by job type: internal jobs (posted directly through Remoet's partner system) are applied to end-to-end and return the created application; scraped jobs (most of the platform) return applicationType "external" with the applicationUrl where the user applies on the company's site. Share that link with the user; Remoet cannot submit external applications for them.
Applying to an internal job submits a real application in the user's name, so it needs the user's explicit consent.
Internal jobs must be published and not expired, and the user can only apply once per job: duplicate applications are rejected.
| Name | Required | Description | Default |
|---|---|---|---|
| jobId | Yes | The ID of the job to apply to |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false) by disclosing that internal applications are submitted in the user's name and require explicit consent, that duplicates are rejected, and that jobs must be published and unexpired. It also clarifies that no write occurs for external jobs, which meaningfully sharpens the mutation semantics.
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-loads both outcomes in the first sentence and uses the remaining two short paragraphs for the consent requirement and eligibility rules. Every sentence carries distinct information with 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?
With no output schema, the description compensates by describing both possible return shapes (created application vs external applicationUrl) plus the preconditions and idempotency constraint. An agent has everything needed to call and handle the result 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 coverage is 100% with a single required jobId already documented as the ID of the job to apply to. The description adds outcome context but no additional meaning about the parameter format or constraints, 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 and resource (apply to a job) and immediately defines its dual outcome, making it clearly distinguishable from siblings like save_job or search_jobs. The internal-vs-external split is spelled out with the exact return signal ('applicationType "external"' with 'applicationUrl').
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?
Explains the branching behavior by job type and instructs the agent to share the external link rather than attempt submission, which is actionable routing guidance. It does not explicitly compare against sibling tools (e.g., save_job) or state when an agent should prefer saving over applying, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a link tree page: a shareable page with the user's links (social media, portfolio, GitHub, etc.). Each account can create up to 10. The slug becomes the public URL. Slug rules: 5-20 characters, lowercase letters, numbers, and hyphens only, cannot start/end with a hyphen. Must be unique. Use the user's name or handle as a base for the slug. The usual links are the ones on the user's profile (githubUrl, linkedinUrl, twitterUrl, url), which get_profile returns.
Remoet tracks views and link clicks on each link tree, so a link tree URL on a CV or application shows whether a recruiter opened it.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | URL slug (5-20 chars, lowercase, hyphens allowed, must be unique) | |
| links | Yes | Array of links to display on the page (max 50) | |
| title | Yes | Page title (e.g. "Carl Igelström: Links") | |
| description | Yes | Short description for the page |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare the generic write profile (readOnly=false, destructive=false, idempotent=false); the description adds non-obvious behavior: a hard quota of 10 link trees per account and the uniqueness requirement on the slug. It does not describe what happens on quota/uniqueness violation or the shape of the created resource, so it is not fully transparent.
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 core requirements (limit, slug rules) are front-loaded and useful, but the closing sentence about view/click tracking and recruiters seeing the URL is product marketing that does not help an agent invoke the tool, and the slug rules duplicate the schema.
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 4-required-param creation tool with no output schema, the description covers the essentials: quota, slug constraints, and data source. It is slightly thin on what the tool returns on success (e.g. the resulting public URL) and on error behavior, which keeps it from a 5.
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; the description still adds value by restating and explaining slug rules and by suggesting a strategy ('use the user's name or handle as a base') plus a source for the links array (profile URLs). It does not clarify the description field or link label semantics beyond the schema.
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?
Specific verb + resource ('Create a link tree page') followed by a plain-language definition of what a link tree is and the key attribute (shareable page of the user's links). An agent can distinguish it from get_linktrees or delete_linktree without opening the 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?
Gives real operational context: each account is limited to 10, the slug becomes the public URL, and it tells the agent where to source the links (the profile fields returned by get_profile). It does not name an alternative or state when *not* to use this tool, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a link tree page. Link tree ids come from get_linktrees. Confirm with the user before deleting.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The ID of the link tree to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds a real behavioral instruction not present in annotations: confirm with the user before deleting, which governs how the agent should sequence the call.
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, each earning its place: action, id source, and safety instruction, ordered by immediacy. No filler or restatement of the title.
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 destructive single-parameter tool with no output schema, the description covers the action, the input provenance, and the required user confirmation, while annotations carry the mutation semantics. Nothing essential to correct invocation 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 coverage is 100% and the single 'id' parameter is documented with a 24-char hex pattern. The description adds provenance the schema cannot convey — that the id originates from get_linktrees — which helps the agent source a valid value rather than guess one.
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 ('Delete a link tree page'), and routes the agent to the sibling that supplies the required id (get_linktrees). An agent can distinguish this from create_linktree or the read-side get_linktrees without opening any 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?
Gives concrete context: ids come from get_linktrees and the user must confirm before deleting. It doesn't explicitly state when-not to use it, but the precondition (obtain id first) and the confirmation step are clear operating guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a profile item: a work experience entry, a project, or an education entry (set type accordingly). Use this to clean up duplicates, placeholder/test entries, or clearly wrong data. Ids come from get_profile. Always confirm with the user before deleting anything that could be real.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The ID of the item to delete (get its id from get_profile) | |
| type | Yes | Which kind of profile item to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is known. The description adds value beyond that by requiring user confirmation before deleting anything that could be real, which is behavioral guidance the annotations cannot express.
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 tight sentences: purpose and variants first, then usage triggers, then the safety caveat. No filler, though the parenthetical about 'type accordingly' slightly duplicates the schema's enum documentation.
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 two-parameter destructive mutation with full annotation and schema coverage and no output schema, the description supplies the missing pieces an agent needs: id provenance, the type-to-item mapping, and a confirmation requirement. Nothing critical is absent.
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 the enum and the id pattern/24-hex constraint already documented in the schema. The description restates that ids come from get_profile and that type must match the item kind, adding little beyond the structured fields, so 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 (delete) plus the resource (profile item) and enumerates the three concrete variants (work experience, project, education), telling the agent to set type accordingly. This clearly separates it from the save_*/update_profile siblings that operate on the same resources.
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?
Gives concrete when-to-use triggers (duplicates, placeholder/test entries, clearly wrong data) and names the prerequisite source for ids (get_profile). It stops short of explicitly naming a when-not or an alternative tool, but no sibling can delete profile items, so the routing gap is minimal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The user's account status in one call: every budget the platform enforces (active stars vs cap, unstars used vs the 30-day unstar budget, MCP requests today vs daily cap, REST API requests today vs daily cap, each with a resetsAt), the remaining limits (link-tree cap), and any over-cap/grace state.
Calling it is free and never counts against a cap. Every limit is a plain number.
Remoet is free. There is nothing to upgrade to and nothing to sell: if the user is at a limit, help them work within it.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds genuinely useful behavioral context beyond that: the call is cost-free, does not consume any cap, every limit is a plain number, and each budget carries a resetsAt. That is real added value, though it omits any note about caching/freshness of the counters.
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 return-value enumeration is well front-loaded, but the trailing sentences ('Remoet is free. There is nothing to upgrade to and nothing to sell: if the user is at a limit, help them work within it.') are promotional/instructional filler that do not help an agent decide to call or invoke the tool, and read as injected guidance rather than tool documentation.
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 no parameters, the description carries the burden of describing returns and does so thoroughly, naming each budget and the resetsAt field. It is essentially complete for a zero-argument status tool, losing a point only for the irrelevant marketing sentences occupying space.
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 tool takes zero parameters, so per the rubric the baseline is 4. There is nothing further the description could usefully say about parameter semantics.
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 ('The user's account status in one call') and enumerates exactly what is returned: active stars vs cap, unstar budget, MCP/REST request counts, resetsAt, remaining limits, and over-cap/grace state. This is clearly distinguishable from the get_linktrees/get_profile/get_apps siblings, which cover other resources.
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 conveys context (free, never counts against a cap) and hints at the use case of helping a user work within limits, but never explicitly states when to call this versus other tools or what scenario triggers it. 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.
List approved apps built on the Remoet platform. These are community and official apps that extend Remoet's functionality. Each app has a repo URL for deployment and a demo URL to try it out. Use this to help users discover tools that complement their Remoet workflow, e.g. portfolio sites, CV generators, job trackers, etc. You can filter by category or tag.
| Name | Required | Description | Default |
|---|---|---|---|
| tag | No | Filter by tag | |
| page | No | Page number, starting from 1 (default: 1) | |
| category | No | Filter by category | |
| pageSize | No | Results per page, max 50 (default: 20) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description goes beyond that by describing the payload contents (repo URL for deployment, demo URL to try it out) and that filtering is available, which helps the agent set user expectations.
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 core action and resource, followed by payload description, then usage context. Four sentences with little waste, though 'community and official apps that extend Remoet's functionality' is somewhat redundant with the opening clause.
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, zero-required-parameter browse tool with no output schema, the description adequately covers what is returned and when to invoke it. Pagination behavior is left to the schema, which is acceptable since those fields are fully documented there.
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 tag, category, page and pageSize are already documented with types, bounds, and defaults. The description only restates that filtering by category or tag is possible, adding no syntax or semantics beyond the schema. 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 (approved apps on Remoet) with scope qualifiers ('approved', 'community and official'). It is clearly distinguishable from every sibling, which are all job/profile/listing operations.
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?
Gives a clear context for use ('help users discover tools that complement their Remoet workflow') with concrete examples (portfolio sites, CV generators, job trackers). No explicit when-not or alternative tool is named, but no sibling overlaps this space, so the gap is minor.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
HISTORICAL ONLY: the user's archived job digests, the email summaries Remoet used to send about new jobs from their starred companies. No new digest has been generated since 2026-07-06, when the feed roundup replaced that pipeline, so this returns nothing at all for an account created since then. What carries new roles now is get_feed (the composed dashboard stream, and what the roundup emails are built from); for searching, use get_starred_jobs or search_jobs. Reach for this tool only when the user asks about their old email summaries by name. Without an id: the 20 most recent as lightweight summaries (id, title, frequency, jobCount, createdAt). With an id: that digest's full markdown body (each job's title, application URL, salary, remote policy, experience level, tech stack).
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Fetch one digest in full by id. Omit to list recent digests. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the read-only, non-destructive, closed-world profile, but the description adds material context they cannot: the digest pipeline was retired on 2026-07-06, recent accounts will get nothing, and the two id/no-id return shapes differ in depth. This is exactly the kind of behavior an agent needs before calling.
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 most decisive constraint (HISTORICAL ONLY) and every sentence carries routing or return-shape information. It is dense and on the long side, but there is no filler to strip; a slightly tighter split would read better than the current run-on structure.
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 fully by enumerating both return shapes and their fields, and it removes ambiguity about a tool that would otherwise appear broken for most accounts. Nothing needed 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 coverage is 100% and the id parameter is already documented, so the baseline would be 3. The description goes further by explaining the consequence of omitting id (20 lightweight summaries with listed fields) versus supplying it (full markdown body with per-job detail), which meaningfully extends the schema's 'omit to list' phrasing.
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 (archived job digests / email summaries) and immediately scopes it as HISTORICAL ONLY, naming the successor pipeline (get_feed) that replaced it. An agent can distinguish this from get_feed, get_starred_jobs, and search_jobs without opening any 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?
Gives an explicit when-to-use ('only when the user asks about their old email summaries by name') and names three alternatives with the condition each serves. It even states the tool is effectively dead for new accounts, which is decisive routing information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The user's dashboard feed as ONE composed stream, chronological newest first. Each entry has a kind: 'item' (per-company job items from their starred companies - the company, when it landed, role snapshots with job id/title/application URL/salary/remote policy/experience level/tech stack, and per-role flags isActive, savedJobId, matchesFilters, plus per-item isStarred: false means the user unstarred that company since), 'job_of_the_day' (one daily editorial pick from anywhere on the platform - a discovery candidate worth surfacing), 'blog' and 'broadcast' (platform content; usually skim). Pass nextCursor back to page deeper; omit it for the newest page.
| Name | Required | Description | Default |
|---|---|---|---|
| cursor | No | nextCursor from the previous page. Omit for the newest page. | |
| pageSize | No | Items per page (default 20, max 50). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare a safe read (readOnlyHint=true, destructiveHint=false, openWorldHint=false), and the description goes well beyond them by disclosing the entry taxonomy (item, job_of_the_day, blog, broadcast) and the semantics of flags such as isStarred:false meaning the user unstarred the company. With no output schema, this return-shape disclosure is exactly the behavioral context an agent needs.
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?
It is front-loaded with the core statement of what the feed is, and the dense parenthetical enumerations each carry distinct information rather than padding. It reads as a long run-on with heavy nesting, which slightly hurts scannability but wastes little text.
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 burden of explaining return values and does so thoroughly, covering each entry kind, per-role fields, and the meaning of flags, while fully accounting for both parameters including pagination limits. Nothing an agent needs to call this correctly appears to be 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 and the baseline is 3. The description adds round-trip meaning to the cursor parameter ('pass nextCursor back to page deeper; omit it for the newest page'), which clarifies the intended paging workflow beyond the schema's field-level text.
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 names a specific resource (the user's dashboard feed) and describes it as a single composed stream that is chronological newest-first, so the agent knows exactly what is returned. It does not name or distinguish itself from siblings like get_digests, get_saved_jobs, or search_jobs, which would be needed for a 5.
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 guidance is limited to pagination mechanics (pass nextCursor to page deeper, omit for the newest page) and a soft content hint that blog/broadcast are 'usually skim'. There is no explicit when-to-use-this-vs-alternatives framing against the sibling list tools (get_digests, get_starred_jobs, search_jobs), so usage is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The user's link tree pages: shareable single-page URLs for a CV, email signature, or job application, with per-link view/click tracking so recruiter engagement is measurable. Without a slug: all of the user's link trees (each with its id and slug). With a slug: that page's content plus its engagement data (views, clicks per link), which answers "has anyone looked at my link tree?".
| Name | Required | Description | Default |
|---|---|---|---|
| slug | No | Fetch one link tree in full by its public slug (with engagement data). Omit to list all of the user's link trees. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint=true, destructiveHint=false and closed-world scope, so the safety profile is covered. The description adds real behavioral value beyond that: it discloses that omitting the slug returns a collection while supplying one returns page content plus per-link view/click metrics, which is exactly what an agent needs to predict the response shape.
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 resource definition, then the two-mode behavior, which is the right ordering. It is somewhat padded ('shareable single-page URLs for a CV, email signature, or job application'), but every sentence carries informational weight and there is no true 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?
With no output schema, the description carries the burden of describing returns and does so adequately for both modes (ids and slugs for the list; views and clicks per link for the single fetch). Minor gaps remain around pagination or ordering for the list case, but nothing essential for correct invocation 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 the slug parameter is already documented as 'fetch one link tree in full... omit to list all', which the description essentially restates. With the schema doing the heavy lifting, the baseline of 3 applies — the description adds framing but no format, validation, or naming semantics beyond what is already structured.
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 (retrieve the user's link tree pages) and defines the domain object concretely as shareable single-page URLs with per-link engagement tracking. It also distinguishes the two operating modes (list all vs. single page with analytics), so an agent can separate it from create_linktree/delete_linktree without opening any 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?
Gives clear context for use: listing the user's pages, or answering the engagement question 'has anyone looked at my link tree?'. However it never names the sibling write/delete tools as alternatives or states exclusions, so routing is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Works without a Remoet account. Get detailed information about a specific company listing by its slug. Use this to review a company before deciding whether to star it. Returns the company's full description, perks, job count, and URLs. NOTE: the tech stack is a small preview unless the company is starred. Starring unlocks the full stack (techStackCount shows the true total, e.g. a 3-tag preview of 147). Pass checkTechStack with the user's technologies to verify overlap against the FULL stack. Matched ones come back in matchedTechStack and lead the preview, same contract as search_listings. The star budget is reported by get_account.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | The URL slug of the listing (e.g. "digital-ocean", "stripe") | |
| checkTechStack | No | Technologies to verify against the company's full stack (auto-normalized, max 50); matches are returned in matchedTechStack |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/non-destructive annotations, the description discloses the key behavioral quirk: the tech stack is only a small preview unless the company is starred, with techStackCount giving the true total. It also notes no account is required and points to get_account for the star budget, adding real operational context.
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?
Dense but front-loaded: purpose and slug first, then the star/preview caveat and checkTechStack contract. Every sentence carries information, though the tech-stack explanation runs long enough to border on verbose.
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 readOnly annotations, the description carries the burden well by enumerating return contents (description, perks, job count, URLs) and the matchedTechStack/preview behavior. An agent has everything needed to call it correctly and interpret the 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% and the schema already documents both params, but the description adds meaning the schema does not: checkTechStack is verified against the FULL (starred) stack, not the preview, matched entries surface in matchedTechStack, lead the preview, and follow the same contract as search_listings. That is genuine added value over the field text.
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 (get) and resource (company listing) and pins the lookup key to the slug. It explicitly differentiates itself from siblings by naming search_listings and by framing its role as pre-star review, distinct from star_listing.
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 to review a company before deciding whether to star it" gives clear context, and the checkTechStack guidance tells the agent when to pass technologies. It stops short of an explicit when-not/alternative-routing statement (e.g., vs search_listings for bulk discovery), so it is strong but not fully prescriptive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The user's complete Remoet profile in one call: profile core (summary, links, location, avatar), workExperience, projects, and education (each section entry carries an id for update/delete) plus the current visibility setting. The ids it returns are the ones the save_* and delete_profile_item tools take.
What the fields affect: the summary is the first thing companies read; the technologies arrays on work entries and projects feed job matching, so an empty array drops that entry out of matching; visibility NONE hides the user from every company's candidate list, STARRED shows them to the companies they have starred, ALL to every company.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), and the description adds genuinely useful context beyond them: what each field affects and how visibility values (NONE/STARRED/ALL) change who can see the user. It stops short of auth requirements or rate limits, but the added data-semantics context exceeds annotation coverage.
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-loads the returned shape, then explains field effects and visibility, so the most important content comes first. It is somewhat long for a no-arg read tool, and the visibility/field-effects paragraph is more data-semantics than tool behavior, but every sentence carries meaning.
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 full burden of describing return values, and it does: it lists the sections returned, notes each entry carries an id, and reports the current visibility setting. Nothing an agent needs to call and interpret 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?
The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to disambiguate. It correctly implies a no-argument call by framing the result as the 'complete ... profile in one call'.
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 names a specific verb (view/get) and resource (the user's complete profile) and enumerates its sections: profile core, workExperience, projects, education, plus the visibility setting. It also distinguishes this tool from siblings by noting it returns the ids consumed by save_* and delete_profile_item, so an agent knows exactly what it produces.
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 implies the right context ('complete ... profile in one call') and explicitly routes the agent: the ids it returns are what save_* and delete_profile_item take, which tells you to call this before mutating profile items. There is no explicit when-not or named alternative (e.g. versus get_account), but the use case is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the user's saved jobs list. This is the user's job search memory: shows all jobs they've bookmarked across sessions, with notes and job details. Includes both AI-extracted jobs and internal partner jobs (see jobType field). It shows the user's existing pipeline, so jobs they have already saved can be told apart from new ones. Paginated, newest saves first. Each saved job includes isActive and deactivatedAt fields. If isActive is false, the job is no longer appearing on the company's careers page. This usually means it was filled or expired, but could also be a temporary scraper issue (there is a grace period before deactivation). A saved job the user can no longer see (its company is no longer starred, or a partner role was unpublished) keeps its entry but comes back with job: null, locked: true and a lockedReason to pass on. If job is null without locked, the listing was deleted entirely. A deactivated job may still be open on the company's careers page.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, starting from 1 (default: 1) | |
| pageSize | No | Results per page, max 50 (default: 20) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint/destructiveHint already covering safety, the description goes well beyond annotations by decoding return-state semantics: isActive, deactivatedAt, job:null + locked:true + lockedReason vs a plain null meaning deletion, and the grace period caveat. This is exactly the behavioral context an agent cannot get 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose is front-loaded in sentence one and the following sentences are dense with return-state semantics rather than filler. It runs long for a two-parameter read tool, but with no output schema most of that length is earned, aside from mild overlap between the deactivation and 'may still be open' statements.
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 a read-only tool with no output schema, the description covers pagination behavior, job provenance, and all the null/locked return variants an agent needs. The main omission is disambiguation from get_starred_jobs and other listing siblings, which matters in this crowded namespace.
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% for both page and pageSize, so the schema already documents them fully. The description only adds the result ordering ('newest saves first'), which is a minor supplement to the schema rather than compensating detail; 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?
The first sentence gives a specific verb+resource ('Get the user's saved jobs list') and the rest clarifies scope (AI-extracted vs partner jobs, notes, job details). It never distinguishes itself from the near-named sibling get_starred_jobs or from get_feed/search_jobs, so the agent must infer 'saved' vs 'starred' on its own.
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 via context ('the user's job search memory', 'shows the user's existing pipeline') rather than stated. There is no explicit when-to-use, when-not, or named alternative (e.g. get_starred_jobs, get_feed), leaving the agent to guess which listing tool fits.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get job postings from the user's starred companies. This is the user's own curated feed. If the user has no stars, this returns nothing. In that case, use search_jobs instead: it reads the public catalogue. Supports filtering by search query, location, tech stack, remote policy, experience level, and minimum salary. Results are paginated. Same-title postings from one company are grouped into a single row: postingCount and postingLocations show how many raw postings it represents and where (boards often post one role per location). Results can be bookmarked with save_job.
A single filtered query can miss good roles; an unfiltered call returns the whole feed, paginated. The techStack filter uses OR logic: specifying ["React", "TypeScript", "Node.js"] returns jobs matching AT LEAST ONE of them (technologies are auto-normalized and matched across spelling variants), so filter by the technologies that genuinely matter and judge each job's fit from its own techStack field. Use searchQuery for role-based searches ("senior engineer", "frontend", "platform") and techStack for technology-based filtering.
OVER-CAP WARNING: if the response includes a "starsOverCap" field, the user has more starred companies than the limit allows and the surplus is scheduled for PERMANENT deletion on the given date. Proactively tell the user (count + date) and let them choose which companies to unstar down to the limit. NEVER unstar companies on the user's behalf just to get under the limit unless they explicitly ask you to.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, starting from 1 | |
| sortBy | No | Sort field (default: createdAt) | |
| pageSize | No | Results per page (max 50, default 20) | |
| salaryMin | No | Minimum salary filter | |
| sortOrder | No | Sort direction (default: desc) | |
| techStack | No | Filter by technologies (e.g. ["React", "Node.js"]) | |
| searchQuery | No | Search keywords for job title, summary, or tech stack | |
| remotePolicy | No | Filter by remote policy: "remote", "hybrid", "onsite", or "remote-restricted" | |
| locationQuery | No | Filter by location or remote restrictions | |
| techStackMatch | No | How techStack combines: "any" (default, at least one technology) or "all" (every technology required) | |
| experienceLevel | No | Filter by experience level: "junior", "mid", or "senior" |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the readOnly/destructive/openWorld annotations by disclosing result grouping semantics (postingCount/postingLocations), pagination, techStack normalization/OR logic, and a critical over-cap warning that surplus stars are scheduled for PERMANENT deletion. The prohibition against unstarring on the user's behalf is exactly the kind of behavioral guardrail annotations cannot express.
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, then usage, then a clearly flagged OVER-CAP WARNING in caps. The paragraph about filtered vs unfiltered queries is slightly meandering, but overall the definition is dense with useful content rather than padding.
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 11 optional params, no output schema, and no annotations beyond the safety profile, the description carries the needed burden: it covers feed scope, empty-feed routing, filter mechanics, grouping, pagination, and a consequential over-cap deletion warning. Nothing an agent needs to call 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 coverage is 100% so the baseline is 3, but the description adds genuine meaning: it explains the OR logic of techStack, its auto-normalization across spelling variants, searchQuery vs techStack division of labor, and pagination behavior. It does not clarify sortBy or salaryMin semantics, keeping it short of a 5.
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 ('Get job postings from the user's starred companies') and immediately scopes it as 'the user's own curated feed', which distinguishes it from the public-catalogue sibling search_jobs. An agent can tell it apart from search_jobs without opening a 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?
Explicitly names the when-not ('If the user has no stars, this returns nothing') and the alternative to use instead ('use search_jobs instead: it reads the public catalogue'). Adds further conditional guidance on filtered vs unfiltered calls and on choosing searchQuery vs techStack, and routes saving to save_job.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add or update an education entry (upsert). Omit id to create (institution is required); pass an id (from get_profile) to update, changing only the fields you send. Ask about degrees, bootcamps, and notable certifications. Confirm approximate dates with the user rather than guessing; don't fabricate. Saving without an id always creates a new entry.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Present: update this education entry (only the fields you pass change). Omit: create a new one (institution is required to create). | |
| endDate | No | End date: a date, e.g. "2024-01-15" | |
| isCurrent | No | Whether you are currently studying here (default false on create) | |
| startDate | No | Start date: a date, e.g. "2024-01-15" | |
| studyLevel | No | Level of study: HIGH_SCHOOL, ASSOCIATE, BACHELOR, MASTER, DOCTORATE, BOOTCAMP, or OTHER | |
| description | No | Description of studies, achievements, etc. | |
| institution | No | Institution name (e.g. "MIT", "Lund University") | |
| fieldOfStudy | No | Field of study (e.g. "Computer Science") | |
| institutionUrl | No | Institution website URL |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false; the description usefully reinforces non-idempotency ('Saving without an id always creates a new entry') and partial-update semantics ('changing only the fields you send'). It stops short of describing what is returned or how duplicates are handled, so it is not a full 5.
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 core upsert behavior and otherwise tight, but the final sentence ('Saving without an id always creates a new entry') repeats the first sentence's create condition, which is minor 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 mutation tool with no output schema and annotations covering the safety profile, the description covers the create/update contract and required field adequately. It does not state what the call returns or how the saved entry is identified, a small remaining 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%, so the schema already documents every parameter, including the id create/update semantics that the description restates. The description adds no field-level meaning beyond 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?
States a specific verb (add/update, upsert) and a specific resource (education entry), and immediately differentiates from siblings like save_work_experience and save_project. The agent can identify the tool's job without opening the 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?
Gives explicit create-vs-update branching (omit id to create, pass id from get_profile to update), states the create prerequisite (institution required), and adds when/what to ask the user (degrees, bootcamps, certifications; confirm approximate dates instead of guessing). This is genuinely actionable routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Save a job to the user's list for later. Supports both AI-extracted jobs (from search_jobs or get_starred_jobs) and internal partner jobs. This gives the agent memory across sessions. Saved jobs persist so the user doesn't lose track of interesting roles. Optionally attach a note (e.g. "Great fit for React skills", "Follow up next week"). Each job can only be saved once.
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | Optional note about why this job is interesting | |
| jobId | Yes | The ID of the job to save | |
| jobType | No | Type of job: "ai_job" (from search_jobs or get_starred_jobs, default) or "listing_job" (internal partner job) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false, destructiveHint=false, openWorldHint=false, idempotentHint=false, so the safety profile is already covered. The description adds real behavioral context the annotations don't: persistence across sessions and the 'each job can only be saved once' constraint. It does not say what happens on a duplicate save (error vs. no-op), which is the one remaining ambiguity.
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 core action and scope in the first sentence, followed by source tools, the memory rationale, the note example, and the once-only constraint. The memory/persistence sentences overlap somewhat in meaning, but overall it is efficient.
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 agent must infer the result of a save; the description doesn't state whether a successful save returns the saved record or how duplicates are reported. Given the mutation nature and the 'only once' constraint, the duplicate-call behavior is the notable gap. Otherwise it covers inputs, sources, and purpose adequately.
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 all three parameters (jobId, note, jobType) are already fully documented in the schema, including the enum values and the 24-hex pattern. The description corroborates the note's purpose with examples and ties jobType's ai_job value to search_jobs/get_starred_jobs, but adds no syntax or format detail beyond the schema. 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 (save), resource (job), and destination (user's list for later), which clearly separates it from unsave_job and get_saved_jobs in the sibling set. It also names the upstream tools that produce savable jobs (search_jobs, get_starred_jobs).
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?
Explains the use case well: persisting jobs across sessions and tracking interesting roles, and names the source tools that feed it. It does not explicitly state when NOT to use it or point to unsave_job/update_saved_job_note as follow-ups, so it stops short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add or update a portfolio project (upsert). Omit id to create (title and shortDescription are required); pass an id (from get_profile) to update, changing only the fields you send. Projects are the #1 differentiator for junior/mid developers. Help the user recognize work they might not think of: side projects, open-source contributions, hackathon entries, internal tools, time-saving scripts, blogs, personal apps. Saving without an id always creates a new entry. Saved entries appear on the user's public profile, so they should describe real work.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Present: update this project (only the fields you pass change). Omit: create a new one (title and shortDescription are required to create). | |
| role | No | Your role in the project | |
| title | No | Project title | |
| demoUrl | No | Live demo URL | |
| endDate | No | End date: a date, e.g. "2024-01-15" | |
| repoUrl | No | Repository URL | |
| isRemote | No | Whether this was remote work (default false on create) | |
| isCurrent | No | Whether this is an ongoing project (default false on create) | |
| startDate | No | Start date: a date, e.g. "2024-01-15" | |
| description | No | Full project description | |
| isOpenSource | No | Whether this is open source (default false on create) | |
| technologies | No | Technologies used | |
| shortDescription | No | A one-line summary of the project |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations declaring readOnlyHint=false, openWorldHint=false, idempotentHint=false, and destructiveHint=false, the description adds critical context: upsert behavior (create if no id, update if id), partial update semantics (only sent fields change), and the public visibility of saved entries. This goes well beyond what annotations provide.
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 front-loaded with the upsert behavior and create/update conditions, followed by motivational context and examples. Every sentence earns its place, with no 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?
Given the 13 parameters, no output schema, and the description's thorough explanation of creation vs. update, required fields, and public visibility, it provides all necessary information for an agent to invoke the tool correctly. The annotations already cover safety hints, and the description fills the remaining gaps.
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 schema already documents all 13 parameters. The description reinforces the core semantics of the id parameter (create vs. update, required fields on create) and emphasizes the upsert pattern, adding clarity beyond the schema's per-parameter descriptions.
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 explicitly states the tool's function as an upsert for portfolio projects, distinguishing create vs. update behavior by the presence of an id. It clearly differentiates from siblings like save_education and save_work_experience by focusing on projects.
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 clearly explains when to create (omit id) and when to update (pass id), and provides detailed guidance on recognizing project types. However, it doesn't explicitly contrast with sibling save tools or mention when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add or update a work experience entry (upsert). Omit id to create a new entry (title and startDate are required); pass an id (from get_profile) to update an existing one, changing only the fields you send. Every description should cover WHAT was built, HOW (technologies), IMPACT (users served, performance gains, revenue, uptime), and SCOPE (team size, scale). Push for measurable outcomes ("Built React frontend" -> "...serving 50K users, 40% faster"). The technologies array feeds job matching. Saving without an id always creates a new entry. Saved entries appear on the user's public profile, so they should describe real experience. Ask the user to confirm vague dates or fill real gaps.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Present: update this work-experience entry (only the fields you pass change). Omit: create a new one (title and startDate are required to create). | |
| title | No | Job title | |
| endDate | No | End date: a date, e.g. "2024-01-15". Omit it for a current role | |
| isRemote | No | Whether this job is remote (default false on create) | |
| isCurrent | No | Whether this is your current job (default false on create) | |
| startDate | No | Start date: a date, e.g. "2024-01-15" | |
| companyUrl | No | Company website URL | |
| companyName | No | Company name | |
| description | No | Job description | |
| technologies | No | Technologies used (e.g. ["React", "Node.js"]). They feed job matching |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare a non-idempotent, non-destructive write; the description adds real value on top by warning that saving without an id ALWAYS creates a new entry, that updates are partial (only sent fields change), and that saved entries appear on the user's public profile. That is meaningful side-effect and idempotency context beyond the annotation flags.
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 operational semantics (id behavior, required fields, public visibility) are front-loaded and efficient. The mid-section content-authoring advice about WHAT/HOW/IMPACT/SCOPE is longer and more coaching than tool definition, but it is still relevant to producing a valid payload.
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 10-parameter mutation tool with no output schema, it covers the important gaps: create-vs-update semantics, conditional required fields, side effects on the public profile, and a caution about confirming vague dates. Failure/validation behavior is the only notable omission.
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 goes further: it explains the conditional requirement of title/startDate on create and that the technologies array feeds job matching, plus content guidance for the description field. It adds meaning rather than restating the schema.
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 ("Add or update a work experience entry (upsert)") and immediately distinguishes the two modes by id presence. It is trivially separable from save_education, save_project, and save_job, which cover different profile resources.
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?
Gives explicit conditions: omit id to create (with title and startDate required), pass an id sourced from get_profile to update, and only the passed fields change. It does not name sibling tools to prefer over this one, but the create/update branch is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Works without a Remoet account. Search Remoet's PUBLIC job catalogue: every role on the open board at remoet.dev/jobs, across all companies, not just the ones the user has starred. No star is needed and none is consumed. Use this to answer "what is out there" for any technology, title or company; use get_starred_jobs instead for the user's own curated feed.
Each result carries the role's public Remoet URL, which is a real page anyone can open, plus applyUrl (the employer's own posting, where an application actually happens) and companySlug (the same slug get_listing takes, for company detail). Roles that Remoet is not permitted to publish never appear here.
Duplicate postings of one role at a company are collapsed into a single result, so totalCount is the number of distinct roles, not raw postings. duplicateCount is how many postings collapsed into it; boards usually duplicate a role per location, but nothing guarantees that, so do NOT report it as a number of locations. firstSeenAt is when Remoet first saw the role, not when the employer posted it, and lastVerifiedAt is the last time Remoet confirmed it was still open.
Filters are searchQuery (title, Remoet summary and tech stack), techStack (ANY of the given technologies, or EVERY one under techStackMatch: "all", which is how you express a must-have stack), companySlug, location, remotePolicy, experienceLevel and salaryMin. A salaryMin floor drops every role Remoet holds no numeric salary for, which is roughly 45% of the board, so use it when salary is a hard requirement and leave it off otherwise. location matches the canonical places Remoet stores per role rather than the free-text location string, so a country also finds roles that name only one of its cities; searchQuery does NOT read location, so filter by place with location and not by typing the place into searchQuery.
When a search returns nothing, the hint says which filter emptied it and how many roles dropping that one filter would return, so act on the hint rather than guessing at which filter to relax. Results are newest-first unless you ask otherwise: sortBy takes "newest" or "salary", with sortOrder asc or desc. Start broad and narrow: a single heavily filtered query misses good roles. Results can be bookmarked with save_job.
Example: search_jobs({ searchQuery: "platform engineer", techStack: ["Go", "Kubernetes"], location: ["Berlin"], remotePolicy: ["remote"] }).
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, starting from 1 (default: 1). Without a Remoet account the first 10 pages are available; connect an account to page deeper. | |
| sortBy | No | Sort field: "newest" (default) or "salary". Under "salary", roles with no known salary sort LAST whichever direction is asked for, so they never head the list. | |
| location | No | Match roles in ANY of these places (max 5), e.g. ["Berlin"] or ["Germany", "Netherlands"]. Matched against the canonical place names Remoet stores per role, not the free-text location string, so a country ALSO matches roles that only name one of its cities. City or country name, url slug ("san-francisco") and common alias ("NYC", "UK") all resolve. A place Remoet does not know returns no roles and says so, rather than quietly returning everything. Note that under a location filter a role's duplicateCount, firstSeenAt and the particular posting shown (its id, applyUrl and location) describe only that role's postings IN THOSE PLACES, so they can differ from the same role returned without one. | |
| pageSize | No | Results per page, max 20 without a Remoet account (default: 20) | |
| salaryMin | No | Minimum salary, against the role's normalized salaryEnriched.from. Roles Remoet holds no numeric salary for are EXCLUDED by this filter, so a floor narrows the board to the ~55% of roles that publish one. | |
| sortOrder | No | Sort direction (default: desc) | |
| techStack | No | Match roles carrying ANY of these technologies (e.g. ["React", "Go"]), or EVERY one of them under techStackMatch: "all". Matched case-insensitively against the exact stored technology, so use whole names rather than fragments. Known spelling variants are expanded, so "Go" also finds roles tagged "Golang". | |
| companySlug | No | Restrict to one company by its Remoet slug (the same slug get_listing takes, e.g. "stripe"). An unknown or delisted company returns an empty page, not an error. | |
| searchQuery | No | Free text, matched against the job title, Remoet's own summary of the role and its tech stack. Comma-separate keywords to require ALL of them (e.g. "react, typescript"). | |
| remotePolicy | No | Match roles with ANY of these remote policies: "remote", "hybrid", "onsite" or "remote-restricted" (max 5). | |
| techStackMatch | No | How techStack combines: "any" (default, at least one technology) or "all" (every technology required ON THE SAME ROLE; use for a must-have stack). Spelling variants stay grouped per technology, so "all" with ["Go", "React"] means a Go-or-Golang role that is ALSO a React role, never a Golang-or-React one. Under "all" at most 20 distinct technologies may be required in one search: more than that returns NO roles rather than a search quietly trimmed to 20, so send the ones that genuinely matter. | |
| experienceLevel | No | Match roles at ANY of these experience levels: "junior", "mid" or "senior" (max 5). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even though annotations already declare readOnly/no-destructive, the description adds substantial behavioral context: works without an account and consumes no star, salaryMin silently drops ~45% of the board, results are newest-first by default, duplicate postings are collapsed so totalCount counts distinct roles, and firstSeenAt/lastVerifiedAt are Remoet-observed timestamps rather than employer-posted ones.
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 account-free public-catalogue framing and the sibling contrast, then organized into result-fields, filters, and sort behavior. It is long and partially overlaps the schema's own parameter docs, but nearly every sentence carries actionable detail for a 12-parameter search tool.
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?
No output schema exists, and the description compensates by explaining the meaningful return fields (public remoetUrl, applyUrl, companySlug, totalCount, duplicateCount, firstSeenAt, lastVerifiedAt) and the semantics of duplicateCount so it is not misread as locations. Edge cases (empty results, unknown place, unknown company) are covered.
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 goes beyond restating fields: it points to techStackMatch:'all' as the way to express a must-have stack, frames salaryMin as a hard floor that excludes unknown-salary roles, and warns that location matches canonical places while searchQuery does not read location. Much is still duplicated from the schema, keeping it below a 5.
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 (search Remoet's PUBLIC job catalogue, the open board at remoet.dev/jobs) and immediately bounds the scope ('across all companies, not just the ones the user has starred'). It explicitly names the sibling it is not (get_starred_jobs) so an agent can choose between them 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?
Gives explicit when-to-use ('what is out there' for any technology, title or company) and the alternative for the opposite case (get_starred_jobs for the curated feed). It also adds operational guidance: start broad and narrow, act on the empty-result hint, use salaryMin only when salary is a hard requirement, and results can be bookmarked with save_job.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Works without a Remoet account, except starred: true. Search companies on Remoet, or list the user's starred companies (starred: true). Returns a summary per result. Full detail (description, perks, URLs) is on get_listing, by slug. Job boards and aggregators are excluded; talent networks that post direct roles (e.g. Toptal) appear as companies.
CRITICAL, star quality: only star companies whose tech stack OVERLAPS the user's skills (a JavaScript dev should not star a Go/Rust-only shop). Stars are the user's job-feed noise filter, so an irrelevant star pollutes their feed with jobs they can't use. Judge overlap by each result's matchedTechStack: the technologies from your techStack filter that the company actually uses, checked against its FULL stack (not the capped preview), so do NOT skip a company just because the visible preview omits the user's skills. An empty matchedTechStack means the result matched on text, not tags. techStackCount is the company's true tag total; the full stack unlocks on starring. techStack matches AT LEAST ONE filtered technology by default; set techStackMatch:"all" to require every one.
starred: true limits results to the user's starred companies; combined with techStack it returns matchedTechStack per starred company, which shows any star with zero overlap.
Example: search_listings({ searchQuery: "payments", techStack: ["TypeScript", "React"], experienceLevel: ["mid"] }).
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, starting from 1 (default: 1). Without a Remoet account the first 10 pages are available. | |
| sortBy | No | Sort results by: stars (most popular), jobCount (most active hiring), or name (alphabetical). Default: relevance when searching/filtering, stars when browsing | |
| starred | No | Set true to list the user's STARRED companies instead of searching the full catalog. In this mode searchQuery/experienceLevel/sort/pagination are ignored; pass techStack to get a matchedTechStack per starred company for auditing stack fit. | |
| pageSize | No | Results per page, max 20 without a Remoet account (default: 20) | |
| techStack | No | Filter by technologies (e.g. ["React", "Node.js", "TypeScript"]). Each result's matchedTechStack shows which matched. Technologies are auto-normalized. | |
| searchQuery | No | Search keyword: matches company name, description, and about text | |
| techStackMatch | No | How techStack combines: "any" (default, at least one technology) or "all" (every technology required; use for must-have stacks) | |
| experienceLevel | No | Only companies with at least one open role at any of these seniorities (e.g. ["junior"] for entry-level-friendly companies). Each result's experienceLevels field shows its per-seniority role counts; a 0 can also mean seniority was not detected for those roles. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare a read-only, non-destructive, closed-world operation, and the description adds substantial extra context: account-free access limits, exclusion of job boards/aggregators, inclusion of direct-post talent networks, and the fact that the full tech stack only unlocks on starring. This is behavior well beyond what the structured fields convey.
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?
Purpose and alternatives are front-loaded, but a large block is devoted to star-quality guidance (who should be starred) that is primarily star_listing's concern rather than search invocation. The example and CRITICAL framing aid the agent but push length well past what a search call strictly needs.
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, and the description compensates by explaining return shape (a summary per result, matchedTechStack, techStackCount, experienceLevels) and the no-account paging limits. For an 8-parameter, zero-required search tool this is complete enough to call 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 coverage is 100%, so baseline is 3, but the description adds real semantics beyond the schema: matchedTechStack reflects only filtered technologies checked against the FULL stack, an empty matchedTechStack means a text-only match, techStackCount is the true tag total, and techStack defaults to at-least-one matching. It doesn't cover sortBy/pagination interplay, keeping it from a 5.
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 ("Search companies on Remoet") plus a second mode ("list the user's starred companies"), and explicitly points to the sibling get_listing for full detail by slug. An agent can distinguish it from search_jobs and get_listing without opening any 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?
Gives clear conditions: works without a Remoet account except when starred:true, use get_listing for full detail, set techStackMatch:"all" for must-have stacks, and starred:true ignores searchQuery/experienceLevel/sort/pagination. It does not explicitly frame when to choose this over search_jobs, so it falls short of the full when/when-not/alternatives bar.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Star/save a company listing. Starring subscribes you to their job postings. Starred company jobs appear in get_starred_jobs. Starring also unlocks the company's FULL tech stack (unstarred listings only show a small preview). Starring is FREE. It does not consume budget. However, there is a limit on how many active stars you can have at once. Remaining star slots are reported by get_account. CRITICAL: Only star companies where the user's tech stack genuinely overlaps with the company's tech stack. A React/Node developer should NOT star a company that only uses Go or Java. Irrelevant stars pollute the job feed with noise. Every star must be a deliberate, high-quality match. A company returned by a techStack-filtered search_listings call confirms the technologies in its matchedTechStack field (the filter checks the full stack, including the part hidden from the preview), so judge overlap by matchedTechStack, not the visible preview.
| Name | Required | Description | Default |
|---|---|---|---|
| listingId | Yes | The ID of the listing to star |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations only declaring this a non-idempotent, non-destructive write, the description adds substantial behavioral context: starring subscribes the user to job postings, unlocks the full tech stack, is free and consumes no budget, and is subject to a limited number of active star slots reported by get_account. This goes well beyond the 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-loads the core action and effects before the CRITICAL guidance, and every clause carries meaning. It is on the long side and the tech-stack-overlap warning is somewhat repetitive, but not padded.
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?
No output schema exists, and the description still tells the agent what happens as a result (jobs appear in get_starred_jobs, tech stack unlocks, slots are consumed and tracked via get_account). Nothing needed to invoke 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 coverage is 100% for the single listingId parameter, so the schema already documents its format. The description adds decision-relevant context about how to judge candidates (use matchedTechStack, not the visible preview) but nothing about the parameter itself, 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+resource ('Star/save a company listing') and immediately distinguishes it from its sibling unstar_listing by describing the state change and its consequences. The agent can tell exactly what operation is being performed.
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?
Gives explicit when-to-use criteria ('Only star companies where the user's tech stack genuinely overlaps'), a concrete counter-example (React/Node developer should NOT star a Go/Java-only company), and names alternatives/related tools (get_starred_jobs, get_account, search_listings). This is unusually rich routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a job from the user's saved list. Saved job ids come from get_saved_jobs. Confirm with the user before removing.
| Name | Required | Description | Default |
|---|---|---|---|
| savedJobId | Yes | The ID of the saved job entry to remove |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new behavioral requirements beyond that: a human-confirmation step and the provenance of valid ids. It doesn't cover edge behavior (e.g., removing a nonexistent id), so not a 5.
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, zero filler, with the destructive action and its precondition front-loaded. Every sentence carries actionable 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 one-parameter destructive tool with rich annotations and no output schema, the description covers purpose, id source, and the confirmation guardrail. Nothing an agent needs to invoke it safely 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 coverage is 100% with a single documented string param (24-hex pattern), so the baseline is 3. The description adds real meaning by telling the agent where the savedJobId value comes from (get_saved_jobs), which the schema does not state.
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 ("Remove a job from the user's saved list") that is unambiguously the inverse of the sibling save_job, so an agent can route correctly without opening a schema. No vague or tautological phrasing.
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?
Gives concrete usage context: it names get_saved_jobs as the source of valid ids and instructs the agent to confirm with the user first. It lacks an explicit when-not or alternative-tool clause (e.g., how this differs from unstar_listing), which keeps it short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a star from a company listing. WARNING: Unstarring consumes from your unstar budget (per 30-day period), EXCEPT when the user is over their star cap (then trimming back to the limit is free). This prevents unlimited cycling of stars. The remaining unstar budget is reported by get_account. Only unstar if the company is truly not relevant. Do NOT mass-unstar to get a user under their cap unless they explicitly ask. If they are over cap, surface the choice and let them decide which to keep.
| Name | Required | Description | Default |
|---|---|---|---|
| listingId | Yes | The ID of the listing to unstar |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds substantial non-obvious behavior: the per-30-day unstar budget consumption, the free-trim exception when over the star cap, and the anti-cycling rationale. It also points to get_account for the remaining budget, which is real operational context not present in any structured field.
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 core action and a WARNING before the rationale and edge-case policy. Five sentences is on the long side for a single-parameter mutation, but each sentence carries a distinct behavioral rule, 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?
For a single-param mutation with no output schema, the description covers action, cost model, exception, and policy constraints. An agent has everything needed to decide whether to call it and what to warn the user about.
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?
Only one parameter and schema coverage is 100%, so the schema fully documents listingId. The description adds no syntax or format detail beyond what the schema already provides; 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 and resource ('Remove a star from a company listing'), and the sibling set contains star_listing, whose inverse this clearly is. It stops short of explicitly naming star_listing as the counterpart, so the differentiation is inferable rather than stated.
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?
Gives explicit when-to-use ('Only unstar if the company is truly not relevant'), explicit when-not ('Do NOT mass-unstar to get a user under their cap unless they explicitly ask'), and prescribes an alternative behavior (surface the choice, let the user decide). This is about as complete as usage guidance gets.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update the user's Remoet profile core and/or their visibility. Only provide the fields you want to change. Omitted fields are left as-is; pass null to clear a field. If the source data (CV, website, etc.) is missing a field, ask the user rather than guessing. Never copy placeholder text like "lorem ipsum".
VISIBILITY: pass visibility to control who can see the profile in company candidate lists: NONE (hidden), STARRED (only companies the user has starred, the recommended two-way match), or ALL (every company). Explain the trade-off before changing it.
SUMMARY WRITING GUIDE: the summary is the most important field, the first thing companies read. Pattern: [Role] with [X years] experience in [core tech stack]. [One differentiator or achievement]. Example: "Senior Full-Stack Developer with 8 years of experience in React, Node.js, and AWS. Built and scaled a SaaS platform serving 200K users." Under 500 characters. Avoid generic fluff like "passionate developer". Be specific and quantifiable.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | Your personal website URL | |
| name | No | Your full name | |
| slug | No | Your public profile URL slug (must be unique) | |
| No | Update your email address | ||
| phone | No | Your phone number | |
| summary | No | A brief professional summary or bio | |
| location | No | Your location | |
| avatarUrl | No | Your avatar/photo URL | |
| githubUrl | No | Your GitHub profile URL | |
| twitterUrl | No | Your Twitter/X profile URL | |
| visibility | No | Who can see the profile in company candidate lists: NONE (hidden), STARRED (only companies the user has starred, recommended), ALL (every company). Explain the trade-off before changing. | |
| youtubeUrl | No | Your YouTube channel URL | |
| facebookUrl | No | Your Facebook profile URL | |
| linkedinUrl | No | Your LinkedIn profile URL |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly=false, idempotent=true, destructive=false, openWorld=false, so safety profile is covered. The description adds valuable behavior beyond that: partial-update semantics (omitted vs null), and the semantic meaning of each visibility mode with a recommendation. It does not mention auth requirements, but this is a strong contribution.
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-loads the key update rule, then uses clear headers (VISIBILITY, SUMMARY WRITING GUIDE) to organize supplementary guidance. It is longer than most definitions but the visibility explanation and summary guide each earn their place rather than being 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 14-param, all-optional mutation tool with no output schema, the description covers everything an agent needs: partial-update behavior, field-clearing, the one enum's options, and guidance for the highest-value field. Nothing material 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 coverage is 100%, so the baseline is 3. The description exceeds that by adding meaningful semantics for two parameters the schema only labels: it defines what each visibility enum value does and the trade-off, and provides a structured writing pattern, length limit, and example for the summary field.
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: 'Update the user's Remoet profile core and/or their visibility.' It clearly scopes the tool to core fields plus visibility, distinguishing it from sibling tools like save_work_experience, save_project, and save_education that handle separate profile items.
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?
Gives explicit operating rules: 'Only provide the fields you want to change. Omitted fields are left as-is; pass null to clear a field.' It also says to ask the user when source data is missing a field rather than guessing, and to explain the visibility trade-off before changing it. These are concrete when/when-not instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update the note on a saved job. Use this to add context, track application status, or record follow-up reminders. Pass null to clear the note.
| Name | Required | Description | Default |
|---|---|---|---|
| note | Yes | Updated note, or null to clear | |
| savedJobId | Yes | The ID of the saved job entry (not the job ID) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare non-readOnly, non-destructive, idempotent behavior, so the safety profile is covered structurally. The description adds a genuinely useful behavioral detail beyond that: passing null clears the note, which tells the agent how to reverse the change without opening 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 short sentences, front-loaded with the action and then the use cases, with the null-clearing behavior last. No sentence is redundant.
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 two-parameter tool with rich annotations and no output schema, the description covers purpose, usage contexts, and clearing behavior adequately. It does not state whether an update overwrites or merges with an existing note, which is the one remaining ambiguity for a mutation 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 coverage is 100%, so both parameters (including the savedJobId-vs-jobId distinction and the null-clearing semantics) are already fully documented. The description's "Pass null to clear the note" restates the schema's own wording rather than adding new meaning, 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?
The description states a specific verb and resource ("Update the note on a saved job") and no sibling tool competes for note editing, so an agent can route to it unambiguously. It stops short of the 5 bar only because it never explicitly contrasts itself with adjacent saved-job tools like save_job or unsave_job.
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 gives concrete usage contexts ("add context, track application status, or record follow-up reminders") that tell the agent when this tool is appropriate. It offers no explicit when-not or alternative, but the tool has no real alternative in the sibling list, so the guidance is effectively complete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
search_listings4 fields changedInput schema / properties / page / descriptionPrevious value: -"Page number, starting from 1 (default: 1)"New value: +"Page number, starting from 1 (default: 1). Without a Remoet account the first 10 pages are available."Input schema / properties / page / maximumPrevious value: -10000New value: +10Input schema / properties / pageSize / descriptionPrevious value: -"Results per page, max 100 (default: 20)"New value: +"Results per page, max 20 without a Remoet account (default: 20)"Input schema / properties / pageSize / maximumPrevious value: -100New value: +20update_profile4 fields changedInput schema / properties / email / anyOfRemoved value: -[
- {
- "type": "string"
- },
- {
- "type": "null"
- }
-]Input schema / properties / email / typeAdded value: +[
+ "string",
+ "null"
+]Input schema / properties / slug / anyOfRemoved value: -[
- {
- "type": "string"
- },
- {
- "type": "null"
- }
-]Input schema / properties / slug / typeAdded value: +[
+ "string",
+ "null"
+]update_profile4 fields changedInput schema / properties / email / anyOfAdded value: +[
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+]Input schema / properties / email / typeRemoved value: -[
- "string",
- "null"
-]Input schema / properties / slug / anyOfAdded value: +[
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+]Input schema / properties / slug / typeRemoved value: -[
- "string",
- "null"
-]update_profile4 fields changedInput schema / properties / email / anyOfRemoved value: -[
- {
- "type": "string"
- },
- {
- "type": "null"
- }
-]Input schema / properties / email / typeAdded value: +[
+ "string",
+ "null"
+]Input schema / properties / slug / anyOfRemoved value: -[
- {
- "type": "string"
- },
- {
- "type": "null"
- }
-]Input schema / properties / slug / typeAdded value: +[
+ "string",
+ "null"
+]get_feed1 field changedInput schema / properties / cursor / maxLengthAdded value: +64save_education5 fields changedInput schema / properties / endDate / anyOfPrevious value: -[
- {
- "type": "string"
- },
- {
- "type": "null"
- }
-]New value: +[
+ {
+ "maxLength": 64,
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+]Input schema / properties / endDate / descriptionPrevious value: -"End date (ISO 8601)"New value: +"End date: a date, e.g. \"2024-01-15\""Input schema / properties / institution / minLengthAdded value: +1Input schema / properties / startDate / anyOfPrevious value: -[
- {
- "type": "string"
- },
- {
- "type": "null"
- }
-]New value: +[
+ {
+ "maxLength": 64,
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+]Input schema / properties / startDate / descriptionPrevious value: -"Start date (ISO 8601)"New value: +"Start date: a date, e.g. \"2024-01-15\""save_project8 fields changedInput schema / properties / demoUrl / anyOfPrevious value: -[
- {
- "type": "string"
- },
- {
- "type": "null"
- }
-]New value: +[
+ {
+ "maxLength": 500,
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+]Input schema / properties / endDate / anyOfPrevious value: -[
- {
- "type": "string"
- },
- {
- "type": "null"
- }
-]New value: +[
+ {
+ "maxLength": 64,
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+]Input schema / properties / endDate / descriptionPrevious value: -"End date (ISO 8601)"New value: +"End date: a date, e.g. \"2024-01-15\""Input schema / properties / repoUrl / anyOfPrevious value: -[
- {
- "type": "string"
- },
- {
- "type": "null"
- }
-]New value: +[
+ {
+ "maxLength": 500,
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+]Input schema / properties / shortDescription / minLengthAdded value: +1Input schema / properties / startDate / anyOfPrevious value: -[
- {
- "type": "string"
- },
- {
- "type": "null"
- }
-]New value: +[
+ {
+ "maxLength": 64,
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+]Input schema / properties / startDate / descriptionPrevious value: -"Start date (ISO 8601)"New value: +"Start date: a date, e.g. \"2024-01-15\""Input schema / properties / title / minLengthAdded value: +1save_work_experience5 fields changedInput schema / properties / endDate / anyOfPrevious value: -[
- {
- "type": "string"
- },
- {
- "type": "null"
- }
-]New value: +[
+ {
+ "maxLength": 64,
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+]Input schema / properties / endDate / descriptionPrevious value: -"End date (ISO 8601), or null if current"New value: +"End date: a date, e.g. \"2024-01-15\". Omit it for a current role"Input schema / properties / startDate / descriptionPrevious value: -"Start date (ISO 8601, e.g. \"2024-01-15\")"New value: +"Start date: a date, e.g. \"2024-01-15\""Input schema / properties / startDate / maxLengthAdded value: +64Input schema / properties / title / minLengthAdded value: +1get_apps1 field changedInput schema / properties / page / typePrevious value: -"number"New value: +"integer"get_listing2 fields changedInput schema / properties / checkTechStack / items / maxLengthAdded value: +100Input schema / properties / slug / maxLengthAdded value: +500get_saved_jobs2 fields changedInput schema / properties / page / typePrevious value: -"number"New value: +"integer"Input schema / properties / pageSize / typePrevious value: -"number"New value: +"integer"get_starred_jobs5 fields changedInput schema / properties / locationQuery / maxLengthAdded value: +500Input schema / properties / page / typePrevious value: -"number"New value: +"integer"Input schema / properties / pageSize / typePrevious value: -"number"New value: +"integer"Input schema / properties / searchQuery / maxLengthAdded value: +500Input schema / properties / techStack / items / maxLengthAdded value: +100search_jobs3 fields changedInput schema / properties / companySlug / maxLengthAdded value: +500Input schema / properties / page / typePrevious value: -"number"New value: +"integer"Input schema / properties / pageSize / typePrevious value: -"number"New value: +"integer"search_listings4 fields changedInput schema / properties / page / typePrevious value: -"number"New value: +"integer"Input schema / properties / pageSize / typePrevious value: -"number"New value: +"integer"Input schema / properties / searchQuery / maxLengthAdded value: +500Input schema / properties / techStack / items / maxLengthAdded value: +100apply_to_jobcreate_linktreedelete_linktreedelete_profile_itemget_accountget_appsget_digestsget_feedget_linktreesget_listingget_profileget_saved_jobsget_starred_jobssave_educationsave_jobsave_projectsave_work_experiencesearch_jobssearch_listingsstar_listingunsave_jobunstar_listingupdate_profileupdate_saved_job_note
Add one secure layer between your agents and this server.