find_judgments_for_provision

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does well: it explains the confirmed_reference semantics (true=verified via referenced regulations, false=only text match), states 'Live from SAOS', and includes a 'not legal advice' disclaimer. The main gap is not disclosing behavior for edge cases like zero results or ambiguous IDs.

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 two sentences, front-loaded with the core purpose and identifier formats, followed by the confirmed_reference explanation and pragmatics. Efficient and well-organized, though the confirmed_reference detail could arguably be more prominent given its importance for interpreting results.

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?

This is a moderately complex search tool with 6 parameters, no output schema, and no annotations. The description covers purpose, identifier requirements, optional refinements, result semantics (confirmed_reference), and sourcing (SAOS). It's reasonably complete for the complexity, though it could add a sentence about expected return format since there's no output schema.

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

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

Schema description coverage is 100%, so every parameter already has documentation. The description adds modest value by giving concrete examples ('art. 267', 'Kodeks karny', 'pl-du-1997-553') and clarifying the either/or relationship between document_id and journal_year+journal_entry. This enriches the schema but doesn't substantially exceed the 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 uses a specific verb+resource: 'Find Polish judgments that cite a given statutory provision.' It clearly distinguishes itself from sibling tools like search_case_law by focusing on provision-citation lookup rather than general case law search, and explains the identifier formats (document_id, journal_year + journal_entry).

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 usage patterns: 'Provide either document_id or journal_year + journal_entry, optionally an article and title_hint.' It notes these are optional refinements to sharpen search. However, it doesn't explicitly contrast with sibling tools or state when NOT to use this tool versus search_case_law, leaving a small gap.

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