score_opportunities

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

With no annotations, the description carries the full burden. It does disclose meaningful behavior: the scoring formula (0-100, title matches weighted 2x), the sort order, and that limit caps postings per source before scoring. It omits whether the call hits the network, rate limits, failure behavior when a source is unreachable, and whether results are deduplicated across sources.

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 opening sentence front-loads the pipeline, the scoring scale, and the sort order, which is exactly what an agent needs first. The Args block is compact and each entry adds distinct information, though the labelled list is slightly heavier than prose would be.

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 four-parameter tool that queries external job sources with no annotations and no output schema, the description covers inputs well but says little about the returned result shape beyond ordering and score range. Source coverage and behavior when a source fails or returns nothing are unaddressed.

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, and it does: capability_keywords gets a concrete example list, query is described as free text passed through to sources, category is identified as an optional Remotive slug, and limit is explained as per-source pre-scoring cap rather than a total. The 2x title weighting also clarifies how keywords are applied.

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 compound action: search job sources, then score each result against capability keywords on a 0-100 scale, sorted descending. It is clear what the tool produces. It stops short of explicitly naming search_jobs as the plain-search alternative, so differentiation from the sibling is left to inference.

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 implied rather than stated: an agent can infer 'use this when you want ranked results rather than raw listings,' and 'search_jobs' is the obvious alternative, but neither the condition nor the alternative is named. No prerequisites, exclusions, or source-selection guidance are given.

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