Edge

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false. The description adds the deprecation/aliasing behavior (identical side effects to report_issue) and a caveat about what does not qualify as an issue. It doesn't describe what happens after submission or any rate limits, but for a deprecated passthrough alias that is acceptable.

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

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

Three short sentences, front-loaded with the deprecation status so an agent knows immediately to prefer the alternative. Every sentence carries distinct information; nothing is repeated from 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?

With no output schema and full schema coverage, the description only needs to explain the tool's status and when to prefer its replacement, which it does. Minor gap: it doesn't say what a successful call returns or whether the report is acknowledged, though that is low-stakes for a deprecated alias.

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 kind, message, contact, and request_id are already fully documented in the schema, including the enum values and the privacy warning. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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

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

States precisely what the tool is (the old name of report_issue) and what it does (report a bug or idea about Edge itself). An agent can distinguish it from the sibling report_issue 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?

Explicit routing instruction: 'Call report_issue instead; this does exactly the same thing,' plus the retention condition for older setups. It also adds a negative case ('A host approval denial is not an Edge bug'), so the agent knows one class of input that should not reach this 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 destructiveHint=true, readOnlyHint=false and idempotentHint=true, so the safety profile is largely covered. The description adds two things annotations cannot express: irreversibility ('It cannot be undone') and the ordering requirement to pass confirm only post-confirmation.

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. The destructive scope is front-loaded, followed by the gating and confirmation rules in the same order an agent would apply them.

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 destructive tool with no output schema and full annotation coverage, the description supplies everything an agent needs: what is deleted, when it is allowed, the confirmation gate, and irreversibility.

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 1 parameter at 100% schema description coverage, so the schema already documents confirm fully; the description's confirm guidance largely restates it. 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?

States a specific verb (delete) and a precisely enumerated resource scope (searches, skill loads, ratings, issue reports) scoped to 'this user'. An agent can distinguish this from siblings like my_activity or feedback 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?

Gives an explicit gating condition ('Use only when the user asks to delete their Edge data') and a sequencing rule for confirm, which is real when-to-use guidance. It stops short of naming a sibling alternative (e.g., deleting individual items), so 5 is not warranted.

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 state the safety profile (readOnlyHint=false, openWorldHint=true, non-idempotent); the description adds material behavior the annotations cannot convey: the link is private, single-use, expires in 10 minutes, and must be echoed verbatim. It also discloses the security constraint of never persisting the link, which is the key operational risk here.

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 before the behavior and constraints, and every clause carries weight (single-use, 10-minute expiry, verbatim reply, no self-initiation, no persistence). It is dense and reads as one long compound sentence, which slightly hurts scannability but wastes no 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?

With no input or output schema, the description must cover the return value and handling on its own, and it does: it tells the agent exactly what comes back (a private one-time link line), how long it lives, and how to relay it. Nothing needed to call or post-process 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate — the baseline for a no-param tool is 4. The description correctly implies no arguments are needed beyond the implicit user context.

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 — returning a private one-time link to the user's Edge page/activity — with the trigger phrasing that identifies it ("open my Edge page"). It is clearly distinct from the skill-management siblings (use_skill, find_skill, scan_skill), so an agent can route 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-to-use ("Only when the user asks to open or see their Edge page or Edge activity") and explicit when-not ("Never call it on your own initiative"). It also prescribes post-call handling: reply with the returned line exactly, don't open the link, don't place it in files/commits/issues/shared docs.

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, idempotentHint=true) by explaining that retries with the same request_id never add a second rating, that the result is the Edge closing line, that the server identifies the skill from request_id, that notes over 280 characters are truncated, and that a Pro key gates the task block. This is unusually rich behavioral disclosure for a 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?

Purpose and the 'call once, after the work' instruction are front-loaded, but the rest is a single ~350-word run-on paragraph mixing outcome rules, scoring, privacy, Pro-key fields, and error handling. Almost every sentence carries content, yet the wall-of-text structure hurts scannability.

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?

Very complete for a 7-parameter tool with nested objects: it covers outcome vocabulary, score bands, reason defaults, component ids, the optional task report, privacy constraints, idempotency, and host-blocked fallback. No output schema exists, and the description still notes that Edge returns the user's weekly tally.

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 86%, so the baseline is 3; the description earns a bump by spelling out cross-parameter couplings the schema does not, such as which outcomes permit a score, omitting score for wrong_skill/loaded_not_used/unclear, and requiring the note for scores 0-2 and 9-10. It largely mirrors the schema's per-field text, 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 ('Records only an Edge rating of a skill you used') and immediately delimits what it is not: it does not change files, task output, or act outside Edge. An agent can distinguish it from siblings like report_issue and use_skill from the text 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 explicit timing ('call it once, after the work rather than right after loading'), conditions for skipping ('If the host blocks the call, finish without it'), and names the alternative tool for Edge problems ('use report_issue instead'). When-to-use, when-not, and the alternative 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?

Annotations only declare the write/openWorld/non-idempotent profile. The description adds real behavior beyond that: the agent may file this autonomously, must not include secrets or private user data, and may include contact only with explicit user consent. It does not describe what happens after submission (confirmation, follow-up), which keeps it short of 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?

Purpose is front-loaded in the first sentence, followed by the guardrail on host approvals and the sibling pointer. Every sentence carries a distinct instruction (self-initiation, exclusion, alternative tool, privacy, contact consent) 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 4-parameter, no-output-schema write tool, the description covers routing, exclusions, privacy, and consent well. It stops short of saying what acknowledgement or follow-up the caller receives, which is a minor gap given no output schema exists.

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

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

Schema coverage is 100%, so the baseline is 3, but the description meaningfully enriches the enum beyond the schema's terse 'bug, wrong_skill, setup, or idea' by mapping each kind to a scenario. It also restates the contact-consent constraint stated in the schema, adding intent but not new syntax.

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 (report a bug or idea about Edge itself) and enumerates the concrete situations that qualify: failed/wrong Edge calls, misfit skill suggestions, setup trouble, feature ideas. It explicitly contrasts itself with the sibling rate_skill, so an agent can route 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?

Gives explicit when-to-use (agent may self-initiate on an Edge call failure) and an explicit when-not (host approval denial is not an Edge failure; skip the blocked call). It names the alternative tool, rate_skill, for evaluating skill performance, 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?

Annotations already declare readOnlyHint/idempotentHint/openWorldHint, so safety is covered. The description adds real behavioral context beyond them: bundle checked before load, reuse of a current exact-bundle audit (caching semantics), the returned findings/date/serve-or-withhold decision, and the caveat that automated checks are not a guarantee.

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

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

Four dense sentences, front-loaded with the purpose before the routing caveat and the relay directive. Slightly packed with format/relay instructions, but every sentence carries operational value.

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 fills the gap by naming what comes back (findings, date, serve-or-withhold decision) and instructing the agent to relay it. Required-parameter looseness (0 required) is not addressed, which is a minor omission.

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 already documents both parameters, including 'as printed by find_skill'. The description's 'Pass source + skill as find_skill printed them' restates the schema's format guidance and adds only the pairing instruction, so baseline 3 is warranted.

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 — 'Check a catalog skill's security before using it' — and the first word ('catalog') immediately separates it from sibling use_skill/find_skill. An agent knows this is a read-only audit gate, not a loader.

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 the trigger ('before using it') and an explicit when-not with an alternative: 'To scan a skill on the user's machine, use the local Edge connector (npx @getedge/mcp).' It also tells the agent to source inputs from find_skill output, closing the workflow loop.

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

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

Annotations already declare readOnlyHint/idempotentHint/openWorldHint, and the description adds real context beyond them: loading is temporary and never installs permanently, and Edge screens against scanner audits and withholds skills that fail its security gate. It also warns to read third-party instructions before following them. It still doesn't say what auth/permissions or rate limits apply, 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?

Front-loads the core action, then moves to pagination and safety guidance. The sentences each carry information, though the security-gate and scanner-audit clause is somewhat elaboration-heavy and pushes the definition longer than strictly needed.

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

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

For a 6-parameter load tool with no output schema, the description covers the workflow entry point, multi-file/pagination escape hatches, the security-gate filtering, and the temporary non-installing nature of loading. 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 description coverage is 100%, so the schema already documents every parameter including the file/request_id relationship and page. The description restates the file+request_id and page usage rather than adding new syntax or constraints, matching the baseline for a fully documented 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 ('Load') and resource ('a selected skill returned by find_skill'), and explicitly ties itself to the sibling that produces the input. An agent can distinguish use_skill from find_skill/scan_skill/rate_skill 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?

Makes the workflow explicit: load a skill that find_skill returned, and gives follow-on conditions for oversized results ('pass file and the original request_id', 'pass page for more content'). It never states when not to use it or names explicit alternatives, so it stops 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.