LexLint: compliance lint for AI, scraping, and privacy law

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

Beyond readOnlyHint/openWorldHint=false, it discloses cost semantics ('costs one upstream request, always'), that the jurisdictions preview rides the same request and is free, and a privacy guarantee ('Nothing about your model is sent here and no argument carries one'). It also enumerates the returned advisory fields (tested_model_families, model_notice), which annotations cannot express.

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 'Preflight.' and ordered by importance, but repeats the single-request cost point twice ('Costs one upstream request, always' and 'rides this same request rather than spending a second one', then again in the jurisdictions property). A modest trim would earn a 5.

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 compensates by enumerating what is returned (key status, allowance and reset, library currency, plugin currency, tested_model_families, model_notice) and the null-means-unknown caveat. An agent has enough to call it correctly 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, but the description adds real decision-relevant meaning: the optional jurisdictions preview does not increase cost, and omitting client_version makes update_available null — explicitly not a currency signal. It stops short of restating formats for jurisdictions slugs, which the schema 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 names a specific verb and resource — reporting key reachability/validity, allowance remaining and reset time, law library freshness, and plugin currency — and explicitly positions itself against siblings with 'Call this first'. An agent can distinguish it from get_law, run_lint, and claim_trial_key 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?

It gives an explicit ordering instruction ('Call this first') plus the concrete failure mode avoided ('a missing key otherwise surfaces several steps later as a rejected tool call'). That is a when-to-use rule with a stated consequence, which is more than most siblings likely need.

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 non-idempotent and non-read-only, and the description goes well beyond them: explicit rate limit (five per day per address), refusal conditions (session already holds a key or a sign-in), the side effect of exposing the key in the transcript, and the quota burn per call. This is exactly the kind of 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?

Dense but front-loaded: purpose first, then precondition, then side effects, then post-call instructions. Every sentence carries operational weight, though the single unbroken paragraph could be split to make the refusal/rate-limit conditions scannable.

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 tells the agent where the key lands (in this result / this session's transcript), what to do with it (persist as UNGOVR_API_KEY, start a new session), and what blocks a successful call. Nothing needed to invoke 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?

Only one optional parameter (client_version) and the schema already documents it at 100% coverage, including its stale-install rationale. The description adds no further meaning about the parameter, so the baseline 3 applies.

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

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

States a specific verb and resource (mints a 30-day UnGovr Open Data trial key), plus the exact scope: no account, 50 requests, 10 jurisdictions, whole-life limits. It also names the sibling (check_access) that surfaces the alternative route, so the agent can distinguish this tool from the rest of the set.

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 precondition: 'Run it ONLY after the developer chose the no-account route over signing in', with a pointer to where the choice is presented (check_access setup.steps). That is a when-to-use, a when-not-to-use, and the alternative route all in one.

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 readOnlyHint and openWorldHint; the description adds substantial behavioral context: resolution walks up to the nearest jurisdiction with data, jurisdiction names the parent actually read while resolved_from names the requested slug, and it discloses rate limits (25 lookups/day anonymous, metered with key, trial key capped at 10 distinct jurisdictions shared with run_lint). It also flags the payload as data-not-instructions, which is meaningful safety context 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 core facts (single payload, nine topics, resolution fallback, quota) are front-loaded, but the nine-topic enumeration and the embedded disclaimer/prompt-injection note make this a single dense paragraph that is hard to scan. The topic list arguably earns its place to justify the 'one call' claim, but the passage could be tightened considerably.

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 return-value burden and does so thoroughly: instruments with citations, status, behavior categories and as_of_date, plus verdict-level crawl policy, per-scenario access matrix, robots.txt legal weight and TDM opt-out status. An agent needs nothing further to decide whether to call it or how to read 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?

With a single parameter at 100% schema coverage, the baseline is 3, but the description adds real meaning: the jurisdiction slug is resolved by walking up the hierarchy, and the response distinguishes the parent that answered from the slug that was asked for. That resolution behavior is not expressible in the schema and directly shapes how an agent interprets the call.

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 ('One jurisdiction's law from the LexLint law library') and enumerates the nine topics the single payload covers, so an agent knows exactly what it gets back. It also distinguishes itself from the natural misuse pattern ('do not call this nine times for one jurisdiction'), which separates it from run_lint and check_access in practice.

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 use context ('ONE call answers an AI question, a scraping question...') and an exclusion ('do not call this nine times'), plus quota behavior shared with run_lint. It does not explicitly route between resolve_domain_jurisdiction, check_access and this tool, so the when-not guidance is not fully complete.

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

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

Annotations cover read-only and closed-world status, but the description adds substantial context: upstream request cost (1-4 with free TLD fallback), unauthenticated rate limit (25 lookups/day), metered auth options, and refusal of IP addresses / server-edge locations. This is far beyond what the annotations provide.

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

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

The purpose is front-loaded and every sentence carries useful information about scope, cost, or access limits. However, it is lengthier than needed for a one-parameter tool, with some dense clauses that could be tightened.

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

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

Given a 1-parameter tool with full schema coverage, read-only annotation, and no output schema, the description supplies all the decision-relevant context: purpose, alternatives, cost, rate limits, and auth. Nothing essential for correct invocation 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% and the single parameter is fully documented with hostname/URL format and IP rejection. The description repeats the IP refusal but adds no new syntax or constraint, so it does not go 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: best-effort mapping from a domain to the jurisdiction governing its operator, for feeding into other tools. It differentiates from siblings by noting it derives a jurisdiction rather than declaring one and that it sits outside a lint's five-request total (check_access, set_profile, run_lint).

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?

Explicitly says to call this tool only to derive a jurisdiction from a domain rather than declaring one, and frames it as an alternative to declaring a jurisdiction. It also discloses it is not part of a lint's request budget, which clarifies when not to fold it into another flow.

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

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

With annotations already declaring readOnlyHint=true and openWorldHint=false, the description adds substantial context beyond them: severity semantics, kind values, certainty.resultset versus certainty.rung, coverage behavior as a warning rather than silent pass, caching behavior, request costs, trial limits, and authentication requirements. It also discloses important behavioral constraints like 'LexLint never reports error' and that omitted forward findings must be disclosed to avoid a silent pass.

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 opening sentence is well front-loaded and identifies the tool's role in the workflow, but the description then becomes a dense wall of long sentences with parenthetical asides and repeated concepts around kind, certainty, and forward findings. The information is mostly useful and earns its place, but it could be structured more crisply and shortened without losing meaning.

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

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

For a read-only lint tool with an output schema, this description is very complete: it explains what findings contain, how severity and certainty should be interpreted, what coverage warnings mean, authentication and metering requirements, and the legal-advice limitation. An agent has enough context to call it correctly, interpret the findings, and avoid misusing forward-looking results.

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

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

Schema description coverage is 100%, so the schema already carries the detailed meaning of activities, jurisdictions, roles, public_sector, regulated_sector, brief, and client_version. The description reinforces that activities and jurisdictions come from set_profile and that declared jurisdictions should be complete, but it does not add much parameter semantics beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description immediately states this is 'Step 2 of the lint, and the one that returns findings,' and explains that it returns lint-style findings with obligations, severity, citation, and confidence. It also distinguishes itself from get_law by saying no topic is served by get_law alone and that full law text is one get_law call away.

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 establishes the workflow context clearly: pass the activities and jurisdictions set_profile validated, use brief when presenting results to a person, and leave brief out when writing lexlint.yml. It also gives important use boundaries such as 'NOT legal advice and NOT a compliance certification' and that forward findings must never gate a build or merge. It does not explicitly name a competing findings tool or spell out when not to call run_lint, so it falls 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 only cover readOnlyHint and openWorldHint. The description adds substantial behavior beyond them: nothing is stored server-side, invalid activities/slugs are refused upfront, one upstream request covers any number of jurisdictions, and it requires sign-in or a metered UnGovr key with a URL to obtain one. Costs, failure mode, persistence, and auth are all disclosed.

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, workflow position, and outputs, then constraints and auth. It is on the long side and the check_access-redundancy point is stretched across two clauses ('so asking both is redundant, never costlier: they just repeat the same answer'), which is mild padding rather than waste.

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

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

For a 5-parameter tool with nested objects and no output schema, the description explains what comes back (validated canonical profile plus per-jurisdiction law holdings), how to persist and forward it, the cost model, and the auth requirement. Nothing needed to invoke 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% and the schema itself carries the detailed enum lists and per-parameter explanations (roles, public_sector, regulated_sector, jurisdiction slug format). The description restates only activities and jurisdiction slugs at a high level, adding little beyond the schema, so the baseline of 3 applies.

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

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

The description gives a specific verb and resource — declare activities and jurisdictions, receive a validated canonical profile plus the law-library coverage — and frames it as 'Step 1 of the lint'. It explicitly names the siblings it relates to (run_lint, check_access), so an agent can place it in the workflow without opening another 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 states the downstream action ('Write the returned profile into the project's lexlint.yml and pass it to run_lint') and handles the obvious alternative directly: check_access's jurisdictions preview answers the same coverage question, so 'asking both is redundant, never costlier'. That is explicit when-to-use and when-not-to-use 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?

Beyond the annotations, the description discloses the external side effect (sending data to the LexLint team), the account linkage, the sign-in or UnGovr Open Data key requirement, and the one-submission limit. It also flags the serious privacy risk of building the usage summary from the session transcript because a pasted key would be transmitted.

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

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

The purpose is front-loaded, followed by the safety and approval constraints. Despite the length, every sentence carries operational weight: approval gating, the single unprompted context, the headless prohibition, the transcript warning, and the one-per-session limit.

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

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

For an external-side-effect mutation tool with no output schema, the description covers purpose, authorization requirements, privacy hazards, approval workflow, and rate limiting. An agent has everything needed to decide whether to invoke it and how to construct the payload safely.

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 parameter meanings are already documented. The description still adds meaningful semantics by constraining how usage_summary must be produced, especially the warning not to read the session transcript, and by requiring the exact payload to be printed and sent only if approved unchanged.

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

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

The first sentence states a specific verb, resource, and recipient: sending developer feedback on LexLint to its builders, recorded against their UnGovr account. This is unmistakably distinct from siblings such as run_lint, upload_lint_run, and set_profile, so no schema opening is needed to identify the tool.

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

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

The description gives explicit when-to-use and when-not-to-use rules: only on the developer's explicit yes, unprompted in exactly one place, never elsewhere, and never in headless or CI sessions. It also specifies the approval workflow and the one-submission-per-session limit, 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 cover only safety hints, and the description supplies everything an agent actually needs: auth requirement (sign-in or UnGovr Open Data key), immutability plus new-revision-on-change semantics, server-side rebuild and refusal conditions (law library moved, stale approval, triage id not in this run), and an explicit exclusion list of what is never stored. That is far beyond what readOnlyHint/destructiveHint/idempotentHint 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 purpose, then approval, then forms, then guarantees — a sensible ordering with no filler paragraphs. It is on the long side and a few clauses are self-referentially dense ('raised unprompted in exactly one place, the close of that run, and never volunteered anywhere else'), which is prompting policy more than tool contract, but the density mostly buys real information.

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

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

For a 15-parameter, nested-object, no-output-schema mutation tool, everything an agent must know is present: the two calling forms, required data per form, auth, approval gate, return values (URLs, trial share expiry), and the immutability/refusal model. Nothing needed to call it correctly is left to inference.

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 the schema cannot: it splits the 15 parameters into two mutually exclusive forms, names which fields each form requires (app_name, activities, jurisdictions, corpus_built_at, run_at for compact; a complete ungovr.lexlint-upload/1 record for full), and explains the triage fields' refusal rule. It does not fully disambiguate which parameters are ignored in which form (e.g. payload alongside compact fields), which keeps it off 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 ('Store one lint run on the LexLint portal'), the account it lands under, and what comes back (portal URL, plus a 30-day share URL for trial keys). It also positions the tool in the lifecycle ('the closing step of every run that produced findings'), which separates it from run_lint and submit_feedback among the 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 when-to-use (close of a run with findings, after developer approval), explicit when-not (never in a headless or CI session where nobody can approve), and explicit fallback behavior when the client asks nothing (the agent asks once itself). It also routes between the two calling modes and says to prefer the compact form.

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