watch_intent

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

With no annotations, the description carries the full behavioral burden, and it does well: it discloses that only the anonymous fingerprint and non-PII filter keys are stored, that the server cannot recover the fingerprint, and that the client must persist it. It also reports the return fields. It does not discuss duplicate registration behavior or idempotency, but the privacy and persistence semantics are unusually 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 description is thorough but not bloated. The purpose is front-loaded, and each subsequent section — fingerprint ownership, data-retention guarantees, filter-key catalog, return payload — earns its place. The structure makes the content easy to scan and act on.

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 tool with no annotations, no output schema, and a completely open filters object, the description is remarkably complete. It covers the call's side effects, the client's responsibility, filter semantics, privacy behavior, and the returned fields. An agent has enough to call this correctly and to coordinate with check_watches.

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 must compensate entirely, and it does. It explains the fingerprint's ownership, persistence requirement, and relationship to check_watches, then details the accepted filter keys (skills, required_skills, remote, role_family, min_salary) with matching semantics and an example. This goes well beyond the bare schema's 'additionalProperties: true'.

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 opens with a clear verb and resource: 'Register a standing intent so new matches can be pulled later.' It establishes a distinct purpose that separates this from one-time search tools like search_jobs and from the later retrieval tool check_watches, even before reading any sibling schemas.

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

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

The description clearly explains when to use this tool: to establish a persistent intent whose results are retrieved later. It names check_watches as the companion tool that must receive the identical fingerprint, and references search_jobs for filter-key semantics. It stops short of explicitly stating 'do not use this for one-time searches,' but the context is clear enough.

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