Add an employer to my index

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

Annotations only declare it as a non-readOnly, open-world, idempotent, non-destructive call; the description adds substantial behavior: the employer is flagged user_added, never enters the public snapshot, participates in search_jobs/watch_intent/refresh_index/weekly refresh like a seeded employer, and is reversible via remove_employer. It also discloses the privacy model (vendor sees only the same tenant read the weekly crawl makes; added-employer data stays on the machine).

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 its scope, then routing, refusal cases, and privacy. Information-dense, but the vendor list and refusal list add bulk that could be trimmed without losing much guidance.

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, yet the description enumerates the return fields (added, company_id, jobs_indexed, count_on_board, suggest_for_public_index with its purpose). Combined with the refusal reasons and lifecycle disclosure, an agent has everything needed to call and interpret it.

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 0%, so the description carries the full burden and does: url is the careers/board URL as pasted (with a Workday format example), and name is the display name defaulting to the board's tenant name. Both parameters gain meaning not present in the bare 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+scope: it puts one employer's board into the index on THIS machine and crawls it now. It explicitly distinguishes itself from siblings, naming read_board as the non-storing preview step and remove_employer as the inverse, and contrasting the user's own index with the curated public snapshot.

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?

States when to use (user names an employer the index lacks and has its careers URL), the alternative and the ordering (read_board shows the board first without storing; add_employer is the step after when the user wants it watched), and when the tool is refused (closed portals such as Feishu Hire, SuccessFactors, Taleo, iCIMS, LinkedIn, BOSS直聘).

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