Skip to main content
Glama
vinayvobbili

jobwatch

by vinayvobbili
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

add_board

Idempotent

Add a company's job board to the watchlist so jobwatch checks it for new roles and alerts.

Instructions

Add a company's board to the watchlist, so fetch_jobs checks it from now on. Find the entry with find_board first and check its sample titles: a guessed board name can belong to another company (list_suggested_boards gives entries for companies whose jobs keep coming in from alerts or HN). Adding one that's already there only updates its name and careers link. For Google, leave name empty: each role keeps its own employer (Google, YouTube, DeepMind). Creates the watchlist when there is none yet. The watchlist is rewritten (a copy of the old one is kept as .bak; comments in a hand-written file are not kept).

Input Schema

NameRequiredDescriptionDefault
nameNoThe company's name as it should show, when the board's own name isn't it (e.g. a Workday tenant id).
entryYesThe board as source:board, the way find_board and list_boards give it (e.g. greenhouse:stripe).
careersNoThe company's own careers site (https://...), for a board whose hosted job pages are offline (fetch_jobs warns about those): its jobs then link there.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.5.0
    • addedInput schema / properties / careers
      Added value: +{
+  "default": "",
+  "description": "The company's own careers site (https://...), for a board whose hosted job pages are offline (fetch_jobs warns about those): its jobs then link there.",
+  "title": "Careers",
+  "type": "string"
+}
  2. Addedv0.3.0

TDQS

A4.8/5.0
Behavior5/5

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

Annotations cover the safety profile (idempotent, non-destructive), and the description adds substantial context beyond them: the watchlist file is rewritten, an old copy is kept as .bak, hand-written comments are lost, and the watchlist is created if absent. That is exactly the side-effect disclosure an agent needs before mutating a file.

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

Conciseness4/5

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

Purpose is front-loaded in the first clause, and every following sentence carries a distinct rule or edge case. It is dense and slightly parenthetical-heavy, but no sentence is filler given the tool's real complexity.

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

Completeness5/5

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

For a 3-parameter write tool with no output schema, it covers the full lifecycle: precondition lookup, dedupe behavior, the special-case parameter value, file-creation, and the destructive aspect of the rewrite. Nothing material to correct invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

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 earns extra by adding behavioral meaning to 'name' (leave it empty for Google because each role keeps its own employer) and by linking 'entry' to how find_board/list_boards present it. The 'careers' parameter is left to the schema alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource+consequence: 'Add a company's board to the watchlist, so fetch_jobs checks it from now on.' That downstream effect cleanly distinguishes it from read-side siblings like list_boards and find_board.

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

Usage Guidelines5/5

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

Explicitly routes the agent: find the entry with find_board first and inspect sample titles, with a stated failure mode (a guessed board name can belong to another company) and a pointer to list_suggested_boards for alert/HN-sourced candidates. Duplicate handling and the Google no-name case are both covered.

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

Deploy Server

Other Tools