Nymrel

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

Beyond the annotations (readOnly, openWorld, non-destructive), the description discloses important behavioral traits: results may be only an aggregate summary, per-check evidence may or may not be included, and absent checks must not be reported as proof. It also warns this is not a ranking guarantee or security/legal/crawler-access certification. This adds substantive context not covered by annotations, though it does not mention rate limits or latency.

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 front-loaded with the purpose, then moves to output variability and evidential caveats. Every sentence carries useful information, though the caveat block is slightly dense and could be tightened without losing meaning.

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?

An output schema exists, so return values need not be fully explained, and annotations already cover the safety profile. The description fills the remaining behavioral gaps (output variability, evidence handling, certification caveats) well, with the only notable omission being parameter-level URL guidance.

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?

With one required parameter and 0% schema description coverage, the description must compensate. It says 'one public website,' which weakly implies the URL target, but it gives no format guidance (http/https), no statement about reachability, and no syntax details. The parameter remains largely undocumented.

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 specific verb and resource: 'Audit one public website for SEO, schema, and AI discoverability.' It states scope ('one public website') and the exact domains checked, so an agent can distinguish it from the unrelated sibling tools without opening the 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?

The scope is implied by 'Audit one public website,' but there is no explicit when-to-use guidance, no alternatives named, and no prerequisites (e.g., whether the site must be reachable). The caveats at the end are limitations, not usage routing, so guidance remains implied rather than explicit.

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?

Substantially beyond annotations: it explains that availability is only reported when the registry clearly says free, that inconclusive lookups produce availability_checked=false and available=false meaning 'not confirmed' rather than 'taken', and that some TLDs have no registry service. It also discloses that brandability_score is subjective and that brandability_factors exposes the inputs.

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?

Front-loaded with the core action, then structured into two short caveat paragraphs. Slightly verbose in places but every sentence carries useful semantics; nothing 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?

An output schema exists so return formatting need not be described, and annotations cover safety and open-world behavior. The one gap is the missing explanation of the required keyword_or_concept parameter, but otherwise the description is complete for calling the tool correctly.

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 50%; the tlds parameter is fully documented in the schema including its leading-dot regex constraint and defaults, but keyword_or_concept is undocumented anywhere. The description adds no parameter meaning, form, or constraints beyond what the schema already provides.

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 pair: suggest domain names and check them against public registry records. That is distinct from every sibling tool in the list, none of which deal with domain availability.

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 implies usage through caveats (confirm at a registrar, read inconclusive results as not-confirmed-free) but never states when to choose this tool over another or what prerequisites exist. Sibling tools are unrelated, so alternatives guidance is not strictly needed, but explicit when-to-use framing is missing.

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, destructiveHint=false and openWorldHint=false, so the description is only responsible for input-contract behavior — and it delivers the non-obvious parts: a 1–14 club range, unique-name requirement, and a strict 'upstream rejects any other key' validator warning. It says nothing about cost, latency, or how the analysis is performed, which keeps it out of 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?

Three tight sentences with the core purpose front-loaded, then requirements, then the strict-validation warning. No filler, though the 'only these three' phrasing mildly duplicates the schema's additionalProperties: false and could have been folded into the previous sentence.

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?

An output schema exists, so return values need no explanation, and the remaining risk surface for this single-array-parameter tool — item shape, cardinality, uniqueness, unknown-key rejection — is fully covered. Nothing an agent needs to construct a valid call 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?

Schema description coverage is 0% at the top level, so the description must carry the parameter burden — and it does: it states that 'name' and 'carry_distance_yards' are required, 'loft_degrees' is optional, and that only these three keys survive the upstream validator. The cardinality (1–14) and name-uniqueness rules appear nowhere in the JSON schema and are the kind of detail that prevents failed calls.

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 verb ('Analyse') and resource ('carry-distance gaps' for golf clubs), so an agent knows this is an analytical tool over a supplied club list rather than an audit/search utility. It stops short of 5 because 'gaps' is never unpacked — what dimension of gap is computed stays implicit and only becomes clear from the output 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?

'Pass 1 to 14 clubs with unique names' gives input constraints but never states when an agent should reach for this tool versus not calling it at all. With an entirely unrelated sibling set there is no routing risk, yet the description still leaves the use case 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?

The annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that the tool returns metadata rather than file content and that device selection is optional, but it does not describe error behavior, permission requirements, or what metadata fields are returned.

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 usage condition, and no wasted wording. The optional device instruction is placed exactly where it is needed.

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?

There is no output schema, so the description should clarify what 'metadata' includes or at least its scope. It says metadata is returned for a file or directory, which is adequate for basic selection, but an agent would benefit from knowing whether sizes, timestamps, permissions, or types are included.

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 both path and device are fully documented in the schema. The description only mentions the optional device argument and does not add syntax, format, or path-resolution semantics beyond what the schema already provides.

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: return metadata for a file or directory via Nymrel Remote. It implicitly distinguishes itself from content-reading siblings like nymrel_remote_read_file by saying 'metadata', but it does not explicitly name or compare siblings.

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 a clear trigger: use when the user explicitly wants metadata for a file or directory. It does not state when not to use it or name alternatives such as nymrel_remote_list_directory or nymrel_remote_read_file, but the intended context is clear.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is clear. The description adds meaningful context beyond that: it 'never starts a new device operation' and advises waiting briefly if the result is still pending, which is important polling behavior not captured by annotations.

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 short and front-loaded with the core action. The 'never starts a new device operation' and 'instead of submitting that inspection again' sentences overlap somewhat, but the polling advice earns its place and overall there is little waste.

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 one-parameter, read-only retrieval tool with no output schema, the description covers the essential scenario, the anti-pattern to avoid, and what to do while pending. It could say more about what the result contains or where callId comes from, but the missing pieces are minor against the annotations and simple schema.

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 carry parameter meaning. It does state that callId is used to retrieve the result of a pending read, which adds some semantic context, but it does not describe the expected format or origin of callId beyond that. This is adequate but not rich compensation for the schema 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?

The description states a specific verb and resource ('Retrieve the result of your pending Nymrel Remote read') and ties it to a callId. It distinguishes this from re-submitting an inspection, though it does not explicitly name the sibling tools such as nymrel_remote_read_file or nymrel_remote_get_file_info.

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 when-to-use guidance ('If a file inspection returns pending, use this tool instead of submitting that inspection again') and a clear anti-pattern to avoid (re-submitting the inspection). It also adds a fallback instruction for repeated pending status, leaving little ambiguity about when to invoke this tool versus re-running the read.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that each result includes current reachability, which is meaningful beyond the annotations, but it does not say whether that status is live-probed or cached, which matters given openWorldHint=false.

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?

One sentence of appropriate length for a zero-parameter list tool, with the trigger condition front-loaded and no redundant restatement of the title or annotations.

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 parameters, no output schema, and annotations covering the safety profile, the description carries what an agent needs: what is listed and why. It could be slightly stronger by noting the identity fields returned that the follow-up remote_* tools expect as input.

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 zero parameters, so there is no parameter semantics to explain; the baseline of 4 applies. The description correctly implies the call is unfiltered and returns the full paired-device set.

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: listing paired Nymrel Remote devices together with their current reachability. That is clearly distinct from the other nymrel_remote_* siblings, which all operate on files, directories, or read results, though it does not name them 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?

"Use this when the user wants to see paired devices... before working with one" gives an explicit trigger condition and positions the tool as the discovery step preceding the other remote_* tools. No exclusion cases are stated, and nothing tells the agent what to do if the list is empty.

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, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds only a hint that recursion is depth-capped, and its device-selection remark restates the schema rather than adding behavior — nothing about ordering, entry format, error handling on a missing path, or size limits on large trees.

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, no padding, and the trigger condition is front-loaded ahead of the parameter note. Slightly wasteful that the device sentence repeats guidance already present in the schema.

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?

There is no output schema, so the description is the only place a caller could learn what a directory listing returns, and it omits that entirely — entry shape, ordering and whether files and directories are distinguished are unstated. For a read-only three-parameter tool this is a modest rather than severe gap.

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 67%; path and device are documented in the schema, while depth carries no schema description at all. The description calls it 'bounded recursion depth' but never explains what depth=1 yields, that the default is 2, or that the max is 8, so the one undocumented parameter is not compensated for.

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 ('list a directory tree') on a named system, and the 'bounded recursion depth' phrasing separates it from the flat-listing or search siblings like nymrel_remote_search_files. It stops short of explicitly naming which sibling to use instead, so it is clear but not fully differentiated.

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?

'Use this when the user explicitly wants Nymrel Remote to list a directory tree' gives a positive trigger condition, but there are no exclusions and no named alternatives, even though nymrel_remote_search_files and nymrel_remote_search_content sit right beside it. The agent must infer when a search tool is a better fit.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the useful constraint that only UTF-8 text files are supported and that pagination is line-based, but it says nothing about failure modes for binary/non-UTF-8 files or whether results must be fetched via the sibling get_read_result.

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 tightly-scoped sentences with the usage condition front-loaded and no filler. The second sentence on the device argument is somewhat redundant with the schema's detailed device description, but it is short enough not to bloat the definition.

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 four parameters, 75% schema coverage, and no output schema, the description is adequate but leaves a notable hole: a sibling named nymrel_remote_get_read_result strongly suggests reads may be asynchronous, and the description never mentions that follow-up step or how results are returned.

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 75%, with path and device documented in-schema, so the baseline is 3. The description adds meaning for 'length'/'offset' by framing them as optional line pagination, but it does not clarify the tail-read behavior of negative offsets or the default page size beyond what the schema shows.

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 ('read a UTF-8 text file') plus the scope of pagination support, which cleanly separates it from siblings like nymrel_remote_get_file_info or nymrel_remote_search_content. It never names those siblings, so an agent must infer the boundary rather than being told.

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?

'Use this when the user explicitly wants Nymrel Remote to read...' gives a clear selection trigger and the 'explicitly wants' qualifier usefully implies this shouldn't be speculative. No when-not conditions or named alternatives are given, so it stops short of full routing guidance.

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, non-destructive, closed-world, so safety is covered. The description adds that content must be UTF-8 and that paths are constrained to an "allowed path" sandbox, which is genuinely extra. It says nothing about result truncation relative to maxResults, depth limits, or whether pattern is interpreted literally or as a regex, which are the behaviors most likely to surprise a caller.

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, constraint-first, and every clause carries information. No filler or restatement 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?

Eight parameters, no output schema, and low schema coverage mean the description should carry more weight than it does. For a file-content search, the interpretation of pattern, the maxResults truncation default, and what a match result looks like are all 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 only 25%: path and device are documented, six parameters (pattern, maxDepth, ignoreCase, maxResults, filePattern, literalSearch) are not. The description repeats the device guidance already in the schema and never explains that pattern is matched literally by default (literalSearch=true defaults) or that results are capped by default — a materially important distinction the schema does not state.

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 plus scope: search UTF-8 file contents below an allowed path. The word "contents" implicitly separates it from the sibling nymrel_remote_search_files, but the sibling is never named, so an agent must infer the distinction.

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?

"Use this when the user explicitly wants..." gives a usage context and implicitly sets a bar (explicit request) before calling. It never names the obvious alternative (nymrel_remote_search_files) or says when searching names is preferable over contents, so the routing decision 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 declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the useful constraint that searching is confined to an allowed path, but says nothing about result caps, ordering, or what happens when maxResults truncates matches.

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, front-loaded with the usage condition and followed by the device hint. No padding, though the second sentence spends space on something the schema already says.

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?

Six parameters, no output schema, and only a third of the schema documented. For a search tool the description should at least clarify pattern matching semantics and default result limits; instead an agent must guess how 'pattern' is interpreted and whether results are capped at maxResults=100 by default.

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 33%: only path and device are documented in the schema, while pattern, maxDepth, ignoreCase and maxResults are bare. The description's only parameter remark ('Select the target with the optional device argument') merely restates the schema, and it never explains whether pattern is a glob, regex, or substring match — the single most important semantic here.

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 ('search file and directory names') plus a scope ('below an allowed path'), and the 'names' qualifier implicitly separates it from nymrel_remote_search_content. It stops short of naming that sibling explicitly, so the separation requires 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?

'Use this when the user explicitly wants...' gives a trigger condition, which is more than nothing, but there are no exclusions and no named alternative — notably it never says to use nymrel_remote_search_content instead when the user wants file contents rather than names.

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=false, and the description still adds real behavioral context: it enumerates the measured signals, explains that hook_score is a 0-100 rollup of exactly those signals, promises suggested edits, documents alias normalization, and warns that every figure describes only the supplied text — an epistemic scope statement the schema and annotations cannot convey.

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?

Front-loaded with the core action and the outcome disclaimer placed last where it belongs. The signal enumeration in the second paragraph partially duplicates what an output schema already exposes, and the 'rollup of exactly those signals' phrasing is a touch redundant, but 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 an output schema present and annotations covering safety, the remaining burden is scope and input expectations; the description handles scope thoroughly (text-only, no real-world outcomes) and platform aliasing. The one thing an agent could still get wrong — what constitutes valid transcript_text — is 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 description coverage is 0%, so the description must carry the load — and it does for target_platform, naming the canonical values and explaining that `reels`/`shorts` normalize and are echoed back in the result, which is information present nowhere in the schema. However, the required transcript_text parameter is never characterized (expected format, whether timestamps or markup belong in it), leaving a genuine 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 specific verb and resource: measures what the opening of a short-video transcript does, returning named signals plus a 0-100 hook_score. It also draws an explicit boundary ('does not estimate reach, views, retention or virality') that prevents confusion with an analytics tool, and no sibling in the list overlaps in purpose.

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 when-not is explicit and strong: the tool never estimates reach, views, retention or virality, and 'Read `signals` to see what moved the score' tells the agent how to interpret results. What's missing is a positive when-to-use cue (e.g., before publishing a script) or a named alternative, so it stops short of the 5 bar.

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