Interpelacja lub zapytanie: szczegóły i treść

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

Goes well beyond the readOnly/idempotent/openWorld annotations: it discloses that answer content almost always lives only in a PDF that the server extracts when odpowiedzKlucz is supplied, that scanned PDFs without a text layer cannot be read and only the PDF address is returned, and that partial results (timeout, Sejm outage, rate limit) surface via a wynikCzesciowy field with an explicit instruction to tell the user upfront. This is exactly the operational context an agent needs.

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

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

Four dense Polish sentences, front-loaded with the primary purpose before moving to edge cases. Every sentence contributes unique operational information (addressees, PDF caveat, partial-result handling), though the run-on first sentence is heavy and could be broken up.

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 tool with multiple operating modes and an output schema present (so return values needn't be re-explained), the description covers chunking, PDF extraction, scan limitations, and partial-result signaling comprehensively. The only gap is the absence of routing guidance to sibling 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?

With 86% schema coverage the schema already documents most parameters, so the baseline is 3. The description adds real value by explaining the interaction semantics: tresc pulls the letter body, odpowiedzKlucz triggers PDF extraction of the answer, and the chunking/fraza modes change what comes back. This exceeds what the schema fields state individually.

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 clearly states what the tool returns for a single pismo (interpellation or written question): addressees with deadlines and statuses, answers with PDF addresses, and optionally the letter/answer text in chunks. The verb+resource is specific. However, it does not differentiate itself from siblings like szukaj_pism (search) or tresc_wypowiedzi, leaving the agent to infer that this is the single-item retrieval counterpart.

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?

Usage is implied through the description of modes — chunked text retrieval, fraza search mode, odpowiedzKlucz for pulling answer content. But it never says when to choose this tool over szukaj_pism or how to obtain the required numer/rodzaj in the first place. Guidance is present but not comparative.

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