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

Goes well past the annotations, which only state readOnly/idempotent/openWorld/non-destructive. It discloses the scoring pipeline (title, level, location, then skills and years for the best ones), the shape of the output (score, level-fit verdict values match/step_up/stretch/step_down, reasons and gaps), an important caveat that this is a rule-based match against public postings rather than a hire prediction, and a data-handling promise that the profile is used only during the call.

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?

Purpose and trigger are front-loaded, and the sentences about scoring, returns, and privacy each carry real information. The enumeration of profile fields partially duplicates the schema and could be trimmed, keeping it just short of 5.

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 9-parameter, open-world ranking tool with an output schema and rich annotations, the description covers inputs, ranking logic, result semantics, caveats, and privacy. The one meaningful omission is routing relative to the overlapping siblings find_company_jobs and job_fit_brief.

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 description coverage is 100%, so the schema already documents every parameter, including the level fallback and the 1-5 / up-to-3 limits. The description only loosely restates which fields to pass and flags some as 'where known,' without adding syntax, format, or interaction detail beyond the schema. Baseline 3 is appropriate.

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?

States a specific verb+resource+scope: 'Rank the open jobs at up to 3 companies for a person's profile.' An agent immediately knows this produces an ordered, scored list rather than raw postings. However, it never names or contrasts with the sibling tools find_company_jobs or job_fit_brief, which plausibly overlap (discovering jobs vs. briefing on fit), so the agent must infer the boundary.

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?

Gives a concrete trigger ('when the user wants to know which jobs suit them') plus a worked example question about a senior backend engineer. Clear about when to use it, but offers no when-not guidance and no explicit alternative to pick instead.

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