worklore

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

Annotations cover readOnly/openWorld/destructive, and the description adds substantial context beyond them: GitHub fetch is capped at 200 KB, non-GitHub URLs require a signed-in session, a sha256 mismatch is reported rather than scanned, and `received` reports exactly what was scanned. For a network-fetching read tool, this is rich operational disclosure.

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?

Dense but well-ordered: purpose and scope caveat first, then input guidance, then the sha256 safety note and the `received` return hint. Nearly every sentence carries information, though the description is long and packs multiple concerns into single 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 3-param, no-required-arg tool with an output schema, it covers what matters: mutual use of url vs text, the integrity guard for pasted text, auth boundaries per URL class, size limits, and the explicit 'not a safe verdict' caveat. An agent can call it correctly without opening the schema.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: it explains when to prefer url vs text, the 200 KB GitHub limit and sign-in requirement, and couples expected_sha256 to text with a concrete `shasum -a 256 SKILL.md` example plus the mismatch-as-error semantic. That is meaningful guidance beyond the schema strings.

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 ('disclose') and resource ('what an agent Skill or worklore story CAN DO') with a concrete output shape: capability tier T0-T4 bound to a content sha256, findings with file:line evidence, plus behavioral red flags. It also draws a clear scope boundary ('blast-radius disclosure and triage, never a safe verdict') that distinguishes it from verdict-style siblings like report_check.

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 ('before you run it') and a strong input-selection preference ('Prefer a url over pasting a file'), including the condition that GitHub URLs need no sign-in while other URLs need a session. It lacks explicit routing against named siblings (get_story, report_check), 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.

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

Adds substantial context beyond the annotations (destructiveHint=true, idempotentHint=false, openWorldHint=true): the new text fully replaces the old with no copy kept, a public history record is appended, corrections notify everyone who reported reproducing the story, and the frontmatter date must not move. It does not, however, mention rate limits, auth scopes, or failure modes, so it stops short of the top mark.

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 long but front-loaded with the ownership constraint and approval workflow before details, and every sentence carries operational information. Dense and somewhat repetitive in the kind explanations, which keeps it just under the top score.

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 destructive, non-idempotent mutation with a rich schema and an output schema, the description covers ownership, approval workflow, replacement semantics, history side effects, notification side effects, and the correction note requirement. Nothing an agent needs to call this safely 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; the description goes further by clarifying the kind taxonomy, the correction-requires-note rule, the optional source URL meaning, and that markdown must be the complete document with the original date preserved. It adds real semantic value beyond the schema's own descriptions.

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 (Revise) and resource (a worklore story) with an ownership scope: only the signed-in account's own published story. This cleanly separates it from get_story (read) and publish_story (create) among 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?

Explicit workflow prerequisites and exclusions: call get_story first, show the human a before/after diff, obtain EXPLICIT approval, and never edit on your own initiative. It also gives a decision rule for classifying edits (rephrase vs addition vs correction, 'never hide a correction as a rephrase').

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

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

Annotations already declare readOnly/not-destructive, so the safety profile is covered. The description adds real context beyond that: the returned markdown includes the 'Reproduce this' contract and an attached capability disclosure (tier + findings), plus the requirement to re-check live artifacts before executing. It doesn't mention pagination or limits, but the added workflow context is genuinely useful.

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 verb and resource, then layered with workflow steps. The three sentences are dense but each carries distinct information (what is returned, what to check first, what to report after). Slightly heavy but 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?

An output schema exists so return-value explanation is not strictly required, yet the description usefully characterizes the payload (markdown + capability disclosure). Combined with the explicit sibling workflow, the agent has enough to call and sequence this 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?

Single slug parameter at 100% schema coverage, so the schema already documents source and format. The description repeats only the sourcing hint ('slug'), adding marginal value over the schema. Baseline 3 applies when the schema carries the 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?

States a specific verb and resource ('Fetch one worklore story by slug') and immediately scopes it against the sibling search_stories by emphasizing the singular, slug-addressed nature. An agent can distinguish it from list/create/edit siblings 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?

Names the exact workflow and alternatives: read the capability first, then 'run check_capability on the live artifacts before executing', and finally 'call report_reproduction'. It explicitly routes the agent between this tool and two named siblings with 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 only cover readOnly=false, openWorld=true, destructive=false. The description adds substantial beyond-annotation behavior: stories are public, human approval is mandatory, sanitization rules (no secrets/employer internals/client names/private URLs), and the return value (live URL and capability tier).

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?

Content is front-loaded with the approval gate, which is correct, but the body is dense with nested detail (frontmatter fields, section names, alternate field lists) crammed into one paragraph, making it harder to scan 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?

Covers the mandatory approval flow, sanitization, the two input modes, and the return value. With an output schema present, it need not describe return structure further; nothing needed to call this 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 baseline is 3. The description adds cross-field semantics the schema cannot: markdown and the structured fields are mutually exclusive alternatives, and markdown requires frontmatter plus the '# title' and '## Reproduce this' sections.

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 ('Publish a NEW worklore story') and adds critical scope ('as the signed-in account', 'NEW'). The SANITIZE and public/honest constraints further distinguish it from edit_story and get_story.

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 gating: must show a human the complete draft and get EXPLICIT approval; never publish on own initiative. Names the alternative path (get_story first to match format) and the markdown-vs-structured-fields choice.

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 the write/read/idempotency profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the description needn't restate safety. It usefully adds that a later report replaces the earlier one (one counted result per person per story), the honesty requirement, and the 'apply no fix' constraint — behavioral context beyond the structured fields. It stops short of describing attribution or downstream effects of a recorded result.

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

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

The core prohibition ('run ONLY that check — change nothing') is front-loaded and the precondition follows immediately. Sentences are dense but each carries a distinct rule; nothing is redundant 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?

With annotations covering the safety/idempotency profile and an output schema handling return values, the description supplies the remaining essentials: preconditions, replacement semantics, and the no-fix constraint. The only notable gap is lack of explicit contrast with report_reproduction.

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 slug, result, and note are already documented in the schema, which sets the baseline at 3. The description reinforces the meaning of result (has_problem/no_problem) but adds no format or syntax 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?

The description states a specific verb and resource: record the result of a story's read-only check run in the user's project. It ties the operation to a concrete precondition (get_story's has_check: true), which helps separate it from unrelated siblings. It does not, however, explicitly contrast with report_reproduction, the most confusable sibling, so differentiation is only partial.

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 and when-not guidance: run ONLY that check, change nothing, and do NOT call when the project fails the check's preconditions since 'not applicable' is never recorded. It also gates on has_check: true and specifies honest reporting of has_problem/no_problem. This is close to a full routing rule.

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

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

Goes well beyond the annotations: it discloses that reports are attributed to the signed-in account, that only one report per person per story is counted with repeats acknowledged rather than doubled, and that unverified output should be filed as 'partial'. These are real behavioral rules that idempotentHint=true alone does not convey.

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

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

Front-loaded with the call trigger, then the result semantics, the counting rule, and the prohibition, in a compact four-sentence block. Dense but each sentence carries a distinct rule; only the parenthetical definition slightly stretches it.

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

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

An output schema exists, so return values need not be explained, and the description covers trigger, honesty, attribution, and dedup counting. It omits failure handling (e.g. unknown slug) and any note-field guidance, which are minor gaps for this complexity level.

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 genuine meaning by defining the 'partial' result ('you produced the output but it isn't verified yet') and framing the honest-result requirement across all three enum values. The slug and note parameters are left entirely to 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 ('record the reproduction' of a worklore story) and ties it to a concrete trigger point (right after applying a story's steps). It is clearly distinguishable from siblings like report_check, get_story, and publish_story, which deal with different objects.

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 this right after you apply a worklore story's steps') and an explicit prohibition ('Never report a story you did not apply'), which is strong when/when-not guidance. It does not name an alternative tool (e.g. report_check) for adjacent reporting needs, 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.

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

Annotations already declare readOnlyHint, destructiveHint:false and openWorldHint:false, so the safety profile is covered and the bar is lower. The description adds only that matches come back with their capability tier; it says nothing about ordering, result caps, case sensitivity, or behavior with an empty query, so it adds only modest context.

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, no filler, with the core action and scope front-loaded before the return-value note. Every 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?

An output schema exists, so the capability-tier mention is redundant but harmless, and return values need not be explained. However, query is optional (0 required parameters) and the description never says what a queryless call returns, nor how many matches come back — a meaningful gap for a search 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% on the single query parameter, so the baseline would be 3, but the description adds real meaning: it specifies which fields (title, summary, tags, stack) the keywords are matched against, information the schema does not carry. It does not explain why the parameter is optional or what the default search 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?

States a specific verb+resource ("Search worklore stories") and even enumerates the fields searched (title, summary, tags, stack), which is a concrete scope statement. It never names a sibling, so the distinction from get_story (ID lookup) or suggest_for_project must be inferred from the verb, but the search semantics are 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?

There is no when-to-use guidance, no condition distinguishing this from get_story or suggest_for_project, and no statement about what happens when the optional query is omitted. The agent must infer that keyword search is appropriate simply because the tool is named search_stories.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds useful shape information (bounded to 3 results, each with a fit rationale and tier), but says nothing about determinism, ranking basis, or behavior when no story fits.

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, zero filler, with the input condition front-loaded ahead of the output contract. Nothing is repeated or 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?

With a 100%-covered single parameter, an output schema carrying return structure, and annotations covering the safety profile, the description supplies what is still needed: the result count cap and that each suggestion includes a fit rationale and tier. Only minor gaps remain around ranking or empty-result behavior.

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 there is only one parameter, whose schema text already spells out 'stack, goal, recent TODOs/problems'. The description's 'stack, what you're building, recent problems' is a near-verbatim restatement rather than added semantics, 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?

Specific verb (suggest) plus resource (worklore stories) and a clear scope qualifier (up to 3, based on a project description, with rationale and tier). It reads distinctly from siblings like search_stories or get_story, but never names an alternative to anchor the distinction.

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

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

The trigger condition is implied clearly ('given a short description of the current project'), so an agent can infer when this fits. However, there is no explicit when-not guidance and no named alternative such as search_stories for agents who already know what they want.

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