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

The description reveals asynchronous background execution, conditionally idempotent/cheap behavior, the feed_build field on every answer, and the non-obvious warning that a feed still being built is not an empty feed. It does not contradict the annotations; it adds operational detail beyond the generic boolean hints.

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?

Four sentences, each carrying distinct value: core behavior, conditional idempotence, parameter semantics, and required follow-up polling. It is front-loaded with the main operation and contains no filler or repetition.

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 background mutation with no output schema, the definition provides the essential operational contract: what runs, how force/rebuild change behavior, what to do after calling, and why waiting for ready matters. Nothing an agent needs 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?

The input schema only provides two bare booleans with defaults and no descriptions, so the prose is the only explanation. It defines force vs full re-match and rebuild vs rebuild-from-scratch with a use case, compensating fully for the 0% schema coverage.

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 states a specific action and object: matching the account's CV against vacancies added since the last look, in the background. This clearly differentiates it from sibling read-only tools like list_matching_jobs and get_match_status, and from the force/rebuild variants it goes on to define.

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 explicit conditions: use force=true for a full re-match, use rebuild=true when the feed looks wrong, and poll get_match_status until ready before calling list_matching_jobs. This gives an agent a clear call-and-poll workflow rather than leaving the decision to inference.

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