Avokata: Lithuanian law & court practice

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

Annotations already declare readOnlyHint/idempotentHint/non-destructive, and the description reinforces this with 'Changes nothing' while adding context the annotations cannot convey: the sign-in prerequisite, the free beta state, and that session must be passed on every call. It stops short of explaining return shape or the beta's end behavior, but it clears the bar raised by the annotations.

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

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

Three tight sentences with the blocker (sign-in required) front-loaded, followed by what is read and where to go for mutations. The alternative-tool routing is repeated in the schema, so there is minor redundancy, but nothing is wasted.

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

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

For a read-only tool with no output schema, the description tells the agent what data comes back (status, plan and limits, keys by prefix) and the auth precondition, which is sufficient to invoke correctly. It could say more about what 'keys by prefix' actually returns, but nothing essential 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 all four parameters, establishing a baseline of 3. The description only reinforces two points (action='keys' and that tier is unnecessary during the beta), adding marginal meaning beyond the schema rather than new syntax or constraints.

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

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

States a specific verb and resource ('Read the signed-in account') and enumerates the returned content: status, plan with limits, and keys when action='keys'. It also names the sibling tools that handle the mutating paths (revoke_api_key, request_deletion), so the agent can distinguish read vs. write 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?

Gives an explicit prerequisite ('call connect(email) and connect_verify first... unless this connection is already signed in') and routes mutation intents to revoke_api_key and request_deletion. It does not address the overlap with the sibling whoami, which plausibly also reveals the signed-in identity, leaving one alternative ambiguous.

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 destructiveHint=false, so the safety profile is covered. The description adds genuinely new context: the free one-email sign-in prerequisite and the distinction that validity is a property of the act, not an article. It does less on return format, though the acts schema entry hints at the compact-row output.

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 sign-in requirement, then states the purpose, then routes to alternatives, then gives an example. Dense and purposeful, though it runs long; every sentence is doing work but the routing 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?

With 6 params, no output schema, and only read-only annotations, the description covers auth, act identification, date semantics, and exclusion from sibling tools. It does not explain the return value of a single-act query, but the essential call-correctness information is present.

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

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

Schema description coverage is 100%, so parameters are fully documented already, and the description largely restates the document_id/act_number duality. It does add one constraint not obvious from the schema: name the act with ONE of document_id or act_number, and that an article id with `#` answers about its act. Baseline 3 is appropriate since the schema carries most of 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 query: whether an act is in force and which consolidated version governed on a date, with the native terms (galioja, suvestinė redakcija, įsigaliojimo data). It explicitly separates itself from read_paragraphs (article wording), compare_provision_versions (what changed), and verify_citation (quotation verification).

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 routing: sign in via connect/connect_verify first; use search_law when only the title is known; use read_paragraphs for an article's wording on a date; verify_citation to verify quotes. Names the alternative tools and the conditions that select them, plus a concrete example call.

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/idempotent/non-destructive, so the safety profile is covered; the description adds genuinely new behavior: the authentication flow, the epistemic caveat that it lists citations but not whether a source was followed or distinguished, and the warning that results are a slice controlled by `provisions_total`. It does not spell out the full response envelope (data_as_of, notes, truncated handling beyond max_chars), 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?

Front-loads the mandatory sign-in step, then purpose, directionality, caveat and result-slice warning in a logical order; every sentence carries operational weight. Minor redundancy: the `provisions_total` caution and the slice caveat are repeated in both the description and the `limit`/`document_id` schema text.

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

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

For a six-parameter tool with no output schema, the description covers the auth prerequisite, what an edge contains (pinpoint, court, date, citing sentence), the partiality signal (`provisions_total`), the compact/full quote tradeoff, and the interpretive limit. An agent has enough to call it correctly and to read the result without guessing.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds selection guidance the schema only implies — pass the search hit `id`, an article id with `#` scopes to that article versus a whole document, and there is no separate `pinpoint` parameter — plus a concrete example argument object. It still mostly restates what the schema already documents for `document_id` and `limit`.

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 one document or article relies on... the acts and earlier rulings it cites, each with its pinpoint, court and date and the citing sentence'), and explicitly names the sibling it is not: 'for the reverse direction ... use cited_by'. An agent can distinguish it from cited_by and read_paragraphs 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?

Gives explicit when-to-use ('to follow a ruling's reasoning back to its sources'), the named alternative for the opposite direction (cited_by), and the follow-up needed to judge agreement (read_paragraphs). It also states the sign-in prerequisite and sequence (connect, then connect_verify) up front.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), and the description adds genuinely new behavioral context: the sign-in flow and free/one-email constraint, the `later_than` temporal semantics, and the crucial caveat 'These are citations, not endorsements: whether the citing court agreed is not recorded' — a limitation an agent would otherwise misinfer. It also notes cassation-admission decisions are excluded by default.

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 auth prerequisite, then the purpose, then the three naming modes, then the caveat, then the example — a sensible order. It is dense and the sign-in sentence is long, but no sentence is filler; slight deduction for density over brevity.

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 11-parameter, output-schema-less tool with an auth gate, the description covers everything an agent needs to call it correctly: auth, subject forms, temporal direction, exclusion of admission decisions, and the distinction from the sibling. Return shape is largely delegated to the rich per-parameter schema, which is appropriate.

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 a 3 is the baseline, but the description earns above that by explaining the mutual-exclusivity rule across document_id / case_no / act_number+pinpoint and by supplying a worked example. It adds selection logic the schema documents individually but not as a coherent decision.

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 operation on a specific resource — 'what has cited this provision (straipsnis) or ruling (nutartis)' — and frames it as 'a reverse lookup that full-text search cannot do.' It also names the sibling it is not: citations_of, which handles outgoing citations. An agent can distinguish cited_by from citations_of 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?

Explicitly routes: use citations_of 'for citations this document itself makes,' and it enumerates the three accepted ways to identify the subject (case_no, act_number+pinpoint, document_id), warns 'A citation string is not a parameter: split it into those parts,' and gives a concrete example argument set. Prerequisites (connect/connect_verify) are stated up front with the exception when already signed in.

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/idempotent/non-destructive, and the description still adds substantive behavior: authentication requirements, what is returned (version metadata and register links), and a fidelity guarantee that missing wording is reported as not held and never reconstructed from register notes. That is exactly the kind of context 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?

The auth prerequisite is front-loaded and the rest reads as a dense but purposeful paragraph with no filler. Slightly long and packed with parentheticals, but 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?

For a 9-parameter read tool with no output schema, the description covers auth, the two answer modes, and the return shape ('version metadata and register links'). It stops short of describing pagination or limits on the shortened redlines, but nothing essential to a correct call 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 schema already documents defaults, formats, list caps, and cross-parameter interactions, so the description's parameter content largely restates it (from_date as baseline, `article` behavior). Baseline 3 is appropriate since the schema already 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 operation ('what changed in an act (or one article) between two dates') with an explicit baseline/end semantic: the version in force on from_date vs the one on to_date plus in-between changes. This clearly separates it from siblings like get_document, check_validity, or read_paragraphs.

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

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

Gives a clear prerequisite (call connect/connect_verify first unless already signed in) and explains the two usage modes: with `article` for wording plus redline, without `article` for the full changed-article list, and the `amended_by` 'what does this amendment change' case. It does not name sibling alternatives, but the branching guidance is concrete.

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/openWorld/idempotent, so the description adds real value by disclosing the external side effect: exactly one email goes out containing a Confirm link and code, sign-in is free, and connect_verify blocks waiting for the click. It does not say what happens on resend/expiry or whether calling twice sends two emails, despite idempotentHint=false.

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

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

Front-loads the action and the prerequisite in the first two clauses, then the call to action; almost no wasted words. The parenthetical '(shared 0.61.0)' is an opaque version tag that costs a clause without helping an agent decide or call.

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 conveys the essential return value by referencing connect_verify(request_id), so the agent knows a request_id comes back and what to do with it. Missing are error/expiry handling and whether re-invocation is safe, which matter given idempotentHint=false.

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

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

Schema coverage is 100% and the schema's own property descriptions already explain email, language tags with fallback to English, and that 'firm' is never worth asking for. The description restates email and language but adds nothing about the parameters beyond the schema, so the baseline 3 applies.

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

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

States a specific action (sign in with the user's email), names the auth mechanism (no password, emailed Confirm link plus six-digit code), and explicitly separates itself from connect_verify by describing that tool as the follow-up step. An agent can tell it apart from whoami/describe/connect_verify 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 a concrete gating rule — 'Required for every tool except whoami and describe' — and names the required next call (connect_verify(request_id)) with the timing cue 'right away'. It stops short of saying what to do when the user is already signed in (e.g. check whoami first, do not re-call), which is the last piece needed for 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 declare non-readOnly, non-destructive, non-idempotent, but the description adds the crucial operational facts: a human must tick the acknowledgement themselves and the agent must never accept on their behalf, plus the do-not-retry rule for the acknowledgement state. These are behavioral constraints no annotation could convey and are the highest-value content 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 primary action and the human-in-the-loop rule, and nearly every sentence carries an instruction. It is dense — several distinct rules are compressed into single sentences and the api_key mode arrives as an appended clause — but there is little outright 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 five-parameter, zero-required, no-output-schema tool, the description covers both entry paths, the waiting/polling semantics, the terminal error state, and the one-time nature of an issued key. An agent has enough to call it correctly without guessing.

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 the inter-parameter relationship the schema does not state — request_id paired with no code versus a code the user read out, and api_key as an alternative entry path. The session parameter is left to the schema, which is acceptable given full coverage.

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 action ('Finish signing in') and ties it directly to the sibling it follows ('after connect(email)'). It also delineates a second mode ('Also takes a key the user already holds (api_key)'), so an agent can tell this apart from connect and the other auth-adjacent siblings.

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

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

It gives explicit routing and call shapes: call with request_id and no code to wait for the Confirm click, or with the six-digit code if the user reads it aloud, or with an existing api_key. It also states a clear negative condition — a terms_acknowledgement_required state requires human action and must not be retried — which is exactly the kind of when-not guidance that prevents loops.

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

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

Annotations already establish read-only, idempotent, non-destructive and closed-world, so the safety bar is low. The description adds real behavioral context beyond them: which corpus areas are thin, that omitting `section` returns an overview while a section returns one block whole, and that sign-in/limits live elsewhere. It stops short of describing response shape or size, hence 4 rather than 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 purpose and routes to alternatives efficiently, with zero filler sentences. The opening sentence is a long enumerated clause that packs many items at once, which costs some readability but no wasted words.

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

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

For a two-parameter, no-output-schema read tool, the description covers purpose, trigger, non-uses, section behavior and an example call. It leaves the actual returned block structure unspecified, which matters somewhat given there is no output schema, but the section enumeration largely compensates.

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 `section` field already enumerates scope/register/coverage/currency/eu with definitions, so the description largely restates that. The only added meaning is the example argument and the framing of a section being returned "whole"; baseline 3 applies 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 resource (the corpus: sources, dates, per-area coverage, court hierarchy, case-number formats) and explicitly delimits itself from search_law, search_practice and whoami, so an agent can separate it from those siblings without reading 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 a concrete trigger ("Call it before telling a user that nothing exists on a topic") plus explicit when-not guidance: it does not search, and act-level existence questions belong to search_law/search_practice, while sign-in and limits belong to whoami. Alternatives are named with the conditions that select them.

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

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

Beyond the readOnly/non-destructive annotations, it discloses the authentication flow, return behavior (best matches with reasons, or no match and guidance), ordering of user vs shipped workflows, and that shipped plans are unvalidated builder drafts. It also states the tool is cheap, runs no search, and makes no decision for the user.

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 dense and mostly functional, but it is not front-loaded on purpose: it opens with authentication before stating what the tool does. The example arguments and some schema-adjacent details make it longer than necessary, though most sentences earn their place.

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

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

For a read-only workflow finder with no output schema, the description is complete: it covers authentication, intended use, alternatives, return expectations, limitations, and example arguments. An agent has enough information to select and 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 description coverage is 100%, so the schema already documents task, limit, and session. The description adds an example call and language guidance, but much of that repeats the schema, so the baseline 3 is appropriate.

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

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

The description states a specific verb and resource: find a proposed workflow/method for multi-step legal work. It gives concrete use cases (checking whether a ruling still holds, memo with sources, deadlines) and clearly distinguishes this tool from get_workflow, list_workflows, and workflow_guide.

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 covers when to use this tool, when to use alternatives, and the sign-in prerequisite. It also clarifies that a single lookup needs no setup, browsing uses list_workflows, opening uses get_workflow, and writing uses workflow_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/idempotentHint, so the bar is lower, yet the description adds substantive context beyond them: sign-in prerequisites, the size cutoff that motivates calling this first, and the important limit that Avokata holds no ECHR text, directing the agent to text_availability.where instead.

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 auth prerequisite, then the core purpose and scope limits. Dense but nearly every clause carries information; the sign-in sentence is long but justified for a gated 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?

With no output schema, the description still conveys the return shape: identity plus contents, chapter-wise listing for long acts, and that answers state true totals and next offsets. Combined with the ECHR fallback pointer, an agent has enough to call and interpret it correctly.

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

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

Schema coverage is 100%, so baseline is 3; the description adds real value on top by clarifying that ids come from search results and that document_id is NOT document.number (the official act number), a distinction the schema leaves implicit. Pagination and part semantics are left largely 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+resource: returns a document's identity and its table of contents (turinys), explicitly WITHOUT the text. That negative scope cleanly separates it from text-reading siblings like read_source_text or read_paragraphs without needing to name them.

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

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

Gives explicit sequencing ('Call this before reading') plus a concrete trigger (Civil Code at 1.7M characters) and prerequisite auth steps (connect/connect_verify). It does not name the sibling to call next, but the when-to-use condition is unambiguous.

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 read-only, idempotent, non-destructive, closed-world behavior, but the description adds material context beyond them: the sign-in dependency, that no step is executed or verified, the 2,000-character advisory size target with 'safeguards are never cut', and the conditional full-read requirement. Size reporting and the advisory-vs-hard limit distinction are exactly the kind of behavior an agent cannot infer from annotations.

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

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

Dense but front-loaded: the sign-in gate opens, the plan contents and execution boundary follow, then id sourcing and detail semantics. Minor waste remains in restating the 2,000-character/advisory/safeguards rule, which already appears verbatim in the `detail` schema description.

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 it well: it describes the plan's contents (calls, slots, principles, expected result) and size reporting. For a 4-parameter, annotation-rich tool, 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 baseline is 3, but the description adds real meaning: it clarifies that `task` binds only slots and 'does not replace that id', that a bare workflow_id is a playbook while jobs use `job-<id>`, and it supplies a worked example of arguments. This clarifies the relationship between the two most confusable parameters rather than restating 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 ('Open one workflow as a PLAN bound to the task') and enumerates what the plan contains: ordered tool calls with filled slots, principles, and expected result. It is unmistakable against siblings, since it explicitly routes to find_workflow/list_workflows for the id and to workflow_guide for authoring a new workflow.

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 prerequisites ('call connect(email) and connect_verify first ... unless this connection is already signed in'), the exact source of workflow_id, when to use detail='full', and the alternative tool for writing workflows. It also states a negative boundary: 'this tool runs no step and checks no result', i.e. the agent executes the plan itself.

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 readOnly/idempotent annotations, it discloses the auth prerequisite (connect + connect_verify), the partiality of the corpus (rulings not held are silently absent) and the deliberate refusal to infer finality (`unknown`). It does not describe error behavior or what happens on a bad case_no, but the important behavioral caveats are covered.

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 auth requirement, then the resource, then usage, then caveats, which is the right order for an agent. The sentences are dense but each carries distinct information; the one waste is the parenthetical Lithuanian court names, which only lightly aid selection.

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 explains the shape of the answer adequately (grouped by proceeding number, date-ordered, court level, `unknown` finality). What remains unstated is whether an empty or absent chain is reported as an error versus an empty 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 baseline is 3; the description adds the decision rule for case_no vs proceeding_no and a worked example of arguments, which the schema alone does not spell out. The session and jurisdiction 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 concrete verb+resource: the held rulings of one matter from first instance through appeal to cassation, grouped by proceeding number and ordered by date with court level. It also concretely excludes cross-case citations by naming cited_by and citations_of as the tools for that job, so an agent can route without opening 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?

Gives explicit use cases (what later happened to a judgment; which lower decisions a cassation ruling reviewed) and explicit selection rules between the two entry parameters (case_no when you have a judgment, proceeding_no when you have the register number). It also names the alternative tools for a different question type.

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 readOnly/idempotent annotations, the description discloses sign-in prerequisites, result ordering, pagination via next_cursor, exact totals and issuer counts, and edge-case behavior for windows beyond the feed. The incomplete/total_at_least/coverage_through explanation is especially valuable behavioral 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?

The description is front-loaded with the sign-in requirement and then the core purpose, and every sentence contributes useful information. It is somewhat dense and occasionally repeats parameter details already in the schema, which keeps it from a perfect 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 complex, authenticated, paginated listing tool with no output schema, the description covers prerequisites, pagination, totals, ordering, and unusual coverage-edge responses well. It does not describe the individual act record fields, leaving a minor completeness gap for return-value expectations.

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

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

Schema description coverage is 100%, so all seven parameters are already documented structurally. The description reinforces date-window and issuer semantics with examples, but it adds little parameter meaning beyond the schema's own descriptions, making the baseline 3 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 states a specific verb and resource with clear scope: every held act the register registered between two dates, newest first, with total and issuer counts, paginated via next_cursor. It explicitly distinguishes itself from search_law by saying that search_law ranks provisions by a question while this lists acts by registration date.

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

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

It gives concrete usage examples such as 'what was published in TAR yesterday', ministry orders with issuer='SADM', Government resolutions, and inspectorate rules. It also names the alternative search_law and the condition that selects it, leaving little inference about when to use 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?

Goes well beyond the readOnly/no-destructive annotations: it discloses the sign-in prerequisite (connect + connect_verify), how to propagate the session, cursor pagination to the end, per-row outcome quotes, `withheld` accounting, and a 1,000-ruling-per-call read cap. These are operational constraints an agent cannot infer from annotations.

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

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

Auth prerequisite is front-loaded and every sentence carries information, but the long multi-clause sentences with em-dashes and parentheticals are dense and partly restate schema content (outcome values). Efficient for a 12-parameter tool, yet not maximally 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 fully covers the return shape (rows with outcomes, exact total, counts by level and year, next_cursor, withheld) plus authentication and read limits. Nothing material 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 coverage is 100%, so the baseline is 3, but the description adds genuine semantics: the 'at least one filter required' rule (absent from the schema), how `cursor` must reuse the same filters, and how `outcome` is read from operative words with a `withheld` bucket. Minor repetition of enum-like values already in the schema keeps it 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 precise verb and resource ('EVERY held ruling matching structured filters') and explicitly contrasts itself with the sibling search_practice ('RANKS passages by a question and stops at a limit; this lists'). An agent can select between them 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 the exact job shape ('all of them') with concrete examples (all regional labour rulings since a date, every Constitutional Court ruling of a year), names the alternative tool and its differing behavior, and states the hard prerequisite that at least one filter is required.

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

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

Annotations already establish readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds behavior the annotations cannot: an auth prerequisite sequence, the session-token persistence requirement across calls, and truncation behavior via max_chars. It does not explain result ordering beyond the schema's note that jobs come first, so it falls just short of 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 sign-in prerequisite, then the purpose, then the sibling routing hint, in three compact sentences. Slightly dense parenthetical asides, but each sentence carries information an agent needs.

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

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

For a read-only list tool with zero required parameters and no output schema, the description covers auth, result sources, scope selection, sibling routing, and truncation handling. Only the return shape/ordering is left implicit (and partially covered by the schema), so it is nearly complete.

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

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

Schema description coverage is 100%, so each parameter (limit, scope, session, max_chars) is already fully documented in the schema. The description only restates scope='mine' ("shows this account's own library with versions and use"), which largely duplicates schema text and adds no new format or constraint details. 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?

"List the playbooks available: the ones Avokata ships and any this account has written" names a specific verb (list) and resource (playbooks), and clarifies the two sources of results. It explicitly distinguishes itself from find_workflow, which the agent could otherwise confuse with a library-listing call.

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 precondition (sign-in via connect/connect_verify unless already signed in) and the alternative path ("For one task, find_workflow is quicker: it names the one that fits"), plus the condition that selects scope='mine'. Nothing about when to choose this tool 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 declare only the mutation/openWorld profile; the description adds the auth prerequisite, the fact that 'read' marks a message read, that 'reply' lands in the same feedback thread, the snooze default/cap, the account-less degraded mode (service notices only), and a full safety model treating message content as untrusted data. This is far beyond what annotations 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 sign-in prerequisite and purpose, then action mapping, safety, and the edge case. Every sentence is load-bearing, though the action glosses partially duplicate the schema's enum descriptions, adding mild 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?

For a 7-parameter multi-action tool with no output schema, the description covers auth, every action's effect, safety constraints, and the account-less fallback. 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%, so the baseline is 3, but the description links actions to their required parameters (read/reply/dismiss/snooze take id; reply needs body; snooze needs hours; settings toggles email notice) and reinforces the confirmed-flag protocol, adding meaning on top of 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 resource (messages from the Avokata team to this person) and enumerates the exact operations via the action enum mapping (list/read/reply/dismiss/snooze/settings). An agent can tell this apart from siblings like submit_feedback or avokata_account 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 explicitly requires sign-in first (call connect and connect_verify unless already signed in), routes the agent when a `notifications` block appears ('tell the person in one sentence and offer to open them; their task comes first'), and gates replies on explicit approval. This is when-to-use guidance of an unusually high standard.

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

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

Annotations already cover the read-only, idempotent, non-destructive safety profile, and the description adds substantially more: sign-in prerequisites via connect/connect_verify, that served text is not automatically current law and must be checked against version/wording, that on_date does not make paragraphs historical, and that # unit/pinpoint overrides from_unit with no cursor available. These are non-obvious traits an agent could not 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?

Front-loads the sign-in prerequisite, then core mechanics, then two worked argument examples, which is a sensible order for a 13-parameter tool. It is dense but mostly earns its length; minor redundancy appears in restating the '# overrides from_unit' and next_from_unit caveats already present in the schema descriptions.

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 13-parameter tool with no output schema, the description compensates well: it names key response fields (paragraphs, version/wording, wording_on_date, next_from_unit, guidance.total) and explains how to continue a read. Auth, jurisdiction, language and ruling-specific behavior are all addressed.

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 a 3 is the baseline, but the description adds genuine meaning beyond the schema: pinpoint vs article equivalence, the rule that a next_from_unit from a pinpoint-filtered read is not a whole-document offset, and the explicit absence of limit/max_chars parameters. It doesn't document every parameter (lang, voice, guidance_limit are only in the schema), so it doesn't reach 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 ('Read a document by its own structure') and immediately contrasts it with its closest sibling: 'Never by character offset (read_source_text reads the publisher's text that way, without our structure).' An agent can distinguish read_paragraphs from read_source_text, get_document and search_* 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 explicit routing rules: pinpoint for a single article, from_unit+count for paging, ruling_part=disposition for the operative order, and a named exclusion (character offsets belong to read_source_text). It also states the prerequisite for document_id (must come from a search hit's id or document.id, not a case number) and the ECHR exception where the tool is not the answer.

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 readOnly/idempotent annotations, it discloses real operational traits: sign-in is required (connect + connect_verify first), what each page returns (publisher link, sha256, raw_basis, units_here), how to continue (next_from_char), and the negative case that ECHR `coe.hudoc:` documents have no text but return a HUDOC link. This is exactly the context annotations cannot 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 critical prerequisite (sign-in) is front-loaded, then purpose, then use cases, then pagination, then edge cases — a sensible order. It is dense and long-ish, but nearly every sentence carries distinct information; a little tightening would help.

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 takes on the burden of describing returns (per-page fields), continuation mechanics, auth requirements, and the ECHR no-text case. An agent has everything needed to call this correctly and interpret the result without opening other tools.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value on top: it shows example arguments, explains pagination flow via `next_from_char`, and notes that offsets can be cross-checked against a read's `structure_check.raw.args`. It does not re-explain on_date/jurisdiction, which the schema already handles well.

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

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

States a specific verb and resource: the publisher's text exactly as published, paged by character offset, explicitly excluding 'our sections, voice labels or units'. This implicitly and clearly distinguishes it from the structured-read sibling (read_paragraphs) and frames it as the ground-truth source the structure is built on.

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

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

Gives concrete triggers: read it when a read's `structure_check` says `verify`, when a section or speaker label looks wrong, or before relying on whose words a passage is. It also routes follow-up actions (submit_feedback with kind='structure'). It lacks an explicit 'use read_paragraphs instead when…' counter-route, so it is clear context without full exclusion 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 read-only, idempotent, closed-world, non-destructive, so the safety bar is low — yet the description adds substantial operational context beyond them: the sign-in precondition, the measured failure mode of English queries ('came back wrong', not empty), the wrong-code failure mode for procedural questions, what max_chars truncates and what it never cuts, and how amending acts are excluded by default.

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 almost every sentence carries decision-relevant information, and the language and code pitfalls are front-loaded. It loses a point because the auth preamble occupies the opening slot ahead of the purpose statement, and the language rule is restated three times (body, query description, jurisdictions note), making it longer than the tool's complexity strictly requires.

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 13-parameter tool with no output schema, the description covers everything an agent needs: what a result row contains (pinpoint, lang label, text_chars), how to read full text, how the character budget and `truncated`/`response_budget` behave, and the in-force/amendment semantics that determine answer correctness.

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

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

Schema coverage is 100%, so the schema already documents all 13 parameters; the baseline would be 3. The description nonetheless adds real semantics the schema does not: `jurisdictions` selects the law's scope and is not a language argument, `codes` must be passed for anything procedural and why, and a worked example argument set is supplied at the end.

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 — 'Find the statutory provision (teisės akto straipsnis) that governs a question' — and immediately scopes it ('consolidated version in force now', 'returns pinpoints, not summaries'). It also routes to the natural siblings (read_paragraphs, cited_by, check_validity) so an agent can tell it apart from the surrounding tools 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 and when-to-use-something-else: read_paragraphs for text, cited_by for judicial reading, check_validity with on_date for past-date validity, occurrences for exhaustive phrase checks, in_force=false vs. past-date as 'a different question'. It also gives a hard prerequisite (connect/connect_verify) and a routing rule for procedural questions via `codes`.

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 readOnly/idempotent/non-destructive, the description still adds substantial behavior: a sign-in precondition with named tools, anonymisation of parties, how compact vs full rows are shaped, deferral under max_chars with response_budget.recover, the echr_catalogue side output, and the fact that outcome is read from the ruling's own words rather than a court-published field. None of this contradicts the read-only 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 sign-in precondition is correctly front-loaded, but the remainder is a dense single block of roughly 500 words covering a dozen independent behaviors with no structure. Much of it (language rule, party-name caveat) duplicates parameter descriptions in the schema, so not every sentence earns fresh 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?

For a 19-parameter tool with no output schema, the definition still conveys result shape (`document` with case_no/court/decided_at/url, `cite_as`, `documents[<id>]` compaction, `echr_catalogue`), truncation behavior, and the sign-in requirement. An agent has enough to call correctly and interpret the response.

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 schema already explains nearly every parameter. The description adds genuine cross-parameter insight the schema cannot — 'No parameter filters by party' and how a party name behaves as query words, plus the fusion-vs-filter distinction between query/also and cites/cites_any/cites_none — which pushes it above baseline.

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

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

The description states a specific verb and resource up front — 'Find court practice (teismų praktika) on a legal question or a provision - rulings and judgments' — which is unambiguous. It references search_law, but only as an analogy for the language rule rather than to distinguish the two tools, and it never addresses list_practice or get_document, so sibling differentiation is incomplete.

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?

Offers concrete routing guidance: which language to pass the query in and why, which terms the courts use, when to filter by court_level (LAT for civil/labour/criminal, LVAT for administrative/tax), when decided_after is appropriate ('recently', not 'what governed then'), and an explicit exclusion — no parameter filters by party. It never states when to prefer this over list_practice or search_law wholesale, so it stops short of 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 mark this as a non-idempotent, open-world write; the description adds substantial context beyond them: sign-in prerequisite, human review of every item, the confirmed=true consent gate, authorship modes, and the non-promise about replies. It also describes the return ('carries a reference id') despite no output schema.

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

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

Long (multi-paragraph), but front-loaded with the sign-in prerequisite and organized into purpose, trigger, consent, and field guidance, with most sentences carrying actionable or privacy-critical content. A few fragments (length limits, kind repetitions) restate the schema and could be trimmed.

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 write tool with no output schema, the description covers the gaps that matter: authentication flow, consent requirements for user vs. agent-authored content, and what the response contains. An agent has everything needed to invoke it correctly and 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 the baseline is 3, but the description goes further by prescribing field usage: 'Fill kind and what', add expected/got for wrong answers, use tool/query for context, and only set contact_email when a reply is wanted. It also clarifies confirmed/authorship interplay. It slightly duplicates schema text (length limits) but adds workflow meaning.

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

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

Opens with a specific verb+resource and audience: 'Send feedback about Avokata to the team that builds it', then enumerates the accepted kinds (bug, wrong answer, missing data, missing feature, workflow idea, praise). No sibling tool does anything similar, so differentiation is implicit and 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?

Has an explicit 'When to offer it' block listing trigger conditions (empty/wrong answer, user correction, missing workflow step, repeated manual step), names the auth alternatives (call connect and connect_verify first unless already signed in), and bounds frequency ('Offer once, in one sentence').

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 readOnly/idempotent annotations: auth requirements, the deliberate refusal to merge the three answers, the 'not held vs non-existent' reporting rule, the single-citation constraint, and the distinction between missing dated wording and confirmation. This is substantive behavioral context an agent could not derive from the annotations.

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

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

Front-loaded with the sign-in prerequisite and the one-citation rule, and nearly every sentence carries usable instruction. It is dense and slightly repetitive of the schema on citation formats and quote handles, but the length is largely earned for a tool with this much answering behavior.

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

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

With no output schema, the description carries the full burden and does so: it enumerates the return fields (matches, voice, fragments, similar_passages, found_paraphrased, cited_vs_found, quote_differs_in) and the act-level grades. An agent knows what it will get back and how to interpret it.

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

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

Schema description coverage is 100% and the schema already documents quote grading, voice/fragments, and citation formats in depth, so the description largely restates it. It adds a little value with example arguments and the 'copy the attributed sentence into quote' instruction, but this is baseline territory 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?

Names a specific verb and resource ('Check a citation SOMEBODY ELSE produced') and scopes it precisely: it validates a third-party citation's existence, wording and currency. It does not, however, distinguish itself from siblings such as check_validity or compare_provision_versions, so the agent must infer whether this or check_validity is the right entry point.

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

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

Explicit when-to-use (citations a model, opposing brief or draft memo produced), prerequisites (sign-in via connect/connect_verify unless already connected), and per-item calling convention ('ONE citation per call... for a list, call once per citation'). It also states when to supply quote and on_date and what is lost without them.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description reinforces this with 'reads no legal text and changes nothing', adding the useful nuance that it does not read corpus content. It does not say whether the call itself counts against the daily allowance it reports, which is the one behavioral fact an agent pacing a long task would still want. No contradiction with 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?

Front-loaded with what it reports, then usage, then alternatives — a sensible order with no filler sentences. The opening sentence is a long enumeration, but every listed item is a distinct return value the agent would otherwise have to discover by calling 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?

There is no output schema, so the description carries the return payload, and it does so by naming the fields the agent gets back. Combined with the fully documented single parameter and the read-only annotations, an agent has everything needed 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 description coverage is 100% and the single `session` parameter is fully documented there, including the omit-case for OAuth/key connections, so the baseline is 3. The description adds only 'Example arguments: {}', which signals the call is argument-free but does not restate the session semantics it might have reinforced.

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 subject and enumerates exactly what is returned: connection status, email, usage against daily limits, jurisdictions with a corpus, newest data dates, and workflows. It also names the siblings it is not (avokata_account for plan/limits/keys, describe for corpus contents), so an agent can distinguish 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?

Gives an explicit trigger ('check sign-in or the remaining allowance before a long task') and routes two adjacent needs to their correct alternatives by name. Nothing about when to prefer this tool over avokata_account or describe 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, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely useful context beyond that: the sign-in prerequisite and the clarification that it 'saves nothing' and returns a schema with one example step rather than a drafted workflow. It stops short of describing the shape or size of the returned schema, so the added value is real but moderate.

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 sign-in prerequisite is usefully front-loaded, but the core purpose is delivered as one long comma-spliced sentence enumerating fields, rules, principles, versions, consent and guardrails, which is hard to scan. Information is dense and none of it is strictly wasted, yet the structure could be split so the purpose precedes the ancillary detail.

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 stateless guide tool with one optional parameter and no output schema, the description covers the essentials: auth precondition, what is returned, the guardrails on content, and the alternative route. It does not indicate how large or structured the returned schema is, which would help an agent plan how to relay it to the user.

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

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

There is only one optional 'session' parameter and the input schema documents it fully (100% coverage), including when to omit it for OAuth or key auth. The description contributes nothing about that parameter beyond 'Example arguments: {}', so it adds essentially no meaning beyond the structured 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 this is a reference for composing a workflow ('how to write a workflow with the user') and explicitly says what it returns: 'A schema with one example step, never a drafted workflow, and it saves nothing.' It also distinguishes itself from the sibling read paths (find_workflow, list_workflows, get_workflow). The purpose is clear but is buried in the middle of a long first sentence rather than front-loaded, which slightly weakens it.

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 both an explicit alternative and its selection condition: 'To use an existing workflow instead, find it with find_workflow or list_workflows and open it with get_workflow.' It also names a precondition for this tool (sign-in via connect/connect_verify unless already signed in), so an agent knows both when to call it and when to route elsewhere.

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