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

Annotations cover read-only and open-world traits, and the description adds genuinely new behavior: boilerplate/nav/ads removal, title and metadata returned, and robots.txt compliance. It still omits failure modes (non-200 responses, blocked-by-robots errors, rate limiting) which matter for a network tool.

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?

Two tight sentences: output shape and content filtering come first, then the use case, then the robots.txt constraint. Nothing is wasted or redundant.

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?

With no output schema, the description carries the return contract and does so adequately by naming Markdown plus title and metadata. The remaining gap is error/edge-case behavior, minor for a read-only fetch tool.

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 url, max_chars, include_links and include_images are already documented with defaults and bounds. The description adds no parameter-level guidance beyond what the schema states, so the baseline 3 applies.

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 states a specific verb and resource (fetch a public web page, return main content as Markdown) plus what is stripped and what extra data comes back (title, metadata). It does not explicitly distinguish itself from the sibling html_to_markdown, though 'fetch a public web page' implies network retrieval rather than converting supplied HTML.

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 clear use context: read an article or docs page for summarising, quoting or RAG. It does not name alternatives such as html_to_markdown or get_link_preview, so the agent must infer routing when it already holds HTML or only needs a preview.

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

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

Annotations already declare readOnly, idempotent and closed-world, and the description usefully confirms the deterministic render contract (fixed 1200x630 PNG output from a title) and that the image itself is returned. It does not mention cost, rate limits or whether titles are truncated, but for a small pure function that is acceptable.

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?

Two tight sentences, with the core operation and output spec front-loaded and the supporting platform list second. No filler or repetition of the tool name.

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?

With no output schema, 'Returns the image' leaves the actual return shape ambiguous (base64 payload, data URI, URL, MIME type), which matters for an agent that must consume the result. All input parameters are covered by the schema, so the gap is limited to the return contract.

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 badge, theme, footer, subtitle and title are all documented in the schema with maxLengths and examples. The description adds only that a title is the source input and the canvas is fixed at 1200x630, which is marginal beyond structured data.

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 (render), resource (Open Graph share image), exact output (1200x630 PNG) and intended consumers (X, LinkedIn, Facebook, Slack, Discord). An agent can immediately tell this generates an image rather than parsing or fetching anything like its sibling tools.

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 purpose line implies when to use it ('for link previews'), but there is no explicit when-not or reference to the closely named sibling get_link_preview, which is the most likely confusion point between generating a share image and retrieving a preview.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the output field list, which is genuinely useful given no output schema, but says nothing about failure modes for non-HTML resources, redirects, or fetch timeouts.

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?

A single front-loaded sentence with the action first and the return payload after a colon. No filler, though the field enumeration is slightly long relative to the one-parameter surface.

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 simple one-parameter read tool with no output schema, the enumerated return fields make the description self-sufficient about results. The only real omission is guidance on unrealistic URLs or missing preview data.

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?

Only one parameter and schema coverage is 100%, with the schema itself noting "http(s) URL to preview". The description repeats "for a URL" but adds no constraints or format detail beyond the schema, so baseline 3 applies.

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 states a specific verb and resource ("Get a link preview for a URL") and enumerates the returned fields, so the agent knows exactly what it produces. It does not differentiate itself from siblings like fetch_url_as_markdown or generate_og_image, which keeps it from a 5.

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?

There is no statement of when to use this versus alternatives, even though fetch_url_as_markdown and generate_og_image occupy adjacent territory. The agent must infer that this is the metadata-extraction option rather than full-page content.

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

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

Annotations already cover read-only, closed-world, and idempotency, so the bar is lower; the description still adds two useful traits beyond them: it does main-content extraction (boilerplate/nav is stripped, not a whole-page dump) and it performs no network I/O. It omits truncation behavior via max_chars and how defaults for include_links/include_images are applied, which would have made this a 5.

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?

Two short sentences, zero filler, and the key differentiator ('Nothing is fetched') is front-loaded. Every clause earns its place.

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?

With no output schema, the description does state the return shape ('clean Markdown of its main content'), which is the essential piece for a converter. What's missing is any note about output size limits (max_chars) and the opt-in nature of links/images, leaving some caller expectations unset for a 5-parameter tool.

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 only 40%: max_chars, include_links, and include_images carry no descriptions at all, and base_url is documented only in the schema. The description adds no meaning to any parameter — it doesn't say that max_chars truncates the output, that link/image inclusion is optional, or how base_url affects relative URLs — so it fails to compensate for the coverage gap.

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 concrete verb (Convert) and resource (HTML → clean Markdown of its main content), and explicitly carves itself out from the sibling fetch_url_as_markdown with 'HTML you already have' and 'Nothing is fetched.' An agent can distinguish the two tools without opening either schema.

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?

'HTML you already have' plus 'Nothing is fetched' gives a clear selection condition: use this when the HTML is in hand rather than retrieved from a URL. It stops short of naming the alternative (fetch_url_as_markdown) explicitly, so the routing is implied rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so safety is covered. The description adds genuinely useful behavioral content by disclosing that results include tunable parameters, their defaults, and their value ranges, which tells the agent this call doubles as configuration documentation. It stops short of describing the returned structure or ordering.

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?

A single front-loaded sentence that names the resource first and then qualifies the payload. No filler, no restatement of the title.

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 zero-param, non-destructive read with no output schema, the agent knows what it will get back at a content level (algorithms, tunables, defaults, ranges). Minor gap: the shape of the response (per-algorithm grouping, ordering, how ranges are expressed) is unspecified, but that is a small omission for a simple listing tool.

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 tool takes no parameters (empty object schema, 100% coverage), so the baseline of 4 applies. There is nothing for the description to disambiguate at the input level.

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 ('List') plus resource ('rating algorithms') and an explicit statement of what the payload carries ('tunable parameters with defaults and ranges'). Nothing among the siblings (parsers, matchers, image/URL utilities) overlaps with this discovery function, so an agent can select it unambiguously.

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 only implied: an agent infers this is the discovery step before calling rate_matches or predict_match, but the description never says so, nor does it state any exclusions or prerequisites. Adequate for a zero-parameter read tool, but the when-to-use routing is left to inference.

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

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

Annotations already establish readOnly, idempotent, closed-world behavior, so the description does not need to argue safety. It adds real value by disclosing the response content (score plus per-dimension breakdown and matched/missing skills), which matters because no output schema exists. It does not say whether inputs are normalized or how ties/partial data are handled, keeping it below a 5.

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?

A single front-loaded sentence that packs the purpose, the scoring range, the breakdown dimensions, and the skill-diff output with no filler. Every clause earns its place.

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?

With no output schema, the description carries the return-value burden and does so reasonably by enumerating the breakdown dimensions and matched/missing skills. What is missing is routing versus the overlapping siblings predict_match and rate_matches, which matters in this family of scoring tools.

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% and both top-level parameters are documented in the schema, including the note that resume may be plain text or the JSON returned by parse_resume. The description adds nothing beyond that, so the baseline 3 applies.

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 and resource (score a resume against a job posting) and also names the output scale (0-100) and breakdown dimensions, so the agent knows exactly what it gets. It is distinguishable from parse_resume/parse_job_posting, which produce inputs rather than scores.

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 by the name and description: use it when you have both a resume and a job and want a fit score. However, siblings predict_match and rate_matches plausibly overlap with this, and the description gives no when-to-use/when-not guidance or prerequisite chain (e.g. call parse_resume first) to disambiguate.

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

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

Annotations already declare readOnly, idempotent and closed-world, so safety is covered; the description adds real value by specifying the derived output surface (salary normalized/annualised, seniority, remote regions, flags), which no output schema documents. It stops short of saying what happens with missing optional fields or how confidence/ambiguity is handled.

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?

A single sentence, front-loaded with the verb and resource, then the payload of output fields. Every clause adds information an agent could act on; nothing is padding.

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?

With no output schema, the field enumeration in the description is doing the necessary work of describing the return shape, which mostly completes the picture. Remaining gaps are minor but real: the tool takes one posting while a batch sibling exists, and there is no hint about handling of missing description or malformed ads.

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 title, company, location and description are fully documented in the schema itself. The description adds no parameter-level guidance (e.g. that description is the main source of salary/skills extraction, or what happens when it is omitted), so the baseline 3 applies.

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 ('parse') plus resource ('a job ad') with an explicit enumeration of the output fields produced, which tells an agent exactly what this returns. It does not differentiate itself from the sibling parse_job_postings_batch, though the singular/plural naming makes the split inferable.

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 only implied: the description makes clear it parses a single job ad, so an agent can guess it is the right pick over the batch or resume variants. There is no explicit when-to-use statement, no prerequisites, and no named alternative such as parse_job_postings_batch for multi-posting input.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds genuinely non-annotated behavior: the 1–20 batch limit and the guarantee that results come back in the same order as inputs. It omits per-item failure semantics (does one bad posting fail the whole batch?) and cost/latency implications of batching.

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?

A single sentence, front-loaded with the action and scope, with the ordering guarantee appended. Nothing is wasted and nothing needs to be re-read.

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?

With no output schema, the description is the only source for what a 'parsed posting' returns, and it only says the results are order-matched — it never mentions the extracted fields (salary, skills, flags) that the input schema hints at. For a batch-mutation-free parsing tool with one parameter this is workable but leaves the return shape and partial-failure behavior undefined.

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?

Only one parameter, an array, and the top-level 'postings' property carries no description in the schema (reported coverage 0%). The description compensates partly by stating the accepted cardinality (1–20) and output ordering, but says nothing about what each posting object must contain (title required) or how the description field drives extraction — that information lives only in the nested item 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?

States a specific verb and resource ('Parse ... job postings') plus the batch scope ('1 to 20 ... in one call'), which implicitly separates it from the singular sibling parse_job_posting. However, it never names that sibling or say 'batch' explicitly in the description body, so the differentiation is inferred from the number rather than stated.

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?

There is no when-to-use guidance, no mention of when to prefer the singular parse_job_posting, and no prerequisites or exclusion conditions. The only hint is the cardinality range, which implies 'use this for multiple postings' but leaves the choice between siblings to the agent.

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

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

Annotations already declare readOnly, idempotent, closed-world, so the description earns credit for adding constraints the annotations can't express: 5 MB cap, PDFs must have a text layer, no OCR, and 'Nothing is stored'. These are exactly the preconditions that would otherwise cause silent failure. It stops short of describing failure behavior when a scanned PDF or oversized file is passed.

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?

Two sentences, front-loaded with the purpose and return shape, followed by the input contract and the single most important caveat (no OCR) and privacy note. No filler or repetition of the title.

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?

With only two simple params, full schema coverage, and rich annotations, the definition covers what an agent needs: output shape, accepted inputs, size/format limits, and that nothing is persisted. Minor gap: no guidance on what happens if both text and file_path are supplied, or on error responses.

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 100%, so baseline is 3, but the description adds genuine meaning beyond the schema: the 'either/or' exclusivity of text vs file_path is not encoded in a oneOf/anyOf, and the accepted file types, 5 MB limit, and no-OCR rule elaborate on the terse 'Path to a local PDF, DOCX or TXT file'.

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 (parse) plus resource (resume/CV) and immediately enumerates the output fields (contact details, title, seniority, function, experience, education, skills), so the agent knows exactly what comes back. The name plus this enumeration distinguishes it cleanly from siblings like match_resume_to_job or predict_match, which consume rather than extract resume data.

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 sentence 'Give either the text or a local file path' implies the two input modes and their mutual exclusivity, which is useful invocation guidance. However, it never states when to prefer this tool over parse_job_posting or when to hand results to match_resume_to_job, so the workflow positioning is only implied.

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

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

Annotations already declare readOnly, idempotent, and closed-world, so the safety profile is covered. The description adds that the prediction is a pure function of current ratings (no rating mutation), which is useful, but says nothing about what happens with unrated/unknown players or whether results are deterministic across algorithms.

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?

A single well-formed sentence with the action and outputs front-loaded and no filler. It is lean to the point of omitting input requirements, but nothing in it is wasted.

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 4-parameter tool with nested objects and no output schema, the description covers the conceptual output but leaves gaps: it never explains the nested teams array, the players payload requirement, or how algorithm choice affects results. Adequate but incomplete.

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?

At 75% schema coverage the schema already documents params, players, and algorithm. The description adds only the interpretive detail that teams produce one probability per team and that quality measures evenness; it does not clarify the nested team-of-players structure or the meaning of the free-form params overrides.

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 (predict) and precisely names the outputs: each team's win probability plus match quality. That distinguishes it functionally from the rating-update sibling rate_matches, though the description never names that sibling explicitly.

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?

'from current ratings' implies the prerequisite that ratings must already exist, and the players schema hints at a prior rate_matches call, but the description itself gives no explicit when-to-use or when-not-to-use guidance relative to rate_matches or list_rating_algorithms.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description usefully adds that the operation is stateless and how to continue a rating history, but it says nothing about the returned payload (per-player mu/sigma/games), error behavior, or the 5000-match input cap — details an agent cannot get anywhere else since there is no output schema.

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?

Three short sentences with zero waste: capability first, supported scenarios second, the non-obvious statelessness contract last. Everything is front-loaded and nothing repeats the name or title.

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 nested, multi-algorithm batch tool the description covers what matters for correct invocation, and the rich input schema supplies the field-level detail. The main residual gap is the absence of any statement about the return value, which matters given no output schema exists.

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 75% and the schema already documents ranks, teams, weight, winner and the algorithm enum. The description reinforces that `players` carries prior ratings, but adds no new semantics for the `params` override object or the per-match fields beyond what the schema states.

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 and resource ('Compute player skill ratings from match results') and narrows the supported formats and algorithms (1v1, teams, free-for-alls, draws; OpenSkill/Glicko-2/Elo). It implicitly separates itself from predict_match by framing the work as deriving ratings from completed results, but it never explicitly names that sibling, so an agent weighing the two must infer the split.

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: use it when you have finished match results and need updated ratings, and re-feed prior ratings via `players` to chain calls. There is no explicit when-not guidance and no mention of the obvious alternatives (predict_match for hypothetical outcomes, list_rating_algorithms for choosing an algorithm).

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