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

With no annotations present the description carries the full burden, and it does meaningful work: it discloses persistence location (~/.backlink-mcp/custom.json), that the entry survives updates, and the conditional visibility rule for location (only shown for projects in that area). It omits whether duplicate URLs are rejected, validation rules on url, and the effect of priority.

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 action and its consequence, then parameter guidance in priority order. Dense but every clause carries information; the parenthetical file path and data.py reference are slightly internal-facing noise but still orienting.

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 7-parameter mutation with no annotations and no output schema, the description covers the high-value fields and persistence behavior but leaves priority, notes, URL format and duplicate handling undefined, so an agent could still call it incorrectly or redundantly.

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% across 7 parameters, so the description must compensate and it partially does: tags gets an example and a pointer to NICHE_TAGS, region gets accepted formats (global, country name/code, EU/GCC/ANZ/NA/SEA), and location gets conditional-display semantics. name, url, notes and priority are left fully unexplained.

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 ('Add your own directory/citation site') plus the downstream effect ('so find_opportunities includes it from now on'), which distinguishes it from sibling registration tools like add_custom_footprint. An agent knows exactly what this mutates and what it changes in later calls.

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?

Implies clearly when to use it: when the user has a directory/citation site not already in the built-in set and wants it surfaced by find_opportunities. It does not address when-not-to-use (e.g. duplicates already in the catalog, or the distinction from add_custom_footprint), so no explicit alternative routing.

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?

With no annotations, the description carries the full burden, and it does disclose the key side effect: the footprint is written to custom.json. It says nothing about whether re-adding an existing group overwrites it, whether validation occurs, or whether the new footprint is immediately usable by sibling scan tools.

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 action and persistence target, then the placeholder rules and an example. Two tight sentences with little waste, though the example is somewhat long relative to the payload it illustrates.

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 two-parameter write tool with no output schema and no annotations, the description covers purpose, persistence destination, and query syntax. The missing piece is the semantics of 'group' and overwrite behavior, but the essentials for a correct call are present.

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. It does well for 'query', naming the three placeholders {kw}, {loc}, {country} and showing a full example, but 'group' is never defined beyond appearing in the sample as "local" — its role as a label/bucket is left to inference.

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 and resource — adding a custom search footprint persisted to custom.json — and explains the templating it expects. It does not, however, distinguish itself from the sibling add_custom_directory, which an agent could easily confuse it with.

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 ('Add your own search footprint'), with no statement of when to prefer this over add_custom_directory or how the resulting footprint is later consumed by the scan tools. The worked example gives a sense of intended shape but not of selection criteria.

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?

With no annotations, the description carries the burden and does well: it discloses merge precedence ('cached scan profile with fields you pass (yours win)'), input validation behavior (placeholders like XXXX, 20XX, 'your address' are rejected and never saved), a filesystem side effect (saves .md + .json), and one return key (needs_review). It omits whether existing files are overwritten, where files are written, and what happens if no cached profile exists.

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?

About 70 words, front-loaded with the artifact and purpose, then precedence, then validation, then return value. Nearly every clause carries information; the only mild inefficiency is the abbreviated 'Saves .md + .json' without stating where.

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 15-parameter, no-annotation, no-output-schema tool that writes files, the description covers the workflow and the critical validation/precedence behavior, but leaves the majority of parameters unexplained and only names one of presumably several return fields. Adequate to call correctly, not complete.

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% across 15 parameters, so the description must compensate and largely does not. It explains the precedence rule for passed fields and implies name/address/phone/description are the core ones, but never clarifies the save flag's default-on file-writing behavior, the socials/services array vs null semantics, or fields like category, founded, and country.

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 artifact: 'Build one consistent Name/Address/Phone + descriptions kit for directory/citation sign-ups.' That is clearly distinct from siblings like scan_site (which produces the cached profile) and generate_schema (which it explicitly says reuses the kit). It stops short of a full sibling differentiation statement, but the artifact it produces is unambiguous.

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: you build the kit before directory/citation sign-ups and fix 'needs_review' items before submitting, and generate_schema reuses the output. There is no explicit 'do not use when' or a named alternative for the case where no cached scan profile exists.

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?

With no annotations, the description usefully discloses the most consequential behavior: it never sends anything and only produces a draft for the user to handle. It also discloses missing-requirement warnings, though it does not clarify whether warnings accompany a draft, block generation, or whether any draft is persisted.

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 safety-critical purpose is front-loaded, followed by scannable parameter guidance and a concise warning behavior note. The examples and emphasis on one specific hook are practical rather than redundant, with no significant filler.

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?

The definition is sufficient for a basic invocation using the three required parameters and explains the central no-send safeguard. For an 11-parameter tool with no schema descriptions, annotations, or output schema, it remains incomplete because template-dependent fields, warning behavior, and the roles of several inputs are unspecified.

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 description adds substantial meaning beyond the schema for template, topic, proof, and hook, including allowed template values, formats, and examples. However, schema coverage is 0%, and my_site, my_name, my_page, target_site, contact_name, broken_url, and extra receive no explanation or template-specific usage guidance.

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 opening sentence clearly states the verb and resource: drafting an outreach email for the user to edit and send. The eight template options clarify its outreach scope, although there is no explicit differentiation from the closest sibling, build_submission_kit.

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 concrete usage context, including list_inclusion for "top N companies" roundups, factual proof, and a page-specific hook to avoid mass-email wording. It does not explain when to prefer this tool over build_submission_kit or provide per-template selection and input requirements.

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?

With no annotations, the description carries the full burden. It usefully discloses that output is two-part (matched sites plus ready-to-run queries) and that the agent must execute those queries externally rather than the tool doing so. It says nothing about empty/no-match results, read-only nature, cost, or limits, which matters for a 0-schema 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?

Purpose is front-loaded in the first sentence, with usage and precedence notes following. The long niche example list is useful grounding rather than fluff, though the single undifferentiated paragraph makes it slightly harder to scan than a short structured list.

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 six-parameter tool with no annotations and no output schema, the definition does well to describe the shape of the return value and the site-vs-explicit precedence. It is still incomplete on direct semantics for keywords/competitors and on what happens when no opportunities match, gaps an agent would have to discover at call time.

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 compensate. It documents site's precedence meaning, gives a rich example list for niche, and states country accepts a name or code. Keywords, location, and competitors are only mentioned as values inherited from a saved site, not explained as direct inputs, leaving three of six parameters loosely defined.

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+resource+scope: return backlink opportunities, comprising citation/directory/profile sites plus footprint search queries. That is highly distinctive from siblings like draft_outreach or verify_backlink. It never names an alternative tool, so it stops short of explicit sibling differentiation.

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 tells the agent to run the returned queries with web search, and explains the precedence rule for the site parameter ('anything you pass wins'), which is exactly the decision an agent needs to make. It does not say when not to use this tool or point to a sibling alternative.

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?

With no annotations supplied, the description carries the burden and does well: it discloses the key behavioral guarantee that missing fields are 'listed, never invented', describes the output as a script tag, and enumerates accepted business_type values. It does not state whether anything is persisted server-side or what happens if the domain has no saved kit/scan, which leaves a material gap for an unannotated 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?

The description is front-loaded with the action and output, then the paste instruction, then the business_type enumeration, then the missing-field guarantee. Every sentence carries information, though the line-broken formatting and trailing '...' enumeration are slightly ragged.

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 generator with no output schema, the description covers the output shape (script tag with named JSON-LD fields), the source data, and null-handling behavior. The remaining hole is failure modes and prerequisites when no kit or scan exists, which an agent would want spelled out.

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 compensate. It partially does: business_type gets a long enumeration of valid values, and the JSON-LD field list clarifies what domain/area_served/price_range feed into. However, those three parameters are never defined directly, and 'domain' in particular (site domain vs. property domain) is left to inference.

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 and artifact: 'Generate ready-to-paste LocalBusiness JSON-LD' with an explicit field list, and it names the source of truth ('the saved submission kit (or the last scan)'). This also implicitly separates it from siblings like build_submission_kit and scan_site, which produce or refresh that source rather than the schema artifact.

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 states the precondition (a saved submission kit or the last scan must exist) and the post-step ('Paste the returned script tag into your site's <head>'), so an agent knows the surrounding workflow. It does not explicitly say when to prefer this over build_submission_kit or what to do when neither source exists, 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?

With no annotations supplied, the description carries the full behavioral burden. It usefully discloses data provenance — results derive from a cached scan, so output may be stale and depends on a prior run — and the word "suggest" implies a non-mutating read, but it never confirms read-only behavior, permissions, or what happens when no cache exists.

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 concrete output format front-loaded before the rationale. The second sentence (backlink equity) is mild motivational context rather than operational guidance, but it is short enough to earn 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?

An output schema exists, so return values need not be explained, and the tool is low complexity with only two parameters. However, the key operational question — which cached scan the domain must match, and how the limit affects results — is left unresolved, which is a real gap for an agent trying to call it 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 description coverage is 0% for two parameters, and the description never mentions either `domain` or `limit`. The phrase "cached scan" weakly implies the domain scopes to a previously scanned site, but nothing explains what `limit` bounds (number of suggestions? pages analyzed?) or its default of 20.

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 and resource — suggest internal links — and even specifies the returned shape (source page -> target page, anchor text) plus the targeting criterion (weakly-linked pages, keyword overlap). It does not explicitly contrast itself with siblings such as seo_link_audit or find_opportunities, so an agent must infer the boundary from the resource name alone.

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?

"For weakly-linked pages" implies the situation where this tool is appropriate, and "from the cached scan" hints at a prerequisite (a prior site scan), but neither the prerequisite nor any alternative tool is stated explicitly. There is no when-not guidance, so the agent must guess whether to run this before or after the audit tools.

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?

With no annotations, the description must carry the behavioral burden. It implies a read operation and discloses returned content fields (niche, location, country, tracker progress), but it omits pagination, ordering, scope limits, and an explicit read-only guarantee.

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 a single, front-loaded sentence with no wasted wording. It immediately states what is listed and what fields are included.

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-parameter tool with no annotations and no output schema, the description is only partially complete. It names key returned fields but does not describe pagination, ordering, response shape, or whether all projects are returned at once.

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 parameter semantics are inherently simple. The description does not add parameter meaning, but no parameters exist to explain, matching the baseline for a zero-parameter tool.

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 gives a specific verb and resource: 'List every site you've scanned or saved,' making clear this is a project/site listing tool. It distinguishes from siblings like save_project and scan_site by describing the read-side inventory, though it does not explicitly name alternatives such as tracker_list.

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 explicit when-to-use guidance or comparison to alternatives. The agent can infer it is for viewing scanned/saved sites, but nothing says whether to use this versus tracker_list or when not to use it.

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?

With no annotations, the description carries the full burden and largely meets it: it discloses that the tool performs network fetching, follows contact/about/write-for-us subpages, checks noindex and sponsored-only policies, and produces a template recommendation. What's missing is any sense of cost, rate limits, or failure behavior on unreachable pages.

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 score, then the detection list, then the parameter note. Every clause carries information, though the long semicolon-chained sentence makes it denser than it needs to 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?

No output schema exists, so the description has to describe returns — and it does, citing a 0-100 score, detected page types, found emails, and a template recommendation. A brief note on how the result is shaped (single object vs. nested sections) would close the remaining 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 0%, so the description must compensate and only partly does. It explains topic_keywords well with a concrete example and describes its default source, but url is never characterized (absolute URL? existing page only?) and my_domain's role is only obliquely implied through the keyword-lookup sentence rather than stated.

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?

Opens with a specific verb+resource+output: "Fetch a prospect page and score it 0-100," then enumerates exactly what the fetch inspects (guest-post pages, roundups, resource pages, noindex, spam links) and that it returns an outreach template. That level of detail clearly separates it from scan_site and find_opportunities.

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 prospecting context, and the topic_keywords fallback ("if omitted, the saved project's keywords for my_domain are used") clarifies a default. But it never states when to call this instead of scan_site, find_opportunities, or seo_link_audit, nor any prerequisite such as a saved project existing for the keyword fallback to work.

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?

No annotations are supplied, so the description carries the full behavioral burden and falls short. It does not say whether tracker entries are mutated by the flagging, whether results are persisted or just reported, how many network requests a batch implies, or whether it can be slow or rate-limited for a site with many live entries.

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, front-loaded with the action and scoped by the 'live' qualifier and the outcome clause. No filler, no redundancy, and the important constraint appears first.

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 batch re-verification tool with no annotations and no output schema, the description should say what comes back (counts, a list of broken/nofollow links, a summary) and whether tracker state changes. Those gaps leave an agent unable to predict the result or side effects, though the core action is clear.

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% for the single 'site' parameter, so the description must compensate. It only repeats 'for a site' without clarifying whether that is a domain, a project name, a URL, or an internal site identifier — a real ambiguity for the only input.

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+outcome: re-verify every 'live' tracker entry for a site, then flag links that disappeared or became nofollow. The scope ('every live entry', 'for a site') distinguishes it in spirit from the single-link sibling verify_backlink, but it never names that sibling or any other, so differentiation is inferred 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?

Usage is implied by the word 'Re-verify' and the 'live' qualifier: this is a maintenance pass over already-tracked links, not a first-time check. There is no explicit when-to-use, no when-not-to-use, and no mention of alternatives such as verify_backlink for a single URL or scan_site for discovery.

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?

With no annotations, the description carries the full burden. It does disclose one genuinely non-obvious mutation semantic: "Only the fields you pass are changed" (partial merge update), which is critical given that most fields default to empty strings. It does not state what happens on conflicting values, whether permission or auth constraints exist, or what the tool returns.

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 upsert purpose front-loaded and no filler. The trailing country-format sentence reads as a dangling fragment appended to the paragraph rather than integrated, which slightly hurts structure.

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 an 8-parameter mutation tool with no annotations and no output schema, the definition covers the core upsert behavior and country format but leaves the primary key (site: domain? full URL?) and several fields unexplained. An agent could invoke it, but would be guessing on site formatting and array handling for keywords/competitors.

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% across 8 parameters, so the description must compensate. It only partially does: the country parameter gets a format explanation with examples ("India", "IN", "UK"), and the fields niche/location/country/keywords/competitors are enumerated as stored attributes. Format and expectations for site, notes, and business_name (5 of 8 uncovered) remain 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?

States a specific verb+resource ("Save (or update) a site") and adds scope ("your own or a client's"), so the agent knows it's an upsert on a project/site record. Sibling tools like list_projects and scan_site are not named, so differentiation is inferable 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?

"Save (or update)" implies the create-or-modify case and the phrase "so every other tool knows its niche..." hints that this should be called before downstream tools. However, there is no explicit when-not guidance, no prerequisites, and no reference to an alternative tool for reading or deleting projects.

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?

With no annotations supplied, the description carries the full disclosure burden. It is clear that this reads a local filesystem project and what categories of information it derives, which is useful context, but it never states that the operation is read-only, whether it writes anything to disk, or what happens on very large repos beyond the max_files default.

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 verb and then the detection list, with the usage cue trailing. The enumeration is long but each item is a distinct signal an agent would care about, so 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?

There is no output schema, and the detection list partially compensates by telling the agent what the result will contain. However, for a tool that takes a filesystem path, the missing guidance on path format and on the max_files cap leaves real gaps an agent could hit at call time.

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 explain both parameters. "Local website project" loosely implies that path is a project directory, but no format, relative-vs-absolute guidance, or examples are given, and max_files is never mentioned at all, leaving a 3000-file cutoff 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?

States a specific verb ("Scan") and resource ("a local website project") and enumerates the artifacts it extracts: framework, routes/pages, meta tags, sitemap/robots, structured data, contact details, external links. It also distinguishes itself from the live-site sibling by noting it is for projects that aren't live yet.

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 when the site isn't live yet or to find what to fix in code" gives a clear selection condition that implicitly separates it from scan_site, which handles live sites. It stops short of naming scan_site explicitly or stating when not to use it, so it is strong context rather than a full routing rule.

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?

With no annotations, the description does real work: it discloses robots.txt compliance, sitemap.xml discovery, and that results are cached for other tools. It omits important operational traits such as runtime/timeout expectations, whether the crawl is breadth- or depth-limited, handling of JS-rendered sites, and whether caching means repeat calls are free.

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 dense, front-loaded sentence where the crawl action, the governing behaviours, and the returned artefacts each appear in that order. No filler; slightly long clauses are justified by the information they carry.

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 and no annotations, yet the description still enumerates return contents well enough to plan around (profile fields, per-page SEO, broken links, link stats). The remaining gap is crawl-scope behaviour tied to max_pages and what a cache hit looks like for the caller.

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% and the description never mentions either parameter. 'url' is obvious from the name, but 'max_pages' (default 30) — the key control over crawl cost and completeness — is left entirely unexplained, so the description fails to compensate for the empty 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 concrete verb+resource ('Crawl a live website') and enumerates the outputs it produces (business profile, per-page SEO data, broken links, link stats). It doesn't explicitly contrast with near-neighbours like scan_codebase or seo_link_audit, so the sibling differentiation is only inferable from 'live website'.

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: 'Results are cached for the other tools' hints this is the first-step scan whose output downstream tools consume, but there is no explicit when-to-use/when-not guidance and no named alternative (e.g. scan_codebase for source, recheck_live_links for a re-check).

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?

With no annotations, the description carries the full burden; it does disclose that the tool operates on cached rather than live data and lists exactly which issue classes are reported. However, it never states that it is read-only/non-mutating, whether it refreshes or invalidates the cache, or what form the findings take, so behavioral coverage is partial.

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: the action and its audit scope first, the prerequisite last. The colon-delimited list delivers dense information with no filler.

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, no-output-schema tool this is close, but the description leaves open what an agent gets back and how findings are structured or scored, and it doesn't address the failure case of an unscanned domain. No return-format detail is strictly required, but some indication would round it out.

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% for the single `domain` parameter, so the description must compensate, and it partially does by implying the domain identifies which cached scan_site result to audit. It never states that the domain must match a previously scanned site or how mismatches are handled.

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?

"Audit the cached scan_site result" gives a specific verb (audit) and resource (cached scan output), and the enumerated problem categories (titles, canonicals, noindex, thin pages, schema/OG, broken links, orphans) define the scope precisely. It is clearly distinct from the sibling scan_site, which produces the data this consumes.

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?

"Run scan_site first" states an explicit prerequisite and, by naming the sibling, routes the agent to the right first step. It lacks any when-not-to-use or alternative path (e.g., what to do if no cached scan exists), which keeps it below a 5.

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?

With no annotations, the description carries the full burden of behavioral disclosure and does little with it. It is clearly a write operation, but it never says whether duplicates are rejected or merged, whether the URL is validated, what the tool returns, or whether entries can be undone; only the enum lists add real content.

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 with the purpose front-loaded and the constrained values listed compactly as pipe-separated sets. No filler, no repetition of the tool name, nothing that could be cut without losing information.

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 six-parameter write tool with no annotations and no output schema, the definition covers the core action and the two enum-constrained fields but is silent on return behavior, deduplication, validation, and the meaning of the contact/notes fields. It is callable but an agent would be guessing about side effects.

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% and the schema declares kind and status as bare strings with no enums, so the description's enumerated allowed values for those two parameters add substantial meaning the schema lacks. However, url, site, notes, and contact get no guidance at all — no domain-vs-sitename convention, URL format, or notes/contact intent — so half the surface remains undocumented in both places.

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: 'Add a backlink opportunity to the tracker', which is immediately distinguishable from tracker_update and tracker_list by the word 'Add'. It does not explicitly contrast itself with siblings like qualify_prospect or tracker_update, but the create-vs-update-vs-list split is inferable from the names.

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: nothing says to call this instead of tracker_update, or whether qualify_prospect should precede adding an entry. No prerequisites, no mention of duplicate handling, and no statement about when-status should be set at creation rather than updated later.

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?

With no annotations, the description carries the behavioral burden. It implies a read-only listing operation and mentions that a summary is returned, but it does not disclose pagination, ordering, return shape, permissions, or whether the summary includes counts versus detailed records.

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 a single front-loaded sentence with no wasted wording. It efficiently covers the core action, filters, and summary return in one pass.

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 two-parameter list tool with no output schema, the description covers the basic action and filters. However, it omits details about the summary contents and filter value semantics that an agent would need to invoke the tool confidently.

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 compensate for undocumented parameters. It names both 'site' and 'status' and explains their filtering roles, but it does not state accepted values, matching behavior, or defaults, leaving meaningful ambiguity.

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: list tracked opportunities, with optional site/status filtering and a summary. It distinguishes itself from related siblings like tracker_add and tracker_update by being a read/list operation, though it does not explicitly name an alternative.

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 'List tracked opportunities' and the optional filter fields, but the description does not say when to use this instead of siblings such as find_opportunities or tracker_update. It gives enough context to infer basic use but no explicit exclusions or 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?

With no annotations supplied, the description carries the full burden and does not say whether this is a partial patch or a full overwrite. This matters concretely because notes/status/contact default to empty strings, so an agent cannot tell from the description whether omitting a field clears it. Error behavior for an unknown id and the response shape are also unstated.

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 resource and identifier up front and zero filler. It is efficient, though the brevity comes at the cost of the semantics noted elsewhere rather than being genuinely complete.

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 small 4-parameter mutation tool, an agent can probably form a call, but with no annotations, no output schema, and zero schema coverage, the definition should explain overwrite semantics and status value expectations. The most consequential behavioral question for this tool is left unanswered.

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% and the schema only provides bare titles, so the description must compensate — but it merely restates the parameter names already visible in the schema. It adds no valid status values, no contact format, no notes length/format, and no id provenance (where to obtain it, e.g. from tracker_list).

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 ('Update a tracker entry') plus the fields affected ('status/notes/contact by id'). It is implicitly distinguishable from tracker_add and tracker_list, though it never names those siblings to confirm 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?

No guidance on when to use this instead of tracker_add or tracker_list, no preconditions, and no note that the entry must already exist. The only cue is the verb 'update', leaving the agent to infer everything.

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?

With no annotations present, the description carries the full disclosure burden. It does well on the side-effect front by stating 'Updates any matching tracker entry', which warns of a mutation inside an otherwise read-looking tool, and it previews the returned data. It says nothing about whether a live network fetch occurs, authentication requirements, rate limits, or what happens when the source page is unreachable or the schema target is malformed.

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 compact sentence covers the purpose and inspected facets, with the side effect appended as a second short clause. It is front-loaded and free of filler, though the enumeration of facets slightly buries the tracker-update warning that matters most for safe invocation.

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 two-parameter check tool with no output schema, the description adequately covers what it evaluates and even names the data returned. The notable omission is the mutation semantics of the tracker update and any failure-mode behavior, which matter because no annotations are supplied to signal safety.

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 both required parameters are undocumented in the schema. The description partially compensates by framing the operation as 'a page' linking to 'your domain', which implies source_url is the page to fetch and target_domain is the domain to look for. It does not specify expected formats, such as whether scheme/path is permitted in source_url or whether target_domain should include a protocol or subdomain.

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 the exact facets it inspects (anchor text, rel attributes, target URL, indexability), so an agent knows what comes back. It does not differentiate itself from the closely related sibling recheck_live_links, which is the main remaining gap.

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: it checks a specific page-to-domain link relationship, which contrasts implicitly with site-wide tools like scan_site or seo_link_audit. There is no explicit 'use this when...' statement and no guidance on when recheck_live_links would be the better choice.

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