clickd

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

Goes well past the readOnly/openWorld annotations: it discloses the two distinct return shapes, the failure modes (site never read, draft, answers not found), the remediation path (mttr_rescan reads it), and the auth posture ('Works with no key'). That is exactly the operational context annotations cannot carry.

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 labeled beats (purpose, When, Instead, Inputs, Returns, Fails) so an agent can scan to the part it needs. The telegraphic, comma-spliced phrasing ('the four fixes worth the most as steps with pages and points, and words to hand another agent') is efficient but takes a second pass 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?

With no output schema, the description carries the return-value burden itself and does so — naming the fields returned in steps mode (steps, prompt, report, caveat) and the plain-text markdown return. Failure handling and the fallback tool are covered, leaving nothing an agent needs to call this correctly.

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

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

Schema coverage is 100%, so baseline is 3; the description earns above that by explaining what each enum value actually yields — markdown returns the whole list, steps returns 'the four fixes worth the most' as steps with pages and points plus wording to hand to another agent. The `site` explanation ('a domain, such as example.com') is a straight restatement of the schema, which holds it back from a 5.

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 ('Gets a site's fixes as a work order') and then spells out the payload shape: what to fix, in what order, how, why, on which pages. It is explicitly distinguished from mttr_site and mttr_todo in the same breath, so an agent can pick it 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?

The 'When' clause gives two concrete trigger points (start of work on a site; after mttr_changes reports a read is done), and the 'Instead' clause routes to mttr_site for a human-facing score and mttr_todo for the cross-site next fix. Both inclusion and exclusion conditions are named.

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, and the description adds the rest: a polling cadence, that changes are null on a first read and stay null until the job completes, explicit failure modes (unread site, job/site mismatch => not found; failed read reported in job state), and that a key is required.

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 outcome, then segmented into When / Instead / Inputs / Returns / Fails. Every clause carries information an agent needs for selection or invocation; no filler.

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

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

No output schema exists, and the description fully compensates with a Returns section describing host, run, changes (null on first read), visits, and the job object shape. Failure semantics and auth are also covered, so nothing needed to call it correctly 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 parameter docs are already there. The description still adds real meaning: `site` is a domain like example.com, `job` is the id returned by mttr_rescan, and specifying job switches the response into a job-state-plus-changes shape, which the schema does not convey.

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: what a site's latest read changed against the previous one, then enumerates the diff surface (score, rules fixed/newly failing, pages added/removed). The 'Instead' line names mttr_rescan and mttr_site, so an agent can separate it from siblings 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?

Explicit sequencing: call after mttr_rescan and poll every minute or two with its job until the read finishes. It also names the alternatives and the condition that selects them (mttr_rescan to request a read, mttr_site for the standing report), leaving nothing 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?

Goes well beyond the readOnlyHint/openWorldHint annotations by disclosing refusal of private addresses, robots.txt obedience, the free-tier hourly allowance, and that no key is needed. The 'Returns' and 'Fails' lines give the agent the safety and failure envelope the annotations cannot.

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?

Labelled sections (When / Instead / Inputs / Returns / Fails) front-load the intent and constraints, with zero filler sentences. Every line carries information an agent needs to select and call the tool.

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

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

No output schema exists, yet the description explains the return shape ('findings, each with its state in a word and what to do when it is wrong') and covers failure modes and quotas. Nothing needed to call this two-parameter tool correctly 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 already 100%, but the description adds real meaning beyond it: it enumerates what each `kind` value checks and clarifies that `ssl` uses only the host portion of `url` while `locations` expects the brand's site. That nuance is not derivable from the schema and materially helps correct invocation.

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 live address now') and enumerates the five check kinds, which immediately signals the tool's scope. It is distinguishable from siblings like mttr_pages and mttr_rescan 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?

'When: before and after a fix to one page, link or host' gives an explicit trigger, and 'Instead: mttr_rescan and mttr_changes ... mttr_pages' names the alternatives and the conditions that favor them. This is a textbook routing block.

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 and openWorldHint; the description adds the important beyond-schema facts: results come from prior lookups rather than triggering a new one, rows stays empty until a lookup exists, and a key plus a claim are required. It also enumerates the return fields (host, rows, credits, price, perDay, note), which matters since no output schema exists. Nothing here conflicts with the read-only annotation.

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?

Five short labelled lines with the core purpose first, then When/Instead/Inputs/Returns/Fails. Every line carries distinct information — no restatement or filler — and the prerequisite failure mode is called out in its own slot rather than buried.

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 tool this covers purpose, alternative, input format, all return fields (no output schema exists), auth prerequisites, and the empty-result failure condition. An agent has everything needed to decide and call correctly.

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

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

Schema coverage is 100% and the single `site` parameter is already documented as a domain in the schema; the description's "`site` is a domain, such as example.com" largely restates it. Baseline 3 applies because the schema carries the parameter load.

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

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

Specific verb and resource: lists the citations assistants were found to make for a site, question by question, drawn from existing lookups. It also scopes the data source ("from lookups already made") and separates itself from mttr_site in the next line, so an agent can pick it without opening either schema.

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

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

"When: to tell a person whether assistants cite their site, at no cost" gives the trigger, and "Instead: mttr_site for how well formed the pages are, which is not whether they are cited" names the sibling and the exact distinction that selects between them. Both the when and the not-this are explicit.

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

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

Beyond the annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false), the description discloses the two-phase nature of the operation, that a person's key is required, and two real failure modes: 'check' before the proof is published returns claimed=false, and new DNS records can take minutes to propagate. It does not address what happens if a site is already claimed or how to revoke, which keeps it below 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?

Labeled lines (When/Instead/Inputs/Returns/Fails) front-load the routing decision before mechanics. Every sentence carries new information; nothing is redundant 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?

There is no output schema, so the description supplies the return fields for both steps (site, record, dns, file, note; site, claimed, how) and covers prerequisites and failure behavior. An agent has everything needed to run the two-step claim correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns more by explaining what each step value actually does — 'start' emits the record and file, 'check' looks for either and adds the site — which the bare enum labels do not convey. The 'site' explanation merely restates 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 ('claims a site') and explains the mechanism (TXT record or file plus the check that finds it). It also names the sibling tools it is not (mttr_signup, mttr_site) so an agent can route without opening schemas.

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?

An explicit 'When' line gives the motivating condition (opening a site's private parts such as rivals, citations, proposals), and the 'Instead' line names two alternatives with the condition that selects each — signup first for a key, mttr_site for public reports needing no claim.

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 readOnlyHint/openWorldHint annotations, it discloses authentication ('Works with no key'), ranking exclusions ('drafts and closed sites are not ranked'), and the degenerate case ('a crowd too small answers an empty board'), plus the returned shape (total, offset, limit, sites, tiers, note) since there is no output schema. These are the exact behaviors an agent cannot infer from structured fields.

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 front-loaded with purpose, then sectioned into When / Instead / Inputs / Returns / Fails, so each line answers a distinct question. No sentence restates the name or title, and the density is appropriate for a 7-parameter tool with no output schema.

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

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

With 7 optional parameters, no output schema, and no nested objects, the definition still covers return fields, paging, filter interaction, failure/empty behavior, and auth requirements. An agent has everything needed to call this correctly and interpret the response, including the record variant.

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 real semantics: filters can be combined 'together or alone', 'city' requires a state (a dependency not stated in the schema), and 'record' substitutes a single record for the place list. 'limit'/'offset' are only glossed as paging, which the schema already covers.

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

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

The description opens with a specific verb and resource ('Lists the public leaderboard') and immediately scopes it as every ranked site by latest score, a single crowd, or a single record. It explicitly separates itself from mttr_site and mttr_rivals, so an agent can route between the three without opening the schema.

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

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

It uses an explicit 'When:' trigger (show a person where a site places among every site, or sites like it) and an explicit 'Instead:' clause naming both alternatives, mttr_site for one site's own place and mttr_rivals for nearest sites. The selection condition between this tool and its siblings is fully determined.

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 annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=false) it discloses the failure mode ('a proposal or task not the person's keeps nothing and says so'), the auth requirement ('Needs a person's key') and a privacy caution ('Never send private data'). It even describes the return shape, which annotations cannot convey.

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

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

Front-loaded and chunked with When/Instead/Inputs/Returns/Fails labels, making it fast to scan. The Inputs section largely restates the schema descriptions verbatim, which is slightly redundant at 100% coverage, but nothing is padded or vague.

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 Returns line supplies the response fields (kept, site, step, note, proposal/task, left). Combined with failure conditions and the auth note, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it clarifies that `proposal` names a proposal carried out (linking it to mttr_propose), that `task` is the queued task finished, and that files/rules are comma separated. Only `found` is left to the schema alone.

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 ('Records a step of work on a site for the person's progress page') and immediately enumerates the kinds of steps recorded, so the agent can tell it apart from mttr_propose and mttr_todo without opening a 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?

Explicit 'When:' clause (after each step, including carrying out a proposal or finishing a queued task) plus an 'Instead:' clause that routes to mttr_propose before deploying and mttr_todo for waiting tasks. When-to-use, alternatives and exclusions are all present.

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 well beyond readOnlyHint/openWorldHint: it discloses that results come from the 'latest read' snapshot rather than live state, that a key is required but any key reads a public site, and that an unread site or page answers 'not found'. It also spells out the return shape, covering behavior the annotations do not.

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?

Labelled sections (When / Instead / Inputs / Returns / Fails) front-load the routing decision before the parameter detail. The telegraphic register packs ten parameters and error behavior into a few lines with no filler.

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

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

For a 10-parameter read tool with no output schema, the definition still covers inputs, return fields, failure mode and auth requirement — everything needed to call it correctly. No material gap remains.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real semantics the schema lacks: that `path` returns one page in full and causes the remaining filters to be ignored — a precedence rule an agent could not infer. The `site` domain example and the grouping of the narrowing/sorting/paging parameters add modest further value.

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 ('Lists the pages of a site's latest read') plus the per-item fields returned, and explicitly contrasts the two modes (list vs. one page in full). An agent can distinguish it from mttr_brief and mttr_check 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?

Has explicit 'When' conditions ('find the pages behind a fix, or everything wrong with one page') and an 'Instead' clause naming two sibling alternatives with the condition that selects each. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, but the description adds important behavior beyond them: failure on id+site, not-found behavior for another person's proposal, and the requirement for a person's key. It also describes the return shape in enough detail to set expectations.

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 then organized into When, Instead, Inputs, Returns, and Fails. The telegraphic style is dense but every line carries actionable information, with no filler.

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

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

There is no output schema, but the Returns section describes what comes back with id, without id, and with site. Combined with failure conditions, auth needs, and polling guidance, the description is complete for this read-only 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?

Schema coverage is 100%, so the baseline would be 3, but the description adds meaningful semantics: `id` comes from mttr_propose and deploys only once approved, `site` returns that site's proposals and mode, and providing neither returns every proposal while providing both is refused.

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+resource: it lists proposals, optionally one by id or all for a site, and reports approval mode. It also distinguishes the tool from mttr_propose and mttr_todo, so an agent can select it without opening sibling schemas.

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

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

It gives explicit timing: before work on a claimed site and every few minutes after mttr_propose until answered. It also names alternatives and tells the agent when to use mttr_propose versus mttr_todo, while warning to deploy only after approval.

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 say this is not read-only, not destructive, and not open-world. The description adds much more: a person is emailed, the links expire in 72 hours, the diff is shown but never applied, the rate limit is 20 proposals per site per hour, and a person's key is required. It also names the failure case ('a site not claimed with this key answers not found'). None of this contradicts 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 labeled sections (When / Instead / Inputs / Returns / Fails) put the key routing and behavior facts first and make the text easy to scan. The Inputs block partly duplicates a schema that is already fully documented, which is the only real waste.

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

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

There is no output schema, so the description carries the burden of explaining returns, and it does: proposal ({ id, state, deploy, ... }), note, and promise. Combined with the stated auth requirement, rate limit, and failure mode, an agent has everything it needs to call this tool and interpret 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?

Schema coverage is 100%, so the baseline is 3. The description still adds meaning beyond the schema for `diff` ('shown and never applied') and clarifies the roles of `rule`, `pages`, and `summary`, though most of the other parameter text repeats what the schema already documents.

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

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

The description opens with a specific verb and resource ('Proposes a change before you deploy it') and immediately explains the mechanism: an email with Approve/Decline links that lapse in 72 hours. This clearly separates it from the read-only sibling mttr_proposals, which is named later 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?

It gives an explicit trigger ('before each deploy to a site mttr_proposals says is set to approve') and names two alternatives with the condition that selects each: mttr_proposals with the id to wait for the answer, and mttr_log_work once the change is carried out. Nothing about routing is left to inference.

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

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

Annotations only say readOnlyHint=false, openWorldHint=true, destructiveHint=false; the description goes well beyond by disclosing an auth requirement ('Needs a key'), a ten-minute deduplication/rate window with the actual refusal payload (allowedAt), the duplicate-suppression signal (added=false), and the private-address rejection. That is exactly the behavioral context annotations cannot carry.

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?

Labelled lines (When / Instead / Inputs / Returns / Fails) front-load the decision-relevant information, and every line carries distinct content with no repetition. The telegraphic style is dense but purposeful.

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 still enumerates the response fields (job, added, allowedAt, ahead) and covers both failure modes and the key requirement. Nothing an agent needs to call it correctly or interpret 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 baseline is 3, and the description's 'Inputs' lines largely restate the schema text ('site is a domain, such as example.com' vs. 'The site, as a domain such as example.com'). The 'in a few words' note on reason is a mild addition but nothing about format, optionality, or effect of omission is added.

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 (queue a fresh read of a site) plus the side effect (returns a job to follow), which is more than the title's vague 'Read a site again'. It explicitly separates itself from mttr_changes and mttr_check, so an agent can pick it without opening either schema.

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

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

The 'When' clause names two concrete trigger conditions (post-fix deployment, never-read site) and the 'Instead' clause routes the agent to mttr_changes for examining what a read changed and mttr_check for a single live page. Explicit when, when-not, and named alternatives.

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 establish read-only and closed-world behavior, but the description adds meaningful operational context: the data comes from existing reads, the tool needs a key and a claim, and specific failure modes are documented. It also previews the return shape by view, which helps an agent understand behavior 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 front-loaded and uses clear labeled sections (“When,” “Instead,” “Inputs,” “Returns,” “Fails”), so an agent can scan it quickly. Despite its density, every sentence carries actionable information and there is no filler.

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

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

For a four-parameter read-only tool with no output schema, the description covers inputs, alternatives, failure cases, authentication needs, and a rough return overview. The return description (“host, then by view...”) is helpful but somewhat compressed and could be more precise about exact response structure.

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 useful semantics beyond the schema descriptions: it explains what `with` means when omitted and how `view` values differ, especially that `rules` and `content` require `with`. The parameter guidance is strong overall, though some details remain terse.

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

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

The description gives a specific verb and resource (“Sets a site against its rivals”) and clarifies the scope (“from reads already kept: who they are, how close, and where it is behind”). It also distinguishes itself from sibling tools by naming mttr_leaderboard and mttr_site and explaining the alternative use cases.

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 states when to use the tool (“to pick the fixes that matter against the sites a buyer compares it with”) and names alternatives for different comparisons (“mttr_leaderboard for places among every site; mttr_site for its own score”). This gives clear routing guidance without requiring inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely non-redundant context that annotations cannot express: 'Works with no key' removes an auth prerequisite question, and 'Fails: nothing to refuse' rules out error handling. It stops short of describing ordering or pagination, so not 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?

Six short labeled lines (purpose, When, Instead, Inputs, Returns, Fails) with the core definition front-loaded and zero filler. The labeled structure makes it scannable, and each line carries distinct information rather than restating the title.

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

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

There is no output schema, so the 'Returns' line does the work by enumerating the returned fields. Combined with the explicit no-parameters and no-auth statements, an agent has everything needed to call this correctly on the first attempt.

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, and the description confirms this explicitly with 'Inputs: none', which is the baseline 4 for a parameterless tool. There is no syntax to clarify, and the 'Returns' line pre-empts any confusion about whether filtering arguments exist.

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: 'Lists the rulebook: every rule clickd checks', and it enumerates the returned fields (id, stage, weight, fix). Two explicit 'Instead' pointers to mttr_brief and mttr_pages let an agent distinguish this from sibling tools without reading further.

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

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

The 'When' line gives both intended purposes (explaining a fix to a person, finding a rule's id), and the 'Instead' line names two alternative tools with the exact conditions that select them (rules one site fails, and pages failing one rule). That is an explicit, actionable routing guide.

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, and the description reinforces this with 'fetches nothing' and 'works with no key' (auth context). It also discloses the failure mode ('a type not offered says which are') and the returned keys, though it doesn't explicitly confirm nothing is persisted beyond the readOnly hint.

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 purpose, then structured When/Instead/Inputs/Returns/Fails labels. Telegraphic fragments but every line carries distinct information with no redundancy.

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

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

No output schema exists, but the description enumerates the return keys (jsonld, script, missing, problems, recommended, fields), and covers inputs, failure behavior, and auth. An agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so baseline is 3; the description still adds meaning by explaining `as` as a narrower subtype (e.g. Plumber) and that `fields` holds values by field key as text with 'give only what the page shows' as a content constraint.

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 output artifact: 'Makes JSON-LD for one page from the fields given, ready to paste, and fetches nothing.' The scope (one page, no fetching) and the contrast with mttr_check make it unambiguous which sibling to choose.

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:' clause ties it to fixing structured data a fix asks for, and 'Instead:' names mttr_check with kind product as the alternative for live pages. It even gives a discovery path ('call it with only type to see the fields'), leaving nothing 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?

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=false) by disclosing the one-time visibility of the key, the failure modes (duplicate email, invalid email), the rate limit of three per hour per address, and that no key is needed to call it. These are exactly the operational facts an agent cannot get from structured fields.

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?

Labeled lines (When / Instead / Inputs / Returns / Fails) front-load the purpose and route, and every line carries distinct information with no repetition of the title or schema.

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

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

No output schema exists, but the description enumerates the return fields (email, key, connect, next); it also covers preconditions, error cases, and rate limits. For a single-parameter tool this leaves nothing an agent needs 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?

With one parameter at 100% schema coverage the baseline is 3, and the description earns a step up by clarifying that the email is the person's *own* address rather than an arbitrary one — a real constraint for a signup call. It is a small addition, so not a 5.

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

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

Specific verb+resource: signs a person up by email and returns a free key with the connect command. It also names the sibling it is not (mttr_claim) and scopes what is returned, so an agent can separate it from the other 17 mttr tools without opening the schema.

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

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

"When: before any call that needs a key, when the person has none" gives an explicit precondition, and "Instead: mttr_claim, once connected with the key" names the alternative plus the condition that selects it. Nothing about sequencing is left to inference.

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

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

Annotations only declare readOnlyHint and openWorldHint; the description adds failure modes ('a site never read, a draft or one kept unnamed answers not found') and auth context ('Works with no key'). It also discloses the return shape without an output schema. That is substantial value beyond the structured fields.

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?

Labeled sections (When/Instead/Inputs/Returns/Fails) make it scannable and front-load the purpose. Slightly dense with long clauses, but virtually every sentence carries distinct routing or behavioral 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 'Returns' line covers the shape, 'Fails' covers error conditions, and 'Inputs' plus the view/agent distinction covers invocation. An agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above baseline by explaining what 'agent' actually means ('the whole-site Agent View from the same read, with each AI crawler as robots.txt treats it') rather than restating the enum. The `site` note just mirrors the schema, so it is not a full 5.

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 ('Gets a site's report from its latest read') and enumerates the payload precisely: score, grades, rank, towns served, and every fix with its failing pages. The 'Instead' line names mttr_brief, mttr_rivals, and mttr_check so the agent can distinguish it from siblings 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?

Explicit 'When:' clause ('to tell a person how a site stands') plus an 'Instead:' block naming three alternatives and the exact condition each covers. This is the strongest possible 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 description focuses correctly on value-add: it discloses the auth requirement ('Needs a person's key'), the failure/edge case ('an account with no claimed site has an empty board'), and the ordering of the queue ('oldest first'). Minor gap: it doesn't say whether results are paginated or capped, but for a read-only board tool that is a small omission.

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 purpose and organized under When / Instead / Inputs / Returns / Fails labels, so an agent can scan for the needed section. Slightly redundant: 'what slipped and what is fixed' in Inputs is restated as 'slipped, fixed' in Returns.

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 parameter and no output schema, the description must carry the return-shape burden, and it does by enumerating the fields for both modes. Auth, failure mode, default value, and mode ordering are all covered, so nothing an agent needs to call it correctly 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% and the single enum parameter is already documented, so the baseline is 3. The description earns above baseline by explaining what each mode actually produces (board: next, everything by worth, slipped, fixed; queue: the person's tasks for you, oldest first) and by stating that 'board' is the default, which the schema does not say.

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: 'Gets the person's work across all their sites', and immediately distinguishes the two modes (next fix + everything by worth, or queued tasks). It also names the sibling it is not ('mttr_brief for every fix on one site'), so an agent can separate it from alternatives without opening schemas. The phrase 'every other by worth' is slightly garbled and keeps this from a clean 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?

Explicit when-to-use triggers ('when you start work for the person, and when a reply says tasks are waiting') plus explicit alternatives with their selecting conditions ('mttr_brief' for per-site fixes, 'mttr_log_work with task' for finishing a queued item). Nothing about routing is left to inference.

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