mttr

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

Annotations already declare readOnlyHint and openWorldHint, yet the description still adds real sourcing behavior: robots.txt is asked first and a disallowed page is not fetched, and results come from mttr's own crawler rather than the caller's reader. It stops short of stating latency, caching, or failure behavior for 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?

It is a single long run-on sentence that strings the whole diagnostic checklist together, which is useful content but hard to scan. The best material, the robots.txt gating, is front-loaded, but the middle collapses into an unpunctuated 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?

With no output schema, the description carries the burden of describing return contents, and it does enumerate the payload: Markdown main content, word and token estimates (~4 chars/token), and per-signal state plus rule reference. Only error and empty-content handling are left 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 100%, so both url and site are already documented in the schema, including the 'latest read' semantics for site. The description reinforces 'one live page' and 'from its latest read' but adds no format or syntax detail beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource: 'Reads one live page the way an agent does', and pins it to the named free 'What an agent reads' tool. It does not name sibling tools such as mttr_page or mttr_explore to differentiate the scope, so an agent must infer the contrast.

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 through the url-vs-site split and the phrase 'the free ... tool'; there is no explicit statement of when to reach for this rather than mttr_page, mttr_structure or mttr_explore. The 'assistant's own reader may differ' caveat hints at scope but does not route the agent.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds a genuinely non-obvious side effect: turning approve off sends an email to the person, which is exactly the kind of context annotations cannot carry. It does not describe the response shape or whether re-setting the same mode is a no-op.

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 sentences, no filler, with the mode definitions and the email side effect front-loaded before the read-tool pointer. The opening sentence is long and slightly tangled with nested clauses, but each clause carries distinct 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?

With only two required, fully documented parameters and no output schema needed, the definition covers purpose, mode semantics, a side effect, and the read counterpart. The only real gap is confirming behavior on already-claimed sites or failure cases, which is minor at this complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the enum values are already documented; the description nonetheless re-frames them as workflows tied to mttr_propose, which clarifies when 'approve' actually bites. It also constrains the site parameter to 'one of the person's claimed sites', a precondition not present in the schema's 'domain such as example.com' note.

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 (set how changes are approved) and immediately defines the two modes with concrete workflow meaning: automatic deploys each change as you go, approve requires mttr_propose plus approval. An agent can distinguish this from mttr_propose, mttr_proposal, and mttr_proposals without opening any 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?

Explains what each mode means in practice and routes the agent to mttr_proposals({ site }) to read the current setting before/after changing it. It does not explicitly say when NOT to call this tool (e.g. that this is per-site and the site must already be claimed), but the conditioning on 'one of the person's claimed sites' implicitly scopes 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?

Annotations already declare readOnlyHint=true and openWorldHint=false. The description adds meaningful context beyond that: it discloses that only sites mttr has already read are included, that unread-site links are unknown, that results are ordered by page count descending, and that a count of sites is returned. It does not fully describe the return shape, but the key limitations and ordering behavior are present.

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 two sentences with no filler. The first sentence is somewhat densely packed and does not lead with a verb, but it front-loads the scope and ordering, and the second sentence adds a necessary caveat.

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?

Given a fully described three-parameter schema and read-only/open-world annotations, the description is largely complete for correct invocation. It covers data availability and ordering, and pagination is handled by schema-described limit/offset. It could do slightly more to distinguish this tool from related link tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents site, limit, and offset. The description adds no additional parameter-level meaning beyond what the schema provides, which is acceptable given the baseline for fully covered schemas.

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 clearly identifies the resource — sites that link to a given site — and specifies scope (only sites mttr has read) plus ordering (most pages first). It is specific enough to distinguish this from internal-link tools, though it does not explicitly name a sibling 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?

The description implies this is for inspecting backlinks but gives no explicit when-to-use guidance, no alternatives, and no exclusions beyond the data-availability caveat about unread sites. An agent must infer usage from the resource name and description alone.

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 and openWorldHint=false, and the description adds useful behavior beyond that: the output is Markdown and is written to be acted on, with a stated structure covering priority, method, rationale, and pages. It does not discuss pagination or limits, but adds meaningful return-content context for a read-only 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 definition is tightly front-loaded: it names the resource and format first, then lists the actionable contents. "Start here" is short and useful, and every part of the description earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter read-only tool, the description adequately covers purpose, output format, and entry-point usage. It does not need to explain safety semantics already covered by annotations, though it could be stronger with a note on how it relates to adjacent planning or queue tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is only one parameter, and its schema description fully documents it as a domain such as example.com. The description says "for a site" but does not add format or validation detail beyond the schema, so the baseline score for high schema coverage is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the resource: a Markdown fix list for a site, with specific contents including what to fix, order, method, rationale, and affected pages. It is more specific than the title alone, but it does not explicitly differentiate itself from siblings such as mttr_plan, mttr_todo, or mttr_queue.

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?

"Start here" gives a clear entry-point recommendation and implies this should be used before other tools. However, it does not name alternatives or state when not to use this tool, so it falls short of full explicit 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 readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds that output is a run-to-run diff and that it must follow a rescan, which is useful context, but the closing sentence about "visits" is opaque and doesn't clarify behavior or return shape.

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 first sentence is front-loaded and dense with useful specifics. The second sentence, however, drifts into an unclear remark about "visits," people, assistant-sent people, and crawler fetches that is hard to parse and doesn't clearly serve the tool's 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?

With no output schema, the description usefully enumerates what comes back: score delta, rules now passing, rules newly failing, and pages added/removed. That is nearly complete for a read-only diff tool, with only the trailing "visits" aside muddying the picture.

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?

There is one required parameter and schema coverage is 100%, with the schema already describing "site" as a domain. The description adds nothing about the site parameter beyond the schema, which meets the baseline for a fully documented single parameter.

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: a diff of the latest run against the prior run, spelled out as score, passing/failing rules, and added/removed pages. It is clear enough to distinguish it from generic site tools, though it never names mttr_compare, the sibling an agent might 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?

"Call it after a rescan is done" gives a concrete precondition tied to the mttr_rescan sibling workflow. There are no explicit exclusions or a pointer to mttr_compare, so it stops short of full when-not 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 establish readOnlyHint=true and openWorldHint=false. The description adds valuable behavioral context beyond that: results come only from prior lookups and the call consumes no credits, while also surfacing remaining credits.

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 compact sentence with no wasted words. The key scoping information and cost note are front-loaded and easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter read-only tool with no output schema, the description provides enough context to call it correctly and understand the cost/read-only behavior. It could mention response shape or pagination, but those are minor gaps for this simple tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is only one parameter ('site'), and the schema already documents it fully at 100% coverage. The description does not add format details beyond the schema, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that this returns citation data per site and question, specifically from lookups that were already made. This implicitly distinguishes it from a tool like mttr_cite that would perform new lookups, but no sibling is named 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?

The phrase 'from lookups already made' tells the agent this is a historical/read-only listing rather than a fresh lookup, and 'Costs nothing' clarifies the cost profile. It does not explicitly name mttr_cite or another alternative for running new lookups, so usage guidance is clear but not exhaustive.

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 only declare readOnly=false, destructive=false and openWorld=true; the description adds the economically important behavior: it is paid in mttr credits, and the zero-connection case returns 503 at no cost. It also enumerates the return content (cited/whether, where, name-without-citation, who is cited instead), which annotations do not cover.

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 cost, then the failure mode, in three dense sentences with no filler. Every clause conveys a distinct fact an agent needs.

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 description compensates by describing exactly what comes back per assistant. Cost, prerequisite sibling check, and the no-connection failure mode are all covered, leaving nothing material for an agent to guess.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so both parameters are already documented, including the instruction to leave the site's name out of the question. The description only adds the framing that the question is asked with web search enabled, which is useful context but not new meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: asks ChatGPT, Gemini and Perplexity one question with web search on, then reports citation status per assistant. It also distinguishes itself from the sibling mttr_citations, which is described as the pricing/balance tool rather than the query tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit preconditions and alternatives: check mttr_citations for price and balance first, and note that only connected assistants are asked (503 and no cost otherwise). It doesn't clarify when to prefer this over near-neighbors like mttr_claim_check or mttr_tells, so it stops short of full when/when-not 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 say this is not read-only and not destructive; the description adds the claim workflow, proof requirement, required follow-up, and what account access a claimed site unlocks. That is meaningful behavioral context beyond the structured hints.

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?

Four short sentences, front-loaded with the action, then the prerequisite and next step, then the resulting account effects. Each sentence contributes useful decision or workflow context.

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 mutation tool with no output schema, the description explains the initiation flow, the proof step, the required follow-up call, and the account consequences. Annotations cover safety, and the remaining call-relevant context is 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 100%, and the single site parameter is already documented in the schema as a domain like example.com. The description mentions the site and ownership proof but adds no format or validation detail beyond the schema, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Starts claiming a site") and distinguishes the step from the sibling check tool by naming "mttr_claim_check" as the follow-up. The agent can tell this starts a claim rather than checking one.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit workflow guidance: put up the TXT record or file, then call mttr_claim_check. It also clarifies that a public report can be read without a claim, which helps the agent decide when this tool is not needed.

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 declare readOnlyHint=false and openWorldHint=true; the description is consistent and adds real value beyond them by disclosing that this call mutates account state (adds the site) and that external DNS visibility can lag by minutes. It does not describe what a not-yet-visible or failed check returns, which is the main remaining gap.

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 action and its effect, plus one genuinely useful operational caveat. No filler, though the 'record or file' phrasing costs a little precision.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and a mutating tool, an agent still cannot tell what the response distinguishes (verified vs pending vs failed) or what to do on failure. The sequencing and DNS-timing context helps, but the result semantics are left entirely 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?

Only one parameter and schema coverage is 100%, with the schema itself specifying the domain format (example.com). The description refers to 'the site' but adds no format or constraint detail beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (checks) and resource (the record/file from mttr_claim) and distinguishes itself from the sibling mttr_claim by naming it as the prerequisite step. The additional outcome clause (adds the site to the person's account) makes the effect concrete. It falls short of 5 only because 'the record or file' is vague about what artifact is actually being validated.

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?

Implicitly establishes the workflow: call this after mttr_claim has produced a record/file, and the DNS propagation note tells the agent to expect delay and possibly retry. There are no explicit exclusions or failure-path guidance, so it stops short of a fully prescriptive 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description adds the meaningful prerequisite that both sites must be already read/crawled. It also outlines the return shape (scores, stages, rule pass-shares, page pairs with words on each, quoted titles), which is valuable given there is no output schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the primary rules comparison, then presents the content view as the alternative, with zero redundant repetition. The phrasing is idiosyncratic ('by the share of its pages passing', 'come under quoted') and dense, slightly taxing readability.

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?

Given a read-only, 3-parameter tool with full schema coverage and no output schema, the description covers the prerequisite and sketches return contents sufficiently. Only sibling-selection guidance and the meaning of 'quoted' are left thinly explained.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and documents site, with, and the view enum, so the baseline is 3. The description does add meaning for the 'content' view's outputs, but it doesn't clarify the domain format or the 'rules' view's per-rule detail beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific comparison of two sites side by side on scores, stages, and rules ahead/behind, plus a content-by-meaning mode. The resource and action are clear, though it never names sibling comparison tools (mttr_competitors, mttr_similar) to differentiate itself.

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?

Explains the 'content' view as an alternative to the default 'rules' view and notes both sites must be 'already read'. However, it gives no guidance on when to pick this over mttr_competitors/mttr_similar or when-not to use it, leaving comparison-tool selection 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?

The readOnlyHint and openWorldHint annotations already confirm the safety and scope profile, while the description adds useful behavioral detail: it derives location from address/phone numbers on the site's pages, uses semantic similarity, proximity, and similarity elsewhere, and reports score, pages, and inbound link counts. It does not contradict the 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 definition is front-loaded with the core concept and packs the relevant output categories into one sentence with no wasted sentences. It is dense and somewhat awkward in phrasing, but appropriately sized for the information conveyed.

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 carries the burden of explaining return values; it does so by naming the competitor categories and the per-result details (score, pages, and inbound link counts). Some ambiguity remains around scoring and ordering, but the definition is sufficient for an agent to understand what to expect.

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 input schema has 100% description coverage for the single site parameter, so the schema already explains that a domain such as example.com is expected. The description adds no further parameter-level semantics beyond implicitly referring to 'a site.'

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 clearly identifies the resource as a site's competitors and enumerates the categories returned: nearby semantic competitors, all nearby sites, and similar sites elsewhere. It is more specific than the title alone, but it does not explicitly distinguish itself from sibling tools such as mttr_similar or mttr_near.

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 description explains what the tool returns but gives no explicit guidance on when to use it versus alternatives. With sibling tools like mttr_similar and mttr_near present, the lack of routing guidance is a clear gap.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false), so the description's job is to add context — and it does, by disclosing that the result is a set of files intended to be saved under .mttr/brain/ and by enumerating what those files contain. It omits file format, approximate size, and what happens for an unclaimed site, which keeps it from a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single dense sentence with the resource front-loaded, a colon introducing the contents, and the imperative guidance at the end — nothing is redundant. The mid-sentence content list is long but each item maps to a distinct part of the brain, so it earns its space.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description must carry the return-value burden, and it does by enumerating the contents and the destination path. Still unstated: whether the tool writes the files or merely returns them for the caller to save, and the file format — the one material ambiguity for an agent acting on the result.

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?

One parameter at 100% schema coverage means the schema already documents the domain format, so the baseline is high. The description adds real meaning the schema lacks: the site must be 'claimed', which is a prerequisite the agent would otherwise not know.

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 resource (a claimed site's content brain, delivered as files) and enumerates its contents — business facts, page voice, structured-data facts, opportunities, and briefs — so the agent knows this is a bundled knowledge artifact, not a single lookup. It does not explicitly distinguish itself from siblings like mttr_brief or mttr_pages, even though 'every brief so far' overlaps with mttr_brief, leaving that boundary to inference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Read it before writing any page' gives a clear, actionable trigger condition, which is stronger than most siblings. It stops short of naming alternatives or exclusions (e.g., when to use mttr_brief instead), so it is clear context without 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 readOnlyHint=false and destructiveHint=false, so the description's job is to add nuance — and it does, disclosing that the brief does not go live immediately but only when a later read finds that page, and that the record captures the site state at that moment. That deferred-confirmation model is meaningful behavioral context the agent could not infer from the 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?

Two sentences with the identifying inputs front-loaded and the follow-up action at the end, no filler. The slightly conversational opening ('Says where... went') costs a little immediacy but nothing is redundant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With three required, fully documented params and no output schema, the description supplies the missing pieces an agent needs: where the id comes from, that success is confirmed asynchronously, and which tool to call next. It omits failure/idempotency behavior, which keeps it from a 5.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and every parameter already carries a description including the mttr_content_next provenance, so the description largely restates the schema. Baseline 3 applies; it adds no format or edge-case detail (e.g. trailing slashes, duplicate paths) beyond what is structured.

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 concrete verb+resource combination: it records where a brief's page lives on the site, keyed by brief id and path, and ties that to marking the brief live. The phrasing 'Says where a content brief's page went' is a bit indirect for a mutation, but the referents (brief from mttr_content_next, page path) make the operation unambiguous and distinguishable from 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 explicitly names mttr_content_next as the source of the brief id and tells the agent to follow up with mttr_rescan to trigger a read. That is clear routing context, though it never states when to use mttr_content_drop or mttr_content_posts instead, nor any exclusion conditions.

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 flag destructiveHint=true, so the bar is lower, yet the description adds real value beyond them: it discloses the three-open-briefs capacity being freed and, critically, that a dropped brief is 'never handed out again' — an irreversibility guarantee the annotations don't encode. It stops short of saying whether the brief's content/notes are recoverable.

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 waste, with the resource/scope front-loaded and the capacity/irreversibility consequences in the second 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?

For a two-parameter, no-output-schema tool this covers the essentials: what it targets, the capacity effect, and irreversibility. The only missing piece an agent might want is confirmation of what happens to the dropped brief's stored content or a return indication of success.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and both parameters are documented, including the useful cross-reference that the id comes from mttr_content_next. The description restates 'by its id' and the site scoping without adding format or constraint detail beyond the schema, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Drops ... content briefs') plus scope ('one of your open ... for a site, by its id'), which separates it from mttr_content_next (fetch a brief) and mttr_content_done (finish one).

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 phrase 'one of your open content briefs' implies a prerequisite (a brief must currently be open), but the description never states when to drop versus complete via mttr_content_done, nor any conditions/exclusions. Usage is inferred rather than guided.

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, so the description isn't needed for the safety profile. It does add real context beyond that: it explicitly says mttr does not write the page (clarifying the division of labor), discloses the three-open-briefs cap, and points to mttr_rescan as the next step. Missing is anything about latency, permissions for 'claimed' sites, or failure behavior.

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 core purpose is front-loaded, followed by two operational constraints. The enumeration of brief contents is slightly long but each item is functional information an agent would otherwise lack. No filler sentences.

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 single-parameter, read-only tool with no output schema, the description is largely complete: it details what the returned brief contains and what to do afterward. The remaining gap is disambiguation from the similarly named mttr_brief sibling in a 60-tool namespace.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% for the single 'site' parameter, so the schema already carries the domain-format guidance. The description only adds the qualifier 'claimed' site, implying the domain must already be registered with mttr—marginal value over the schema. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states precisely what the tool returns: the brief for the page most worth writing next on a claimed site, and enumerates the brief's contents (question, why, page kind and path, facts, voice, rules). This is more specific than the title alone. It does not, however, differentiate itself from the sibling mttr_brief, which an agent would reasonably 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?

It gives a state constraint ('at most three briefs are open at once') and a follow-up route ('when the page is live, call mttr_rescan'), but never says when to choose this over mttr_brief or mttr_content_brain. Usage is implied by the workflow rather than explicitly scoped.

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 description adds meaningful behavioral context beyond the readOnlyHint annotation by stating 'mttr writes no post and posts nothing; you or your person write them.' It also explains the brief contents, including character counts and how X counts links. It does not cover auth or rate-limit behavior, but it is strong for a read-only 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 compact and front-loads the core resource before listing brief contents. The first sentence is dense and run-on, but every clause contributes information about the returned briefs or the no-posting behavior.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the burden of explaining what comes back, and it does so by listing the brief fields for X and LinkedIn. It also clarifies that no post is written, which is important for invocation expectations. A minor gap is that it does not describe the response shape or whether multiple briefs 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 description coverage is 100%, so the schema already defines both required parameters and the live-page prerequisite for 'brief'. The description does not add syntax or formatting detail beyond what the schema provides, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description identifies the returned resource precisely: briefs for X and LinkedIn posts about a page that went live from a content brief. It is not just a restatement of the title, but it never names a sibling tool such as mttr_content_next or mttr_content_done, so differentiation is left implicit.

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 phrase 'about a page that went live from one of your content briefs', which tells the agent this applies after a brief's page is live. However, there is no explicit when-not guidance and no alternative tool named for related cases.

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 state that this is a read-only operation and not open-world, so safety behavior is covered. The description adds useful context about what status categories are included, but does not describe return format, pagination, or other operational details.

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 definition is a single compact sentence with no wasted material. The phrasing is slightly awkward and indirect, but it front-loads the crawl status context efficiently.

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 read-only listing tool with complete schema coverage and no output schema, the description provides enough context to understand what categories of crawl data are returned. It could be more explicit about default behavior and sibling differentiation, but no critical information 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?

The input schema fully documents the single optional days parameter, including its allowed values and default behavior. The description reinforces the 1/7/30-day window but adds no syntax or format details beyond the 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?

The description identifies the resource and the main statuses returned: current crawls, queued crawls, and recently ended crawls over a time window. It is clear enough to understand the tool, though it does not explicitly differentiate itself from nearby siblings such as mttr_queue or mttr_rescan.

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 description implies the tool is used to inspect crawl status, but gives no explicit guidance on when to choose it over alternatives. It names no exclusions, prerequisites, or sibling 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds nothing beyond that — no ordering guarantee, no default limit, no pagination or retention window, which are the behaviors that actually matter for an event feed.

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 no filler, and the event-type enumeration is compact. It earns its place, though the informal phrasing ('scores that moved, rules that were fixed') costs some precision.

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-required-param read tool this is nearly adequate, but with no output schema the description should say something about the shape of an event (what fields, whether it is ordered newest-first, default count). The event-type list hints at content but leaves the return contract opaque.

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% (site, limit both documented in-schema), so the baseline of 3 applies. The description contributes no additional parameter meaning, such as what 'site' accepts or what the default limit is.

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 conveys that this is a recency-ordered event feed and enumerates event kinds (reads requested/finished/failed, score changes, rule fixes), which gives real content flavor. But it never states a verb ('list', 'returns') or the resource name directly — the reader has to infer 'events' from the title — and it distinguishes nothing from near-siblings like mttr_changes, mttr_progress_link, or mttr_queue.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no exclusion of alternatives, and no mention of how this differs from the many other listing tools in the sibling set. The agent must guess whether this is a dashboard feed, an audit log, or a job history.

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. The description adds useful behavioral context about selection logic: same market or nearest sites, closest in meaning, and passages returned under 'quoted'. It does not cover pagination, default limit behavior, or full response shape, but it adds some value beyond 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 front-loaded with the core purpose and stays reasonably short. The first sentence is dense and slightly repetitive, but the remaining sentences are efficient and the 'quoted' return hint is useful.

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 read-only lookup tool with no output schema, the description explains the selection criteria and notes that each result includes a passage under 'quoted'. It could more fully describe response ordering or default limit behavior, but it provides enough context to call 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 description coverage is 100%, so the input schema already documents site, path, rule, and limit. The description adds little parameter-level meaning beyond reinforcing that the rule is one the page fails, and it does not explain the limit parameter further. Baseline 3 is appropriate when the schema does the heavy lifting.

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: finding pages on other sites that pass a page rule the current page fails. It adds scope details such as same market, nearest sites, and meaning-closeness, making the tool distinguishable from generic similar-page or rule-list tools, though it does not explicitly name sibling alternatives.

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 phrase 'Worked examples for writing the fix' clearly signals the intended use case: gathering concrete passing examples when preparing a page fix. It does not state when not to use the tool or point to alternatives, but the usage 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 and openWorldHint=false, and the description adds meaningful behavior beyond that: unnamed sites have no pages, each decision includes reasoning and a recommended 'next', and words under 'quoted' are data, never instructions. Those are useful operational and safety details not covered by the 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 a single dense paragraph with a lot of useful information, but the syntax is awkward and hard to scan. The core idea is front-loaded, yet phrases like 'One thing mttr knows' and the run-on list of node types reduce clarity. It is information-dense but not tightly structured.

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?

Given a complex multi-hop exploration tool with no output schema, the description covers node and edge types, trail continuity, the unnamed-site limitation, and prompt-injection safety around 'quoted' content. It still leaves the exact return shape and when-to-use context somewhat implicit, but overall it is substantially 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 100%, and the description largely restates what the schema already documents: node formats, 'why' as a nearby site, 'trail' as prior onward steps, and 'by' as edge kind. It adds only marginal interpretation beyond the structured schema, so the baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description makes clear that the tool opens a knowledge-graph node and lists every outgoing edge labeled by meaning, links, or rules. It enumerates concrete node types such as site, market, work, rule, page, passage, alike, and finding. It does not explicitly distinguish itself from siblings like mttr_search or mttr_page, so it lands at clear but not sibling-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?

It explains the iterative trail mechanic ('Pass "onward" back as trail to keep walking') and that 'by' helps Next choose a different edge kind. However, it never states when to use this tool rather than mttr_search, mttr_links, or mttr_page. Usage is implied by the exploration framing rather than explicitly guided.

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, so safety is covered. The description adds real behavioural context about the response shape: each gap carries the rival pages and the nearest page on the site, one gap is surfaced first, and page titles are wrapped in quotes. It says nothing about ordering beyond 'first', result volume, or how the limit interacts with ranking.

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 resource label 'Content gaps:', and every clause carries distinct information about scope or return shape. The clause 'the one most rivals cover first' is placed awkwardly enough to require a second read, and the 'quoted' formatting note reads as an aside.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the burden of describing returns, and it does partially: gap subject, rival pages, nearest page here, and title quoting. It omits how gaps are ordered or scored, what happens when the site is unknown or empty, and whether the limit defaults. Adequate but with clear gaps for a tool whose output is entirely undescribed structurally.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so both the domain format and 'how many to return' are already documented in the schema. The description contributes no extra parameter meaning, though the 'one most rivals cover first' clause hints that results are ranked rather than arbitrary. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description defines a specific resource precisely: subjects rivals write about that nothing on the site covers semantically, plus the one most rivals cover first. This is far more concrete than the title 'Find content gaps'. It does not, however, distinguish this from near-neighbours like mttr_competitors, mttr_similar or mttr_topics, so an agent must infer the boundary.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use statement, no prerequisites, and no named alternative. With siblings such as mttr_competitors, mttr_content_next and mttr_topics in the same family, the agent gets no signal about which tool answers which question. Usage is only implicit in the concept definition.

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, so safety is covered. The description adds meaningful behavioral context: it enumerates the possible status values (waiting, running, done, failed) and mentions queue depth ('how many reads are ahead'). It doesn't contradict annotations and adds value beyond them.

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 that wastes no words. The core purpose and the returned information are presented efficiently.

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?

Given the tool's simplicity (one param, read-only, no output schema), the description is largely complete: it states what statuses and queue info are returned. It could be slightly more explicit about the return format (e.g., whether it returns a status string and a count), but it is sufficient for an agent to understand the tool's output.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single parameter 'id' is well-documented in the schema ('The job id that mttr_rescan returned'). The description adds no additional semantics about the parameter, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the tool reports a rescan's status (waiting, running, done, failed) and queue position. The verb 'stands' is informal but clear enough; the title and parameter description reinforce the purpose. It does not explicitly differentiate from siblings like mttr_rescan or mttr_progress_link, but the param description names mttr_rescan.

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 description provides no explicit guidance on when to use this tool vs alternatives. It only describes what output to expect, leaving the agent to infer that it should be called after mttr_rescan to check progress. No conditions or exclusions are stated.

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

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

Annotations already state readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds useful behavioral details: ties share places, counting is based on site reports, anonymous sites use codes, and drafts/crawler-blocked sites are excluded. It could still say more about result consistency or limits, but it is substantially informative.

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 dense run-on with awkward quoted parameter references and repetitive phrasing. It contains relevant information but is hard to scan and not structured for quick agent comprehension.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description does a reasonable job covering return content: stages, pages read, prior score, record-mode outputs, and what records are counted over. It also covers exclusions and anonymization, making it fairly complete for a complex leaderboard tool, though clarity suffers.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining record enum values and how filters can be combined, though the awkward phrasing around 'in', 'record', and place counts reduces precision.

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 identifies a public leaderboard of ranked sites scored by their latest read and describes filter and record modes. It is specific enough to distinguish this as a leaderboard/list tool, but the dense phrasing and lack of explicit sibling differentiation keep it below a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explains how filters and the record parameter change the output, including record alternatives like fastest, improved, stages, answer-first, and biggest. However, it gives no explicit guidance on when to use this tool versus siblings such as mttr_sites, mttr_search, or mttr_compare.

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, so safety is covered. The description adds useful data-source scoping ('from its latest run') and the default filter, but says nothing about ordering, pagination behavior beyond the schema, or what happens when no run 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 dense sentences with no filler, and the core scope plus default behavior are front-loaded. The phrasing is slightly compressed and the final clause about 'quoted' reads as an appendix, but 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?

For a read-only list tool with full schema coverage and no output schema, the description covers scope, default filter, and enum meanings. It still omits the shape of returned records, ordering, and the failure mode when a site has no run, which an agent would need to interpret results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description goes further by translating the opaque enum values, explaining that 'content' means links in page content and 'outbound' means other sites linked to. It also clarifies that quoted link text is surfaced under 'quoted', which the schema cannot convey since there is no output schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('the links of a site from its latest run') and enumerates the variants (broken, all, content, outbound), which lets an agent distinguish this from generic crawl or page listing tools. It does not name or differentiate itself against closely related siblings such as mttr_backlinks or mttr_citations, so it falls short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

'broken ones by default' implies the common starting case, and the enumerated show modes hint at when each is appropriate. However, there is no explicit guidance on when to prefer this over mttr_backlinks, mttr_pages, or mttr_structure, and no prerequisites (e.g., whether a completed run is required) are stated.

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

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

Annotations already indicate this is a non-read-only mutation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds useful behavioral context: naming adds a report link, un-naming reverts to an anonymous code, and only claimed sites are eligible. It does not contradict the 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 two compact sentences that front-load the main action and then explain the show=false reversal. Slightly awkward phrasing and lack of explicit structure keep it from being ideal, but it is efficient.

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 toggle with full schema coverage and annotations, the description covers the key prerequisite and both naming outcomes. It does not describe return values or error behavior, but no output schema exists and the tool is low-complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and the schema already defines both parameters, including show=false behavior and the default. The description reinforces the meaning of show=false and adds the claimed-site constraint, but contributes little additional parameter syntax beyond the 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?

The description states a specific action: naming or un-naming a claimed site on the public leaderboard, including the report link when named. It is clear despite the misleading tool name mttr_list, though it does not explicitly contrast with siblings such as mttr_claim.

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 the important prerequisite that only a claimed site can be named, and explains that show=false reverses the naming. However, it does not explicitly route the agent to mttr_claim for claiming or name alternatives, so usage is implied rather than fully specified.

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 description goes well beyond the readOnly/openWorld annotations: it explains that robots.txt is checked first and closed sites are not read, that the home page, sitemap, and up to 25 location pages are crawled, what the eight checks are, how the score is derived, and that it cannot confirm whether a business is really at an address. This is rich behavioral and return-context disclosure for a read-only audit 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 purpose is front-loaded, but the description is a single dense run-on sentence that packs in every check and caveat. It is hard to scan, and phrases like 'state and city listings followed down to the places and subpages every location has left out' reduce clarity rather than earning their 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?

For a complex multi-location audit tool with no output schema, the description is complete enough: it covers crawl scope, the 25-location limit, all eight checks, how failures and fixes are reported, the score, and the key limitation. An agent can understand what it will get back and what the tool cannot do.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and the single url parameter already documents the expected site format with an example. The description adds only the broad idea that the URL is the brand's site being graded, not extra format, edge-case, or validation semantics beyond the 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?

The description states a specific action: it grades a brand's location pages as a free multi-location grader, with eight checks and a 0-100 score. That is clearer than a generic listing tool, but it does not reconcile the 'List' title/name with the actual grading behavior, nor does it differentiate this tool from siblings like mttr_pages, mttr_site, or mttr_reviews.

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 indicates this is the free multi-location grader, implying it is for auditing location pages, but it gives no explicit when-to-use guidance, no when-not-to-use conditions, and no named alternatives among the many sibling tools. The caveat that it cannot verify physical presence is useful but is not usage 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?

Goes beyond the annotations by disclosing downstream effects: entries appear on the person's progress page and 'mttr reads these to get better,' plus a data-hygiene constraint ('Never send secrets or a site's private data'). It doesn't discuss idempotency or update behavior, but the annotations already cover the safety profile.

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-loads the core purpose and packs the behavioral notes into a short closing sentence. There is mild list-like enumeration that duplicates the schema, but overall it is tight and earns most of its words.

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, fully documented write tool with annotations and no output schema, the description covers purpose, timing, side effects, and a data-safety warning. Missing only sibling routing and any note on how repeated logs are handled.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents all seven parameters. The description restates the field categories (planned/changed/checked/stuck, files, rules) but adds no format or syntax detail beyond what the schema provides. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Tells mttr what you did on a site') plus the timing ('after each step') and the categories of content it records. An agent can tell this is a work-journal tool, though it never names or contrasts a sibling (e.g., mttr_changes or mttr_plan) that might look similar.

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?

'after each step' gives a clear timing cue, but there is no explicit when-not-to-use guidance or routing to alternatives among the many similarly named siblings. Usage is implied rather than stated.

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

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

Annotations already cover read-only and closed-world behavior. The description adds useful behavioral context beyond that: it refers to the 'latest read', notes that orphan pages are omitted when the read stopped at its page limit, and clarifies that meaning-view proximity means similarity, 'never better or cited'.

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 and compact, with the three view modes clearly labeled and separated by semicolons. Some phrasing is dense and cryptic ('words', 'first way in'), but there is little wasted text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the burden of explaining what each view returns, and it does so conceptually for all three modes. It is not fully precise about output structure or terms like 'words', but it gives enough to understand the result of each view.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds substantial meaning for the view enum beyond the schema's short labels. It explains what tree, links, and meaning each represent and what kinds of information appear in each view.

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 resource and scope: every page of a site's latest read, presented in one of three view modes. It does not name or differentiate from sibling tools such as mttr_structure, mttr_links, or mttr_pages, so it falls short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains what tree, links, and meaning produce, but gives no explicit guidance on when to use this tool rather than a sibling, nor when to choose one view over another. It only implies view selection through output descriptions.

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

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

Annotations already establish readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real behavioral context beyond that: the fallback to nearest sites when no market exists, and the ordering of rules by how far behind they are. It omits output shape limits and whether results are paginated or size-capped.

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 core concept and then the return contents, with no filler. It is dense and slightly comma-heavy, but every clause adds 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?

With no output schema, the description must describe return values and does so meaningfully (rank, median score, per-rule share vs market median and best site, ordered by gap). What remains thin is when to choose this rather than sibling market tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% for the single 'site' parameter, and the description adds nothing beyond the schema's domain-format note. Baseline 3 applies since the schema already carries full parameter meaning.

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 resource and scope: a site benchmarked against its market, including rank, median score, and per-rule pass-rate comparisons. It never names or contrasts with adjacent siblings like mttr_markets, mttr_competitors, mttr_leaderboard or mttr_similar, so the agent cannot confidently disambiguate from the description 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?

There is no explicit when-to-use guidance, no prerequisites, and no named alternative. The nearest-sites fallback is a behavioral detail, not a routing instruction, so an agent must infer when this tool beats mttr_markets or mttr_compare.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false), and the description adds useful behavior: ordering ('largest first') and the grouping/naming rule for each market. It stops short of describing the result shape, whether the list can be empty, or how 'last found' relates to a prior analysis run.

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, with the ordering constraint front-loaded. The second sentence ('writing about the same work') largely restates 'close in meaning' and could be folded in, but the text is otherwise tight.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and no parameters, the description carries the full burden, and gaps remain: the structure of a returned market (sites? size? identifier for use with mttr_market?) and the empty/no-analysis state are unaddressed for what is evidently a dependency-ordered list tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes no parameters, so the baseline of 4 applies; there is nothing the description could add on this dimension.

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 explains what a 'market' is (a semantically similar group of sites, named for its centre site) and implies a listing ordered largest-first. But it never states the action plainly ('returns the markets'), and it gives no differentiation from the near-identical sibling mttr_market, which is the most likely confusion point.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no mention of when to prefer mttr_market (singular) for one market's details, and no stated prerequisite. 'The markets last found' hints that markets must have been computed in an earlier step, but never says which tool produces them or what happens if none exist.

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. The description adds real behavioral context beyond that: results are ordered closest-first, and critically, it discloses a prerequisite – both sites must have been embedded, since results are read from a stored vector.

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, purpose front-loaded, no padding. The clause 'Read from one vector a site kept in the catalog' is a slightly awkward construction but still earns its place by conveying the embedding prerequisite.

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 read-only tool with full schema coverage and no output schema, the description covers purpose, ordering, and the embedding precondition. Only the sibling differentiation and limit behavior are missing, which are minor for this complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and both parameters (site as a domain, limit as count) are documented in the schema. The description reinforces 'one site' but adds no format, default, or range detail for limit, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific operation (returning sites closest in meaning to one site, ordered closest first) and even characterizes the result as 'likeliest rivals'. It does not, however, distinguish itself from close siblings like mttr_similar or mttr_competitors, leaving ambiguity about which similarity tool to pick.

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 a hint of use ('its likeliest rivals'), but no explicit when-to-use, when-not-to-use, or named alternative. With siblings mttr_similar and mttr_competitors present, the agent receives no guidance on choosing among them.

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, so the safety profile is covered externally. The description adds useful behavioral context by saying the result includes both failed rules and their fixes plus inbound/outbound links, but it does not clarify pagination, freshness, permissions, or limitations.

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 definition is a single front-loaded sentence that avoids repetition. It is efficient, though the compressed phrasing of 'what it says about itself' and 'rules it fails with the fix for each' makes some of the content less immediately clear.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the burden of explaining return values. It names the major categories (page self-description, failed rules and fixes, inbound/outbound links), which is helpful, but it remains vague about the exact representation and whether full page content, metadata, or limited summaries 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 100%, and both required parameters are already documented in the input schema with examples: 'path' as /guides/gravel and 'site' as example.com. The description adds no parameter-level detail beyond the schema, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description identifies a specific resource, 'one page of a site,' and enumerates its contents: self-description/metadata, failed rules with fixes, inbound links, and outbound links. It is more specific than the title alone, though it uses somewhat literary phrasing such as 'what it says about itself' instead of explicit terms like metadata or page content.

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 guidance on when to use this tool versus alternatives such as mttr_pages, mttr_backlinks, mttr_links, or mttr_rules. The description implies it returns page-level detail, but it does not state when that is preferable to sibling tools or mention any prerequisites.

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, so safety is covered; the description adds the important behavioral detail that results come from the site's latest run (data freshness), which the schema does not say. It also enumerates the returned fields, though it does not discuss pagination behavior beyond what offset/limit imply.

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 packed sentences with the resource and scope front-loaded, then the narrowing option. Nothing is repeated and no filler appears.

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 nine-parameter read-only listing tool with no output schema, the description supplies the key facts an agent needs: source run, returned fields, and the failing filter. It stops short of explaining sort direction defaults or result paging semantics, which 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 description coverage is 100%, so the schema already documents all nine parameters including enums for kind, sort, and dir. The description only echoes the 'failing rule' filter and the field set, adding no syntax or example values beyond the schema; baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (list) and resource (a site's pages) with the scope 'from its latest run' and lists the returned fields (status, depth, words, failing rules). It implicitly contrasts with the singular mttr_page and with aggregate siblings, but never names an alternative, so differentiation is left to inference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The sentence 'Can be narrowed to the pages failing one rule' gives a usable condition for the failing filter, which is implied guidance. But there is no explicit when-to-use vs when-not, no mention of when to prefer mttr_page (single page), mttr_search, or mttr_rules, and no prerequisites such as needing a completed crawl.

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 readOnlyHint and openWorldHint annotations already establish that this is a safe read operation. The description adds useful context about the output being an ordered action plan with agent-facing instructions, but it does not disclose pagination, permissions, or other behavioral details beyond the 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 a single front-loaded sentence that immediately identifies the resource and then enumerates the return contents. It is somewhat dense but contains no extraneous sentences.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the burden of explaining return values, and it does so reasonably well by describing ordered steps, pages, points, and agent instructions. Minor gaps remain around how many steps are returned or how points are calculated, but the core output is covered.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and the single required parameter site is fully documented in the schema with an example domain format. The description only says the plan is 'for a site,' adding no syntax or format details beyond the 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?

The description clearly states that the tool returns a prioritized action plan for a site, including ordered fixes, pages, points, and agent instructions. It is specific about the resource and output shape but does not explicitly distinguish itself from siblings such as mttr_todo or mttr_brief.

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 description explains what the plan contains but gives no guidance on when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or sibling tools like mttr_todo or mttr_content_next.

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

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

Annotations already cover readOnly/openWorld, and the description adds real value beyond them: it says the portfolio is private to the person, breaks down the scoring weights, and warns that the score reflects page well-formedness, not citations or authorship. That last caveat is a useful behavioral nuance an agent could not get from 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?

It is a single tight paragraph and front-loads the resource, which is good, but the wordy circumlocutions ('three tenths', 'a fifth', 'not counted yet') reduce parseability. The content largely earns its place but the delivery is denser and more figurative than necessary.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description must convey return values, and it does describe the structure — every site by real name, per-part contributions and rationale, public-facing view, and highest-leverage levers. That is fairly complete for a zero-param read tool, though exact shape (types, ordering) remains implicit.

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 the baseline is 4. Nothing in the description is needed to clarify inputs, and none is misleading.

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 does identify a specific resource — the person's private portfolio with a composite score across claimed sites — but the ornate phrasing ('half for what was improved while they held each site') buries the plain purpose. It does not distinguish this from siblings like mttr_sites or mttr_site, so the agent gets a fuzzy sense of what it returns rather than a crisp verb+resource statement.

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 indication of when to prefer this over mttr_sites, mttr_site, or mttr_leaderboard, and no preconditions stated. The reader must infer usage context entirely.

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?

Adds substantial behavioral detail beyond the annotations: display names are not checked and null clears them, the home site must be DNS/file-proved, and a site can be named only when its owner allows it. These are meaningful constraints for a non-destructive mutation 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?

Front-loaded with the core action and contains little waste, but the first sentence is dense and its parenthetical clauses make it slower to parse than ideal. The final sentence usefully anchors the return behavior.

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 5-parameter optional-field mutation tool, it covers constraints, permissions, null handling, and return behavior by reference to mttr_portfolio. It does not clarify whether multiple fields may be changed in one call or what happens with no parameters, leaving a minor 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 100%, so the schema already defines all five parameters. The description still adds meaning beyond the schema, especially around null clearing, unchecked names, DNS/file proof for home, and owner permission for naming a site.

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?

Clearly states a specific mutation verb and resource: it changes the person's portfolio and enumerates the aspects that can be changed (publish/hide, name, home site, display mode). It also explicitly distinguishes itself from the read-oriented sibling mttr_portfolio.

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 when to use it by contrasting with mttr_portfolio: use this to change the portfolio, while mttr_portfolio returns it. It does not spell out exclusions or alternatives such as mttr_portfolio_veto, but the intended usage 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?

Adds context the annotations can't: the effect is global across all portfolios at once, and it requires the domain to be proved with the current key by DNS or file before it will act. This also explains why destructiveHint=false is credible — the change is reversible via out=false. It doesn't cover what happens if verification fails or what a partial veto looks like.

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 sentences, front-loaded with the action and scope, then the prerequisite, then the sibling pointer for the near-miss use case. Minor wording friction ('with out false', 'or with') costs it the top score but nothing is padded.

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, no-output-schema tool, an agent gets the action, reversibility, precondition, scope of effect, and a redirect to the right sibling. Missing only error/failure behavior and whether ownership must be re-proved on each call.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so both parameters are already self-documenting and the description largely restates the out flag's true/false meaning. The one genuine addition, the DNS/file proof requirement for 'site', is a precondition rather than argument semantics, so it sits at the baseline.

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 precise verb and scope: it removes the caller's site from every portfolio except the owner's own, and the same call reverses the action with out=false. The bidirectional behavior is clear and distinct from mttr_portfolio / mttr_portfolio_set, though those siblings are never named for contrast.

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?

Identifies the caller it is for ('the owner of a site') and gives a concrete alternative for the adjacent-but-different need: 'To keep a site in portfolios but take its name off, call mttr_list with show false.' That is real routing guidance, but it does not address when to prefer mttr_portfolio_set or how to undo an accidental veto other than out=false.

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?

Beyond readOnlyHint/openWorldHint, it discloses that it reads only what the page publishes and that Merchant Center/Google decide eligibility for any Google feature — a real scope limitation an agent must know. It also previews the per-field verdict format and the buy-ability guess.

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 clause, with usage and limitations trailing in separate sentences. The parenthetical field list is long but each item is load-bearing for understanding what is validated; slight density is the only cost.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the burden of explaining return values and does so (per-field present/missing/invalid with remediation, plus a purchase-ability guess). Combined with the eligibility caveat, an agent has everything needed to call and interpret 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?

Only one parameter, fully documented in the schema (100% coverage), so baseline is 3. The description adds a mild constraint — one product URL per template, a live public page — but gives no format or validation detail beyond what the schema already says.

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 (checks) and a tightly scoped resource (one live product page's Product/ProductGroup/Offer structured data against Google's merchant-listing fields). The enumeration of validated fields makes it unmistakable versus siblings like mttr_schema_create or mttr_page, even without naming them.

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 it on one product URL per template before and after a fix" gives concrete operational context for when to call it. It stops short of explicit exclusions or naming an alternative tool for other page-checking needs, so it is clear but not fully 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?

The description adds substantial behavioral context beyond the annotations: the link is signed with the current key, expires after the requested days with a default of 30 and maximum of 90, and lapses if the key is rotated. It also discloses the privacy constraint that the link should be handed only to the person, which is important handling guidance not captured by the 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 compact and front-loaded with the core purpose, followed immediately by the important expiry and handling constraints. Every clause contributes useful information without repetition.

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 tool with no output schema, the description is nearly complete: it explains what the link exposes, how long it lasts, and who should receive it. It does not explicitly state the return value format or whether repeated calls produce distinct links, leaving a small 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 100% and the single parameter already documents the 1-to-90 range. The description still adds useful meaning by specifying the default of 30 days when none is provided, which is not present in the 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?

The description clearly establishes that this creates a private progress-page link, listing what the page contains and emphasizing that the link is private. The verb is implied rather than stated outright, and no sibling tool is named, but the resource is specific enough for an agent to distinguish it from general reporting tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'Hand it only to the person' gives a clear recipient restriction, which implies the intended use case: sharing a person's own progress with that person. However, it does not explicitly state when to use this tool versus alternatives, nor does it mention prerequisites 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description still adds genuine behavioral context — the state machine, the meaning of the 'deploy' flag, the presence of a decline reason, and the recommended polling cadence. It stops short of covering behavior for unknown/expired ids, which is why it isn't a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the outcome states and then the workflow instruction; nothing is padded. The first sentence is slightly convoluted by the embedded quoted flag and the trailing 'reason when declined' clause.

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 tool with no output schema, the description covers the return states, flag semantics, and the surrounding propose→poll→deploy workflow. Only edge behavior (invalid or unknown proposal id) is left 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 100% and the single 'id' parameter is already documented as the value returned by mttr_propose. The description only echoes that linkage, adding no format, range, or validation detail beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific resource and outcome: the status of one proposal, enumerated as pending, approved, declined or expired. 'One proposal' implicitly contrasts with the plural mttr_proposals sibling without naming it, so the distinction is clear but not explicit.

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: poll every few minutes after mttr_propose, and gate deployment on 'approved'. No exclusion against alternatives (e.g. mttr_proposals for bulk listing) is stated, keeping it just short of 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real value beyond that: result ordering, the fact that each row carries status, and the conditional extra payload (approval vs automatic mode) when a site is supplied. It omits pagination/result-size behavior, which keeps it off a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, zero filler, with the resource and ordering front-loaded and the actionable precondition placed last where it lands. Nothing repeats the schema or the 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 one optional param and no output schema, the description covers what an agent needs: what comes back, in what order, when the extra site-mode field appears, and the workflow trigger for calling it. Pagination is a minor omission rather than a blocking gap for a read-only list.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the one parameter's description already states it returns the site's mode. The description adds only the optionality framing ('for one site or all of them'), clarifying the default when site is omitted, but re-states the mode behavior rather than adding syntax or matching rules. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('the person's proposals') plus ordering ('newest first') and return contents ('where it stands'), which is far more than the title alone. It doesn't explicitly distinguish itself from the singular mttr_proposal or the write-side mttr_propose/mttr_claim siblings, so an agent still has to infer the list-vs-detail boundary.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit precondition: 'check it before you start work on a site,' which tells the agent when this call is warranted. It stops short of naming alternatives (e.g. mttr_proposal for a single proposal, mttr_approvals_set for changing the mode it reports), so the routing is clear but not complete.

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 say readOnlyHint=false, destructiveHint=false, openWorldHint=false, but the description adds genuinely new behavior: an email is sent to a human, the Approve/Decline links are single-use and lapse after 72 hours, the diff is never applied by mttr, and there is a per-site rate limit. The only gap is that it does not say what the tool itself returns in the call response (id only, presumably).

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 trigger condition, then the follow-up loop, then the rate-limit caveat, so an agent gets the decision rule in the first clause. The first sentence is long and enumerates email contents the agent cannot control, which is the only 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 6-parameter mutation-ish tool with no output schema, the description covers what the call does, what the human sees, what to do afterward, how long approval lasts, and the throughput limit. Nothing an agent needs in order to call it correctly and act on the result 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 coverage is 100%, so the schema already explains diff, rule, site, pages, title and summary, and the description mostly restates content rather than parameter syntax. It does add two useful nuances the schema lacks: the summary is presented to the approver 'marked as your words', and related changes should be consolidated because of the hourly cap. That is incremental meaning on top of a fully documented schema, so baseline 3.

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 (proposes a change) and the exact condition that triggers it (a site set to approve), plus what the tool actually does with it: mttr keeps it and emails the person. This separates it cleanly from mttr_proposal (status check) and mttr_proposals (list) named right in the text.

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?

Explicit when-to-use (before deploying to an approving site), explicit follow-up loop (call mttr_proposal with the id until approved), and explicit negative branch (declined or expired means do not deploy). It even gives batching guidance given the 20/hour cap by telling the agent to put related changes in one proposal.

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, so safety is covered. The description usefully adds the data-source dependency and the returned measures (clicks, impressions, average place), but omits anything about empty-result behavior for unconnected sites or how large result sets behave.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, front-loaded with the core resource and metrics before the prerequisite and the formatting note. No filler, though the final sentence about quoted queries is telegraphic enough to be slightly ambiguous.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the burden of describing returns and does name the three metrics; pagination is handled in the schema via limit/offset. The only meaningful gap is that it never explains what an empty answer looks like when the site is not connected to Search Console.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so all five parameters including the 'show' enum are already documented. The description restates the same modes ('by query, by page, or only those close to the top') without adding syntax or defaulting information beyond the schema. It does add one output-format note: queries appear under quotes.

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 resource and source: the Google searches a site's pages were shown for, from Search Console, with the metrics returned. It also flags the three shapes (by query, by page, near-top). It does not name or contrast with any sibling (mttr_near, mttr_traffic, mttr_search), so an agent must infer the boundary.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The prerequisite is explicit and valuable: 'Only sites whose owner added mttr in Search Console have any' tells the agent when this tool will return nothing. However, there is no guidance on when to pick this over mttr_near or mttr_traffic, which overlap on the same subject matter.

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 readOnlyHint and openWorldHint annotations already establish safety and scope. The description adds useful behavioral detail beyond them by specifying oldest-first ordering and the returned task fields (id, site, words), which helps the agent know what to expect from the call.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two tight sentences with no wasted text. The return contents and ordering are front-loaded, and the usage guidance follows immediately.

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?

Given the tool has no parameters, no output schema, and only read-only annotations, the description is complete enough: it explains what the tool returns, how results are ordered, and when to call it. An agent has everything needed to invoke and interpret 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?

The tool takes zero parameters, so there are no parameter semantics to clarify. The schema is trivially complete, and the baseline for zero-parameter tools applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a clear purpose: listing work queued for the agent, sorted oldest first, with each task's id, site, and working words. It is distinguishable from a generic list tool, but does not explicitly contrast itself with siblings like mttr_queue_done, so it falls short of full 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 provides explicit usage triggers: check at startup and whenever an answer indicates tasks are waiting. This is clear contextual guidance, though it does not name alternatives or state when not to use the tool.

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=false and destructiveHint=false, so the mutation and safety profile are covered. The description adds genuinely non-obvious behavioral meaning beyond that: recording completion does not itself mean the fix is real — 'counts only once a later read finds it passing' — which steers the agent toward mttr_rescan before reporting success.

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 action and id source before the caveat. The second sentence ('counts only once a later read finds it passing') is slightly oblique and takes a beat to parse, but every sentence carries necessary 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 one-parameter, non-destructive state-change tool with full schema coverage and annotations, the description covers the essentials: where the id comes from and how completion is validated. It omits idempotency (calling twice on the same id) and error behavior for unknown or already-completed ids.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single parameter is already documented as 'The task id from mttr_queue.' The description repeats the same provenance ('by its id from mttr_queue') without adding format, range, or error semantics, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and state change ('says a queued task is done') against a specific resource ('queued task'), scoped by 'its id from mttr_queue'. That implicitly separates it from mttr_queue (the lister) and mttr_rescan (the verifier), both of which are named or referenced.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear context for use (after a queue task is fixed) and names the alternative/follow-up tool explicitly: 'ask for a fresh read with mttr_rescan'. It stops short of stating when not to call it or what happens if the id is stale/already done, so it is clear context without full exclusions.

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 only declare readOnlyHint=false, openWorldHint=true and destructiveHint=false, so the description earns credit for disclosing two things they don't: an asynchronous job-based return ('Returns a job to watch with mttr_job') and a rate limit ('at most once every ten minutes'). It doesn't say what happens if the limit is hit (error vs. queue) or whether a rescan replaces cached data.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences: purpose first, then the return contract, then the constraint. No hedging or filler, and each sentence carries distinct 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?

With only two simple parameters and no output schema, the description covers the trigger, the async return path via mttr_job, and the throttling rule, which is enough to call it correctly. It falls short of complete because the behavior at the ten-minute boundary is 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?

Schema coverage is 100% and both parameters (site as a domain, reason as a few words) are already documented in the schema, so the description adds nothing parameter-specific. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('read a site again') and adds the precondition 'after it has been changed', which separates it from a plain read like mttr_site or mttr_crawls. It does not name any sibling explicitly, so the differentiation is implicit 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?

The trigger condition ('after it has been changed') gives clear context for when to call it, and pointing at mttr_job for the returned handle is a useful follow-up route. No exclusions or 'use X instead' guidance is given, which is the only gap.

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, so the safety profile is covered. The description adds useful behavioral context—results are paginated a screen at a time, ordered newest first, limited to sites with pending items, and include a total across all sites plus a quotedDetail field. It still does not explain page size or the item structure, and no output schema exists to fill that gap.

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 compact sentences, each contributing distinct information: what is returned, ordering and pagination, and the quotedDetail field. The prose is slightly cryptic in the first sentence, but nothing is wasted and the key scoping constraint is front-loaded.

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 read-only list tool with a single parameter and no output schema, the description covers the essentials: scope, ordering, pagination behavior, totals, and one returned field. Missing details such as page size and item shape keep it from being fully complete, but it is adequate to call 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?

The single offset parameter is fully documented in the schema as the number to skip for the next part of a long list, and the description's 'a screen at a time' reinforces pagination semantics. Schema coverage is 100%, so the baseline of 3 is appropriate; the description adds no format or sizing detail beyond what the schema says.

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 identifies a specific resource—model verdicts that could not be relied on and are waiting for human review—and clarifies that these items do not count toward a score. This is clear enough to distinguish the tool's output from generic list or queue tools, though the phrasing is awkward and it never names how it differs from siblings like mttr_queue or mttr_queue_done.

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 or when-not-to-use guidance, and no named alternative tool. An agent is left to infer from the description that this is the human review queue, but sibling tools such as mttr_queue and mttr_queue_done are not mentioned or contrasted.

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

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

Annotations already establish readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful disclosure about the payload's shape (stage, weight, remediation per rule), but says nothing about list size, ordering, or whether the catalog is static — meaningful context for a no-parameter catalog call.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single clause, front-loaded with the 'rulebook' framing followed by the concrete contents. No filler, and the most decision-relevant information (what fields each rule carries) comes 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 zero-parameter read tool with no output schema, the description adequately conveys what comes back and why it matters ('how to fix a failure'). Only the absence of any guidance on when to consult it keeps this from being fully 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?

Zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly implies the tool takes no filters.

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?

Names a concrete resource ('every rule mttr checks') and enumerates the fields each entry carries: stage, weight, and remediation guidance. The verb is only implicit ('The rulebook'), but no sibling among the ~60 tools plausibly overlaps with a rule catalog, so disambiguation is not a problem.

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 statement and no reference to alternatives or prerequisites. An agent can infer this is reference material to consult before acting on check results, but that inference is left entirely to the reader.

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?

Despite no output schema, the description fully describes the return shape: JSON-LD as data and inside a script tag, plus required fields left empty, invalid values detected (zero price, non-ISO currency, partial hours), recommended fields omitted, and the field map per type. It also confirms the no-fetch behavior, consistent with readOnlyHint and 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?

The purpose is front-loaded, but the middle is a long run-on sentence whose embedded return-value list ('the required fields left empty, what is not right..., the recommended fields left out...') is grammatically tangled and slow to parse.

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 3-param generator with no output schema and nested object input, the description covers types, input conventions, return contents, and validation behavior. Only the exact textual format of the returned field listing is left fuzzy.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents all three parameters, setting a baseline of 3. The description adds useful semantics for 'type' alone (discovery mode) and for 'fields' (empty values are dropped, not invented), but nothing beyond that for 'as'.

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 artifact: 'Makes JSON-LD for one page from the fields given,' then enumerates the supported types. 'Fetches nothing' and the explicit exclusion of FAQPage/HowTo pin down the scope so there is no ambiguity about what it produces.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete procedural guidance: 'Call it once with only "type" to see the fields' and 'Give only values the page shows.' It also explains the exclusion rationale (Google no longer shows FAQPage/HowTo). It doesn't name a sibling alternative, but no sibling overlaps this generate-schema job.

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 and openWorldHint=false. The description adds genuinely useful context beyond that: a scope cap ('At most 12 sites are read'), the return grouping ('bySite', 'quoted'), and a semantic caveat ('similar in meaning, not right, and not cited by an assistant'). It doesn't cover result ordering edge cases but adds real value.

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 content mostly earns its place, but the single run-on sentence is hard to parse ('and each site once by its best passage under "bySite", from the sites closest...'). Return shape and filtering options are tangled together rather than front-loaded, hurting readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description earns credit for sketching the return shape ('bySite', 'quoted') and the 12-site scope. However, it omits limit behavior, empty-result handling, and ordering, leaving meaningful gaps for a search tool whose return contract isn't otherwise documented.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so both 'sites' and 'market' are documented in the schema. The description echoes the market/site filtering ideas but adds no format or behavioral detail beyond the schema, matching the baseline-3 case where structured fields do the heavy lifting.

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 action (ask a question, get answering passages) and the resource (passages grouped under 'bySite' and 'quoted'). It's clear this is semantic retrieval, but it never names or contrasts a sibling (e.g., mttr_similar, mttr_explore), so an agent must infer differentiation on its own.

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?

Filtering options ('from the sites closest to the question, one market, or named sites') imply when to use it, and the 'similar in meaning, not right' caveat frames expectations. But there is no explicit when-to-use/when-not or named alternative, so guidance is only implied.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=false), it discloses two things the annotations don't: the key is shown only once, and it also returns the command that connects with it. It does not cover rate limits or error cases, but the critical irreversibility of the key display is surfaced.

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 compact sentences, front-loaded with the core action, followed by return values and the follow-up path. Slightly awkward wording ('its private parts,' 'reads any public site's report at once') costs a bit of clarity 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 no output schema, the description correctly compensates by describing the return (the key, shown once, plus a connect command) and the follow-up path. For a single-parameter bootstrap tool this is nearly complete; only failure/duplicate-signup behavior 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?

There is one required parameter, fully documented by the schema ('The person's email address'). The description adds no format, validation, or domain-restriction detail beyond that, so the schema does all the work — baseline 3.

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?

It states a specific verb and resource — signing a person up with their email — and uniquely identifies itself as 'the one call that works before mttr has a key for them,' which no sibling does. The phrasing is a little informal ('signs the person up'), but an agent can tell this is the bootstrap/registration tool.

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 clearly places itself as the entry point (the only call available pre-key) and gives sequencing: use the returned key to 'connect again,' and use mttr_claim to add private data for a claimed site. No explicit when-not guidance, but the gating condition is stated.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered; the description adds meaningful context beyond that: results are derived from text vectors, embedding is a prerequisite, and each nearest-page result carries the two closest passages returned under a "quoted" key. It does not say what happens when the site has not been embedded.

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?

Four tight sentences with the core purpose front-loaded and no filler. The phrasing is choppy ("Passages come under 'quoted'." is a bare fragment) but every sentence carries 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?

With no output schema, the description does the work of explaining the return shape (grouped pages, or nearest pages each with two quoted passages) plus the embedding prerequisite. Remaining gaps are limit scoping and failure behavior for un-embedded sites, which are minor for a read-only lookup tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents site, path, and limit; the description only reinforces path's two behaviors. It adds no meaning for limit (whether it caps groups or individual pages) and gives no format hints beyond the schema's example domain.

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?

Names a specific resource (pages that mean nearly the same thing, grouped, potentially competing for one search) and distinguishes the two modes of operation (site-wide grouping vs. nearest-to-a-path). It never names a sibling such as mttr_near or mttr_gaps, so an agent must infer the boundary from the wording 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?

Gives a real precondition — "the site must have been embedded" — and explains that supplying a path switches to nearest-page mode while omitting it yields grouped results. There is no explicit guidance on when to pick this over alternatives, but the usage 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 and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: data reflects the 'latest run', `rank` is scoped to 'every ranked site', and `card` is only present 'when its report is public', with an anonymous card substituted for a site 'kept by its code' — a non-obvious privacy/availability condition.

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 purpose is front-loaded, which is good, but everything is crammed into one long run-on sentence dense with backticked field names and nested parentheticals, which makes it hard to scan. Given there is no output schema the return-value detail earns its place, but the packaging does not.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description must carry the whole return contract, and it does: it names each field family, explains `rank` as {place, of}, sources `served` from three inputs, and conditions `card` on report visibility. An agent could call this and interpret the result without further documentation; only error/not-found behavior 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?

There is a single parameter at 100% schema coverage, and the schema already says 'The site, as a domain such as example.com.' The description adds nothing about the `site` argument itself — no constraints, normalization rules, or behavior on unknown domains — so it sits at the baseline the schema earns.

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 the resource precisely — 'one site as its latest run found it' — and enumerates its payload (score, grade, four stage grades, rank, served towns, fixes). This clearly separates it from the plural sibling mttr_sites and from report-style siblings like mttr_brief. It lacks an explicit verb ('get'/'return'), but the intent 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 only implied: an agent must infer that this is the single-site drill-down used after mttr_sites or mttr_leaderboard. There is one concrete instruction — 'send it to your person with the answer' for the `card` — but no when-not-to-use guidance and no named alternative for overlapping tools such as mttr_page or mttr_brief.

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, so the safety profile is covered. The description adds useful context about the returned fields and the 'sites mttr has read' scope, but it does not discuss pagination defaults, sort behavior, or authorization boundaries.

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 zero waste. It states the action, scope, and return summary immediately.

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 a fully described six-parameter schema and read-only annotations, the description provides a good high-level picture of what the tool returns. It omits some list-tool details such as default sorting and pagination semantics, but these are partly covered by the schema and there is no output schema to explain.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and all six parameters including the three enums are documented directly in the schema. The description adds no parameter-specific meaning beyond the return fields, so the schema does the heavy lifting as expected for a baseline 3.

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: it lists the sites mttr has read, and adds the return fields (latest score, page count, rule to fix first). It is clear what the tool does, though it does not explicitly distinguish itself from the singular mttr_site or other list-like 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?

The description implies usage by saying it lists sites mttr has read, so an agent can infer this is the plural overview tool. However, it gives no explicit when-to-use guidance, no exclusions, and does not name alternatives such as mttr_site for single-site detail.

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 cover the safety profile (readOnlyHint=true, openWorldHint=true), and the description adds substantial context beyond that: it discloses the exact number and kind of network calls made (one TLS handshake on 443 with SNI, one plain-http request, one https request), what the warning and failure thresholds are (under 30 days, expired, not-yet-valid), and that results are expressed as word-states with remediation. It stops short of saying whether results are cached or how long the check takes.

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, which is good, but the enumeration of every measured attribute runs long and reads as a feature list rather than guidance. It is dense and information-rich but could be trimmed or bulleted without losing substance.

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 single-parameter read-only diagnostic with no output schema, the description does the heavy lifting of describing returned findings, state words, and remediation text. A brief note on response shape or ordering would make it complete, but an agent can call this correctly as written.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the schema already explains that a full address is accepted and only the host is used. The description reinforces this by emphasizing 'one public host' and 'Public addresses only', which meaningfully constrains input to publicly resolvable names — an added constraint beyond the schema's phrasing.

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 ('Checks one public host's SSL certificate') and then enumerates exactly what is measured: validity for the name, issuer, dates, chain, TLS version, HSTS, http-to-https redirect. Nothing in the sibling list does certificate inspection, so it is clearly distinguishable.

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 description scopes usage tightly ('one public host', 'Public addresses only') and implies the call is a one-shot diagnostic, but it never names an alternative tool or says when not to reach for it versus related site tools like mttr_site or mttr_rescan. Clear context, no explicit exclusions.

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, so safety is covered. The description adds useful substance about what dimensions are measured, but says nothing about freshness, whether it triggers a crawl, latency, or cost — the traits an agent actually needs for an analysis 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?

A single tight sentence with no filler, and the four measured dimensions are listed up front. It is a sentence fragment rather than a statement of action, which slightly weakens the front-loading of a verb.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description should convey the shape and nature of the result; it does list the metrics but omits whether the response is per-section, how depth is bucketed, and whether a prior crawl is required. Adequate but with real gaps for an analysis tool in a 60-sibling namespace.

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 `site` and `links` are documented in the schema, including the content/all enum and the default. The description mentions links between sections but does not clarify the content-vs-all distinction, so it adds no meaning beyond the schema. Baseline 3.

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 resource (a site's structure) and enumerates what it contains: sections, click depth from the home page, share of each section linked from content, and inter-section links. That is far more concrete than a tautology. It stops short of differentiating from siblings like mttr_site, mttr_map, or mttr_pages, which also sound structural.

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 guidance on when to use this versus mttr_site, mttr_map, mttr_pages, or mttr_brief, nor any prerequisite such as needing a completed crawl. The agent must infer the use case from the noun phrase alone.

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

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

Annotations already establish readOnlyHint=true and openWorldHint=false, so the bar is lower, and the description still adds real value: result ordering (strong signs first), an explicit caution that a sign is not proof, and a convention for presenting quoted site text. It omits any note on pagination despite limit/offset params.

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 concrete sign list in a single dense sentence, then two short caveat sentences. Mostly earns its space, though the trailing "Site text comes under 'quoted'." is cryptic and reads like an unexplained convention.

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 read-only, non-destructive lookup with no output schema, the description covers what is detected, how results are ordered, and how to treat them (signs are not proof). The only soft gap is return shape and pagination behavior, which the limit/offset params imply but the description never confirms.

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 all four parameters (including the show enum defaulting to 'strong') are already documented. The description's "Strong signs first" weakly echoes the show semantics but adds no syntax or format detail beyond the schema. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names the exact resource (signs of generated text on a site's pages) and enumerates the specific indicators it detects: hidden/tag characters, left-in chat and markdown, unfilled placeholders, stock phrasing, heavy dash use. No sibling tool covers this, and an agent can tell immediately what it returns.

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 interpretive guidance ("Strong signs first. A sign is not proof.") and a note on quoting, but never states when to reach for this tool versus alternatives or what preconditions apply. Usage is implied rather than prescribed.

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, so safety is covered; the description adds real semantic detail beyond that: the board is ordered by 'worth', it surfaces regressions ('what slipped back'), and it embeds the domain rule that a fix only counts as done once a later read finds it passing. It does not mention size limits or whether the list is truncated, which keeps it below a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

It is a single dense sentence with no filler, so it is compact, but the front-loaded clause buries the plain meaning under a 'progress page' metaphor. The most useful line, the definition of done, is stranded at the end after a list of mostly decorative labels.

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 permissive annotations, the description carries the whole burden of explaining what comes back. It does name the content sections, which is the minimum an agent needs, but gives no sense of ordering stability, volume, or item shape, so it is adequate rather than 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?

The tool takes zero parameters, which is the baseline-4 case; there are no argument semantics to explain. The description correctly implies the call is context-free (scoped to 'the person's' own sites) rather than parameterized.

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 name and title say 'todo' / 'work board', and the description enumerates what the board holds (next fix, other fixes by worth, regressions, verified fixes, sites needing re-read). However, everything is expressed in metaphor ('what slipped back', 'the words to work from', 'by worth'), so an agent must decode terms rather than read a plain statement of purpose. It also never distinguishes itself from similarly-scoped siblings like mttr_queue, mttr_content_next, or mttr_plan.

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 statement of when to call this versus alternatives, and no prerequisites or exclusions. The only implicit cue is that it is a dashboard-style summary of current work, but the agent has to infer that calling this is the way to find out what to do next.

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

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

Annotations already cover safety (readOnlyHint=true, openWorldHint=false), so the bar is lower. The description does add one genuinely useful behavioral note — topic names are model-generated and therefore returned in quotes, which tells the agent to treat them as labels rather than canonical strings. It says nothing about result volume, pagination, or freshness, which are the remaining unknowns for a read tool of this shape.

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 compact sentences with no filler, and the 'what a site covers' framing is front-loaded. The enumeration of the three output kinds is dense but each clause carries 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?

With no output schema, the description does the right thing by sketching the returned content, which is the main gap it needed to fill. However, it leaves the agent unsure about scale (how many topics/pages) and about how this differs from the many other site-analysis siblings, so it is adequate rather than 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?

The single parameter has 100% schema coverage ('The site, as a domain such as example.com'), so the description owes little here. It adds no extra meaning such as whether a bare domain vs. subdomain or URL is accepted, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description conveys what comes back (subjects, pages under each, competing pages, coverage gaps) but never states a clean verb+resource like 'returns the site's topic taxonomy'. It is distinguishable from mttr_pages or mttr_traffic in flavor, but it never names or contrasts any sibling, so the agent must infer the boundary.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no 'use this when...' guidance and no mention of alternatives such as mttr_gaps, mttr_structure, or mttr_queries, despite those siblings clearly overlapping with the 'missing subject' and 'competing pages' concepts described here.

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, so the safety profile is covered. The description adds a genuinely useful prerequisite not in the schema or annotations: 'Only sites whose owner added mttr in Search Console have any' — an agent needs this to interpret empty results. It also sketches what the result contains (clicks by day, totals vs prior days, pages ranked by loss).

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 content is essentially a few run-on sentences with broken grammar ('the totals against as many days before'), forcing the reader to re-parse clauses. Key facts are present but not front-loaded or cleanly separated, so structure costs readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description must convey what is returned, and it does attempt that (clicks by day, totals vs baseline, per-page deltas). But the garbled phrasing and missing pagination-return detail leave an agent partially guessing about result shape.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents show/site/limit/offset, making 3 the baseline. The description reinforces 'show' by tying 'lost most first' to the default-ish lost ranking, but adds no format or interpretation detail beyond what the schema states.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence identifies the resource (clicks from Google search via Search Console), and the description branches clearly into a no-site mode and a with-site mode. However, the language is heavily tangled ("the searches nothing on two or more of the sites answers") and never states a clean verb+resource, so an agent must decode intent rather than read it. Siblings like mttr_queries or mttr_pages are not named or distinguished.

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 site vs no-site branches imply when each shape of result applies, and "A baseline to judge a change by" hints at the use case. But there is no explicit when-to-use-vs-alternatives guidance and no exclusions relative to the many sibling traffic/query tools.

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