Przetargowy Janusz — Polish public tenders

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

Goes well beyond annotations: names the destination column ('Do przejrzenia'), states that a previously removed entry is restored, that duplicates are left untouched and echoed back, and spells out the three result states (added/restored/already). It also declares OAuth authentication and a trial/paid plan requirement, 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?

Front-loaded with the action and destination, then constraints, then return values — a sensible ordering. The sentences are long and parenthetical, and the 'one removed earlier comes back there' aside is slightly buried, costing some crispness.

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?

No output schema exists, and the description enumerates the return payload (result, status, workspace link). Combined with the auth/plan prerequisites and idempotency semantics, an agent has everything needed to call it and interpret the answer.

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 50% and the description compensates by explaining tender_id as the primary key, its sources, and slug as the fallback. It does not resolve what happens if both are supplied or what the acceptable slug format is, so it stops short of fully closing the gap.

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?

A specific verb and resource: adds a tender to the signed-in company's 'Moje przetargi' kanban, mapped explicitly to the UI action. It rules out confusion with request_summary and with listing tools, so an agent can distinguish it from every sibling in one read.

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 where the identifier comes from (search_tenders, list_matched_tenders, get_tender), plus an explicit non-overlap clause: summaries are not ordered here, request_summary does that. The idempotent case (already present, including a copy from another portal) is described so the agent knows the call is safe to repeat.

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 destructiveHint=true and idempotentHint=true; the description adds what the annotations cannot — OAuth authentication plus a trial/paid plan requirement, and that the chosen price is written into the offer documents. It stops short of explaining what the 'destructive' aspect actually overwrites (e.g., a previously confirmed price).

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

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

Two dense sentences, front-loaded with the action and unit (net PLN), followed by the variant mechanics and the auth/plan prerequisite. Slightly clause-heavy but no sentence is filler.

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

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

For a mutating tool with no output schema, it covers the essentials: prerequisites, variant semantics, and the side effect on offer documents. It omits what happens if a price was already confirmed (relevant given destructiveHint) and what 'rationale' is for.

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 only 25%, so the description has to compensate, and it does for the critical fields: it enumerates the three named variants plus 'manual' and states that 'manual' requires an amount. It leaves 'rationale' and 'tender_id' unaddressed, though tender_id is self-evident as a UUID.

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 — set the offer price (net PLN) of a tender in 'Moje przetargi' — and grounds it in the concrete UI action it mirrors. It also points at the sibling get_my_tender's fill_details.price_proposals as the source of variants, which lets an agent place it relative to the fill 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?

The description implies the workflow (read variants from get_my_tender, then commit one), but never explicitly says when to use this instead of set_fill_details, start_fill, or set_tender_status. Usage is inferable but not spelled out.

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/closed-world, so safety is covered. The description adds genuinely new behavioral context the annotations lack: the OAuth requirement and plan-tier gating. Minor gap: no statement about rate limits or behavior on invalid codes.

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

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

Two sentences with zero waste; the core purpose is front-loaded, followed immediately by the input format and prerequisites. Nothing repeats the title or annotations.

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 single-parameter, annotation-rich, no-output-schema tool, the description covers purpose, input format, and access requirements adequately. It briefly notes output shape ('each label comes with the full code') but could mention behavior on unknown codes.

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 0%, so the description must compensate, and it does: it explains the array-of-codes input, that the check digit is optional, and gives concrete examples ('45000000-7', '79952000'). It omits the maxItems=500 bound, but the core format ambiguity is resolved.

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: 'Resolve CPV codes to their Polish labels', which is clearly distinct from browsing tools like cpv_tree or cpv_search. It does not explicitly name those siblings or state when they should be preferred, so it falls short of a 5.

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 useful invocation context: pass an array of codes, check digit optional, and that OAuth plus a trial/paid plan is required. However, it never says when to use this rather than cpv_search or cpv_tree, so the alternative-selection guidance is only implied.

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, and non-destructive behavior, so the safety profile is covered. The description adds real value beyond that: the required OAuth authentication, the trial/paid plan gate, and the shape of the response ('matching codes with Polish labels'). Pagination and the meaning of the limit cap are still undisclosed.

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, front-loaded with the core purpose, then downstream usage, then access prerequisites. No filler or restated title.

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 usefully sketches the return value and its Polish labels, and covers auth and plan gating. What's missing is the behavior of the limit parameter and whether results are ranked or truncated, which matters for a search tool.

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

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

Schema coverage is 50%: the query parameter is documented in the schema with the Polish-language constraint, while limit has no description anywhere. The description's 'resolve free-text' reinforces query but adds nothing about limit, so it does not compensate for the coverage gap beyond the schema 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?

States a specific verb and resource ('Resolve free-text to CPV codes') and even explains what CPV is and that results come with Polish labels. It implicitly separates itself from cpv_labels and cpv_tree by positioning this as free-text resolution, but never names those siblings explicitly.

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 downstream usage: hand the codes to list_tenders filter='category', using the first 8 digits as the division. It also states access preconditions (OAuth plus trial/paid plan). It stops short of telling the agent when to prefer this over cpv_labels or cpv_tree.

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, closed-world behavior. The description adds useful non-schema context: OAuth authentication and a trial or paid plan are required, and each returned node indicates whether it has children. It does not describe error behavior or pagination, but it meaningfully supplements 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 description is four tight sentences, front-loading the purpose and then covering parameter usage, node behavior, and access requirements. Every sentence adds actionable information with no filler.

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

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

For a simple one-parameter tree traversal tool with annotations covering safety and no output schema, the description covers how to call it, access constraints, and the key child-flag behavior. It stops short of describing the full returned node shape or traversal depth semantics, but an agent has enough to 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 0%, so the description carries the full burden for the single `parent` parameter. It explains omission for top-level results, passing a code to list children, accepting the code with or without the check digit, and gives examples such as '45000000-7' and '45000000'. This is substantially more useful than the schema's pattern alone.

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 clear verb plus resource: 'Walk the CPV hierarchy' and explains that it lists children or top-level divisions. It is clearly a different operation from siblings like cpv_search and cpv_labels, but it does not explicitly name or differentiate them, so it falls short of the sibling-routing clarity required for a 5.

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 guidance: omit `parent` for top-level divisions and pass a CPV code to list its children. This is clear enough to invoke correctly, but it does not mention alternatives such as using cpv_search for keyword lookup or cpv_labels for labels.

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?

The annotations already cover read-only, idempotent, and closed-world, and the description adds real information beyond them: OAuth authentication is required, a trial or paid plan is required, the payload mirrors the public page, and older pages may return a different shape. It does not mention rate limits or error behavior, 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?

A single dense sentence that is front-loaded with the purpose and then enumerates the contents. Every clause adds information, though the parenthetical legacy-data aside makes the second half harder to parse.

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?

Since there is no output schema, the description compensates by enumerating the return payload and flagging that the schema variant depends on page age. Given there is one parameter, a read-only hint, and a plan restriction, an agent has enough information to call the tool correctly.

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

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

Schema coverage is 0% and the sole parameter is undocumented in the schema, so the description carries the burden: it explains that the slug is a contracting-authority slug and where to obtain it. It does not give the format or length, but it adds substantial value over the bare string.

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?

Uses a specific verb and resource: returns the profile of a single contracting authority, and lists exactly what is inside (identity, tenders, awards, contractors, plan positions). It is clear, but it never explains how it differs from the close siblings get_contractor and get_company_profile, so the agent must infer the distinction.

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

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

Explicitly tells the agent where the slug comes from (search_entities or a tender's authority), which is the key piece of guidance needed before calling the tool. It does not say when NOT to use this tool or when one of the sibling tools is the better choice.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds real context beyond them: it requires OAuth authentication and a trial or paid plan, and it flags that certain fields may be missing and that NIP is verified in the GUS register.

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 a single dense sentence built from nested parentheticals and em-dashes, which makes the returned-field list hard to scan on first read. It is front-loaded with the resource, but the mid-sentence tangents about mutation paths and NIP make it more convoluted than it needs to be.

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 burden of describing return values and does so by enumerating the profile and detail fields, plus auth and plan prerequisites. It stops short of stating the response shape or how missing fields appear, which keeps it from a 5.

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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-param tool is a 4. It appropriately spends its words on return content instead of nonexistent inputs.

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 the exact resource (the signed-in company) and enumerates what is returned: the matching profile (CPV codes with names, voivodeships, budget, interests, own description) and the document details (name, address, NIP, REGON, KRS, contact, default signatory). It also differentiates from writable siblings by naming set_company_details and set_matching_profile as the mutation paths, so an agent can tell read from write 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 makes clear this tool reads, and that changes go through set_company_details (all fields except NIP) or set_matching_profile (the matching profile), and that NIP is set only in the app via profile_url. That effectively routes the agent to the right sibling, though it never states the read-side trigger ('use when you need the company's profile') in so many words.

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 closed-world, so the safety profile is covered; the description adds the non-obvious auth and plan-gating requirement and notes the data equals the public page view. It does not cover failure behavior for an unknown or stale slug, which would be the remaining useful detail.

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?

Purpose is front-loaded in the first clause, and the trailing data enumeration helps an agent judge relevance before calling. The middle catalogue of fields is dense but each item earns its place by signalling returned data, given no output schema exists.

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 compensates by listing the returned data categories, and it covers the single parameter's origin plus auth/plan prerequisites. Nothing an agent needs in order to invoke this correctly is missing.

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

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

Schema description coverage is 0% and there is a single undocumented parameter, so the description carries the burden — it explains what the slug identifies and where to obtain it (search_entities, buyer results), which is the key operational fact. Length/concrete format of the slug is left to the schema's minLength/maxLength only.

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 the exact resource (one contractor profile) and the identifier (slug), and enumerates the payload categories: registry data, wins/offers, buyers, rivals, recent contracts. Naming the slug source (search_entities or a buyer's results) also disambiguates it from sibling lookups like get_buyer and search_entities, so an agent can route 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?

Gives concrete preconditions (OAuth authentication plus a trial or paid plan) and tells the agent where the required slug comes from, which is real when-to-use guidance. It does not name an explicit alternative or exclusion case (e.g. when to prefer get_buyer or get_company_profile), so it stops short of a 5.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds genuine context beyond them: authentication and plan requirements, and the enumerated AI summary states (ready / requested / no_documents / none) that shape what an agent will see. It stops short of describing error behavior for a missing or unauthorized tender.

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

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

One front-loaded sentence that puts purpose and scope first, then the payload enumeration, then the sibling pointer and prerequisites. It is dense but every clause corresponds to a real returned field; the long mid-sentence enumeration of return values is the only source of friction.

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 entire burden of explaining what comes back, and it does so field-group by field-group. Combined with the stated auth/plan prerequisites and the pointer to get_tender for the summary text, nothing an agent needs in order to call this correctly is missing.

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

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

Schema description coverage is 0% for the single parameter, so the description must carry the meaning, and it does: it explains that tender_id is a tender identifier coming from list_my_tenders or list_matched_tenders, which tells the agent where to obtain a valid UUID. It does not describe format or failure on unknown IDs, but the origin guidance is the practically important part.

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 tender from the signed-in company's "Moje przetargi" by tender_id') and then enumerates exactly what comes back: pipeline status and history, deadlines, AI summary state, document counts, fill state, links. It also distinguishes itself from siblings get_tender (summary text), list_my_tenders and list_matched_tenders, so an agent can route 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 the exact provenance of the required argument ('tender_id from list_my_tenders or list_matched_tenders') and names the alternative for a related need ('The summary's text itself comes from get_tender with the returned slug'). Prerequisites (OAuth authentication, trial or paid plan) are stated explicitly.

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: discloses the has_summary=false degradation (summary_sections and scope_brief null), the not-found behavior for non-public tenders, and the OAuth plus trial/paid plan prerequisites. These are exactly the preconditions an agent needs before calling.

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 verb, resource, and identifier, then packs edge cases and auth into the tail. It's dense rather than wasteful, though the long enumeration of returned sections partly duplicates the output 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?

With an output schema present, the description doesn't need to explain return shape, yet it covers the failure mode, the null-summary case, and access requirements. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100% and the single parameter is already documented as 'public_slug from a listing result'. The description only reinforces provenance ('from search_tenders/list_tenders results'), adding no format, casing, or constraint detail 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 verb and resource ('Fetch full detail for one tender by its public slug') and enumerates the payload so an agent can distinguish it from siblings like get_tender_results, get_tender_documents, or get_company_profile. The scope (single tender, by slug) is 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?

Explicitly tells where the slug comes from ('from search_tenders/list_tenders results'), which routes the agent to the right discovery tool first, and states when it fails ('Returns not-found for non-public tenders'). It doesn't explicitly name a sibling to prefer for partial needs (e.g. results-only), but the retrieval context is clear.

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 pagination limits, the next_offset continuation mechanism, fallback to notice text, documents_status and message behavior, copy_with_documents cross-portal pointers, source_url context, and OAuth plus trial/paid plan requirements. This is substantial behavioral context for an otherwise safe read-only tool.

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, but the description is a single very dense sentence with multiple semicolon-separated clauses. It is information-rich rather than wasteful, but the structure makes it harder to scan than a short multi-sentence or bullet-like explanation.

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?

Annotations cover safety and idempotency, and there is no output schema. The description fills that gap by explaining return-relevant behavior: document list, status and message when text is unavailable, notice fallback, source_url, and cross-portal copy pointer. It is complete enough for an agent to call 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 only 33%, so the description must compensate. It clarifies the relation between tender_id and slug, explains that each call reads 20000 characters, and tells the caller to pass next_offset as offset for continuation, adding meaning beyond the bare 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: reading text from a tender's documentation, explicitly naming SWZ, OPZ, attachments, and the specification-first behavior. It also clarifies the lookup keys, tender_id or public slug, making it clearly distinguishable from general tender lookup or file-listing 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?

Usage is strongly implied by the detailed description, and the no-document fallback behavior is explained. However, it does not explicitly say when to choose this tool over siblings such as get_tender_file or list_tender_files, nor does it state clear exclusions.

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: 20,000-character paging via offset, download links expiring in 5 minutes, the surprising rule that a filled document downloads as editable Word/Excel even when the filename ends in .pdf, and the OAuth plus trial/paid-plan requirement. These are exactly the behavioral traps an agent would otherwise hit.

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 core purpose, and every clause carries real information. The single long sentence with nested parentheticals is dense and slightly harder to parse than it needs to be, but nothing is filler.

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

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

No output schema exists, so the description supplies the return shape itself: paginated text, a time-limited download link, download_filename, and the pdf_download_url/pdf_filename pair for filled documents. An agent has everything needed to call it 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 0%, so the description must compensate, and it does: file_id is defined as an archive document identifier sourced from list_tender_files, and offset is explained as taking the next_offset value returned for continuation. Both parameters gain meaning unavailable in the bare 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 – fetching one file from the signed-in company's document archive – and anchors the file_id to its source tool (list_tender_files). This clearly distinguishes it from sibling list_tender_files and get_tender_documents.

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 file_id comes from list_tender_files, which routes the agent from the listing tool to this one. It stops short of stating when not to use it (e.g. bulk download vs single file), so it falls just short of full alternative 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 cover the read-only/idempotent/non-destructive profile, and the description adds genuinely new behavior: empty `results` when no award exists, `found=false` for non-public slugs, per-part `winners` semantics, and the OAuth plus trial/paid plan requirement. That auth gating is exactly the kind of context 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?

Front-loads the verb, resource, and batch limit before the alternative source, and each clause carries substance (return fields, edge cases, per-part behavior). The single dense paragraph is long, but almost every sentence earns its place given there is no output schema.

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 does the full job of enumerating return fields (title, authority, estimated value, deadline, URL, award results) and the edge-case sentinels (`results` empty, `found` false, `winners` per part). Nothing an agent needs to interpret the response 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 single `slugs` parameter is documented in the schema, but the description still adds value by pinning the origin of slug values to listing results and reinforcing the batch limit implied by maxItems: 10. Sits above the high-coverage 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?

States a precise verb and resource — fetch award results for up to 10 tenders by public slug — and explicitly distinguishes itself from get_tender (batch, no AI summary) and from search_archived_tenders (the source of slugs). An agent can route here without opening either sibling 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 clear use case ('to compare prices of similar past tenders') and tells the agent where slugs come from ('from search_archived_tenders or any other listing'), plus how it differs from get_tender. It stops short of explicit when-not conditions, but the context is actionable.

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 needs no restating. The description adds genuinely new behavioral context: it requires OAuth authentication and a trial or paid plan, and it describes the shape of each returned item (a count plus a slug/code). Minor gap: nothing about result size or rate limits.

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 sentences, front-loaded with the resource and its contents before the routing advice and the auth/plan caveat. Every clause carries information, though the middle sentence packs two extra facet families (buyer_types, kinds) densely enough that it reads slightly list-heavy.

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 parameters and no output schema, the description must carry the return-value burden, and it does — enumerating the facet families and stating each entry has a count and a slug/code. It also covers the auth/plan prerequisite. What "active tender set" means and whether the facets are user-scoped is left slightly ambiguous.

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?

The tool takes zero parameters, so the baseline is 4 and there is nothing the description could add or omit. The description correctly implies no input is needed, focusing entirely on what the call returns.

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 and resource ("List the browsable facets of the active tender set") and enumerates exactly what is returned: CPV categories, voivodeships, cities, buyer_types and kinds. It also states the payload usefulness (count plus the slug/code to pass to list_tenders), which distinguishes it clearly from siblings like cpv_tree or search_entities.

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?

"Call this to discover valid filter values" is an explicit when-to-use instruction, and the description names the downstream consumers (list_tenders, search_tenders) so the agent understands the discovery-then-filter workflow. It lacks an explicit when-not or a pointer to a competing sibling, which keeps it below 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 say readOnly/idempotent/non-destructive; the description adds the materially important context: OAuth authentication and a trial or paid plan are required, results are capped at 50 per page, and a missing-CPV profile yields an explanatory answer rather than an empty list. It also discloses the shape of each returned item (fit_score, has_summary, app_url, public url, matching_profile).

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?

A single dense paragraph that front-loads what the tool is and the view choice before edge cases and return fields. Every clause carries information, though it runs long and the auth/plan caveat would read better as a separate sentence.

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 10 optional parameters and no output schema, the description covers the gaps that matter: view semantics, profile-driven defaults, pagination limit, the return-field inventory, the no-CPV failure mode, and auth/plan prerequisites. An agent has enough to decide and call 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 60%, so the schema carries most of the burden, and the description only adds meaning for the 'view' parameter and the profile-derived defaults behind regions/min_value/max_value. It says nothing about sort, dir, kind, query or deadline_before beyond what the enums already convey, so it adds modest value over 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 ('matched tenders' for 'the signed-in company') and immediately grounds it in the matching-profile mechanism, which cleanly separates it from siblings like list_tenders, search_tenders and search_my_tenders. An agent can tell what this returns 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?

Explicitly explains the 'recommended' vs 'all' view choice and the precondition that a CPV-populated profile must exist, plus what happens when it does not (no list, link to profile). It does not name a sibling alternative for general tender browsing, so it stops short of full when-not 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 readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuine context beyond that: it requires OAuth authentication and a trial or paid plan, which the annotations do not convey. It stops short of describing pagination or result limits.

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

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

Two sentences, zero filler, with the resource and scope front-loaded and the access requirements placed after. Nothing is repeated from the title or annotations.

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 zero-parameter read tool with no output schema, the description supplies the resource, the fields returned, and the access prerequisites. It omits pagination or result-count behavior, which is the only meaningful remaining gap for an agent calling 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?

The tool takes zero parameters, so the baseline is 4. The description nevertheless enumerates the content of each alert profile (query, CPV codes, regions, budget band, delivery settings), which frames the semantics of the returned object in the absence of an output 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?

Names a specific verb and resource ('List the signed-in user's saved alert profiles') and disambiguates with synonyms ('saved searches / notification rules') plus the fields it surfaces. This is unmistakably distinct from siblings like list_my_tenders and search_my_tenders, which operate on tender data rather than saved alert profiles.

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?

States the prerequisites for use ('Requires OAuth authentication and a trial or paid plan'), which tells the agent when the call will actually succeed. It does not name alternatives or explicitly exclude scenarios, but no sibling covers alerts, so routing ambiguity is low.

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 closed-world, so the safety profile is covered. The description adds real value beyond that: result ordering ('most recently updated first'), the fields returned (pipeline status, public URL), and the authentication/plan requirements.

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

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

Two tight sentences: the core action and result shape come first, the prerequisite second. Nothing is redundant and no sentence fails to earn its 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?

With no output schema, the description does the right work by naming the returned fields and ordering, and it discloses auth and plan requirements. The remaining gap is pagination/limit behavior, which is left entirely to the schema's numeric bounds.

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 0% and the single 'limit' parameter is never mentioned in the description. The schema does carry a default (25) and min/max bounds, so the parameter is not fully opaque, but the description makes no attempt to explain paging or what limit controls.

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 ('List the tenders in the signed-in user's pipeline') and clarifies the local alias 'Moje przetargi'. The phrase 'signed-in user's pipeline' implicitly separates it from the sibling list_tenders/search_tenders, but it never names those alternatives explicitly.

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 a prerequisite ('Requires OAuth authentication and a trial or paid plan'), which is useful gating context, but gives no explicit when-to-use versus siblings such as search_my_tenders or list_tenders. Usage is only implied by the 'signed-in user's pipeline' framing.

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

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

Adds genuinely non-obvious behavior beyond the annotations: the first call may copy tender documents into the archive if it is empty, which explains why readOnlyHint=false on an ostensibly listing tool. It also discloses OAuth authentication and a trial/paid plan requirement, plus the returned fields (type, version, date). No pagination, result-size, or ordering behavior is mentioned.

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?

A single front-loaded sentence that puts the resource and scope first, then the file origins, then the read-alternative and prerequisites. It is dense and slightly run-on, 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?

With no output schema, the description supplies the return shape (type, version, date) and covers auth, plan gating, and the archive-population side effect. Missing only edge-case behavior (tender not in 'Moje przetargi', empty archive after copy, result limits) for a tool that mutates state on first call.

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 0% and the schema only constrains tender_id to a UUID, so the description must carry the meaning — and it does, clarifying that the ID identifies a tender in the user's 'Moje przetargi' archive rather than any arbitrary tender. It does not state what happens when the ID is not in the company's saved tenders.

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 the concrete resource (files in the document archive of one tender) and the scope ('Moje przetargi' of the signed-in company), which an agent can act on directly. It also enumerates the three file origins (copied-in, company uploads, Janusz-filled documents). It does not distinguish itself from the sibling get_tender_documents, which an agent could easily confuse with this 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?

Explicitly routes content retrieval to get_tender_file ('Read one with get_tender_file'), so the list-vs-read split is unambiguous. It also states the precondition that the tender must belong to the signed-in company's saved tenders. It gives no guidance on when to prefer get_tender_documents or get_tender_file's metadata path instead.

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 closed-world, so the safety profile is covered. The description adds genuinely new operational context the annotations cannot carry: OAuth authentication plus a trial or paid plan is required, and 'active' versus archived tenders is a distinct result set. Pagination depth (page max 10) is not mentioned, keeping it below 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?

The opening clause front-loads the distinguishing property, then the filter modes are packed into two tight parenthetical sentences with no filler. Slightly dense and backtick-heavy, but every clause 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?

An output schema exists, so return values need no prose. Auth and plan requirements, the filter axis model, the facet-value dependency and the active/archived distinction are all present, which is everything needed to invoke 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?

With 50% schema coverage the description has to compensate, and it does: it explains that `filter` selects the search axis, spelling out the meaning of 'all', 'category' (CPV division code), 'region' (voivodeship slug) and 'city' (city slug) — semantics the bare enum does not provide. `value` and `archived` are already documented in the schema, but `page` is undocumented in both places.

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 ('Browse tenders') and immediately scopes it apart from the textual search sibling with 'without a text query'. The filter-axis enumeration tells the agent exactly what shapes of result are obtainable, so it is distinguishable from search_tenders, list_matched_tenders and list_my_tenders 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 prerequisite chain ('Use list_facets first to get valid values') and maps each filter mode to its required value source, which is real routing guidance. It does not explicitly exclude a case or name the alternative to use when a text query is desired (the archived/search_archived_tenders pointer lives only in the schema, not the description), so it stops short of full when/when-not coverage.

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 layers on real behavioral context beyond that: the settled_tenders definition, the caveat that award results are missing for some finished tenders (especially recent months), that a very broad scope may not count in time and says so, and the OAuth plus trial/paid plan requirement.

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?

Purpose and sort options are front-loaded, and nearly every clause carries information (scope rules, defaults, caveats, return fields). It is a dense single paragraph, so the enumeration of returned fields and the caveats could be broken out for faster scanning.

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?

No output schema exists, yet the description fully enumerates the returned per-contractor fields (wins, parts_won, share_of_tenders, value_pln with its reliability caveat, last_win, NIP, slug/url) and explains the aggregation basis. An agent has everything needed to call it and interpret 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?

With 67% schema coverage, the description adds meaning the schema lacks: the CPV division-vs-narrower-code matching rule (mirroring cpv_codes[].match in search_archived_tenders), that regions refer to the contracting authority's voivodeship, and the default 24-month period that is not encoded in the published_after/published_before defaults.

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 — ranks contractors who won public tenders in a given sector (CPV) and region, with an explicit choice between sort='wins' and sort='value'. It is clearly distinguishable from siblings like list_tenders or search_archived_tenders, which return tenders rather than aggregated winners.

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?

Explains the scope conditions (finished tenders, contracting authority's voivodeship, publication period defaulting to 24 months) and routes follow-up work to siblings: cpv_search for codes, list_facets for region slugs, and get_contractor for the returned slug. It does not explicitly state when to prefer this over list_tenders or search_archived_tenders, so no true 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?

Adds context the annotations cannot express: OAuth authentication plus a trial or paid plan is required, and the call is asynchronous — it queues a summary, or first a document download/read. The status taxonomy discloses every possible behavior along with its follow-up, well beyond readOnlyHint=false / idempotentHint=true.

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 verb and resource, and every clause carries operational value (UI anchor, statuses, auth). The opening sentence is slightly run-on — "queues the summary, or first the download or reading of the tender documents" needs a second pass to parse.

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 correctly takes on the return-value burden by enumerating the status values and their meaning. Authentication and plan gating are covered; only identifier precedence is left implicit, a minor gap for a two-optional-parameter tool.

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

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

The description adds "By tender_id or public slug," which matches the schema's indication that slug is used only when there is no tender_id. With 50% schema coverage and zero required parameters, it does not resolve whether calling with neither identifier is valid or which identifier wins if both are supplied. 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?

States a specific verb and resource ("Orders the AI summary of a tender's documentation (SWZ)") and anchors it to a UI equivalent ("Wygeneruj teraz"). It also distinguishes itself from the read-side siblings by naming get_tender and get_my_tender for retrieving an existing summary.

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 exclusion: if status is already-done, do not re-request — read via get_tender/get_my_tender. Each terminal/interim status carries the next action ("ask again in a few minutes", "no SWZ among the documents"), so an agent knows exactly when to call and when to stop.

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 past the readOnly/idempotent annotations: it explains the AND-matching rule plus semantic expansion, documents the `teaser` award-result grammar including the cancelled and no-result cases, discloses `has_summary=false` inclusion, defines `mode` and `unapplied_filters`, and states the OAuth plus trial/paid plan prerequisite.

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 capability and use cases, then filters, then output semantics, then recovery tips — a sensible order. It is dense and long, and the `teaser` format detail borders on over-specification given an output schema exists, but nearly every sentence carries operational 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 16-parameter search tool with a high-coverage schema and an output schema, the description still covers matching behavior, result-shape caveats, degraded-mode signals, and auth/plan requirements. Nothing an agent needs before calling it 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 already 88%, so the baseline is 3, but the description adds real semantics on top: what only_settled buys you and its hit-rate roughly by tender age, that cpv_codes expand to sub-codes sourced from cpv_search, and what the value and date-range filters constrain. Sort options and CPV expansion are partly restated from the schema, keeping it below 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 with a hard scope boundary: 'Search finished Polish public tenders (submission deadline passed)'. That boundary is what separates it from the active-tender siblings, and it also points to get_tender_results for the full result detail.

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

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

Names concrete jobs to be done ('similar past tenders to price an offer, and who won them') and gives a decision rule for only_settled=true ('use it to compare prices'). It also handles failure recovery ('Few results: try fewer or other Polish words') and routes to cpv_search/list_facets for filter inputs.

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 closed-world, so safety is covered. The description adds what the structured fields do not: OAuth plus a trial or paid plan is required, and each match returns city, voivodeship, slug and public URL. Pagination/limit behavior is not explained.

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 tightly packed sentences: purpose and kind semantics first, then return values and next step, then prerequisites. Every clause carries information, though the opening sentence is dense enough to slow parsing slightly.

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 correctly supplies the return shape and the slug handoff to detail tools, and it discloses the auth/plan gate. The only real gap is result-count/pagination behavior via limit, which an agent might need for broad queries.

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 only 33% (only 'query' is documented in schema), so the description compensates by mapping kind to buyer vs contractor and explaining query accepts either a Polish name fragment or a NIP. The limit parameter (default 20, max 20) is left unmentioned in both places.

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 (find) plus both resource types, and defines the kind values inline with Polish domain terms ('zamawiający', 'wykonawcy — companies and sole traders'). This clearly separates it from get_buyer/get_contractor, which fetch one entity by slug rather than searching.

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 implies the intended flow: search here to obtain a slug, then pass it to get_buyer / get_contractor. It also names the two input modes (name fragment or NIP). It does not say when not to use it (e.g. for tender search, use search_tenders), so it stops short of full routing 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 readOnly, idempotent, non-destructive behavior; the description adds real context beyond them: OAuth authentication and a trial or paid plan are required, results are 50 per page, and cards match list_matched_tenders. It does not cover edge cases such as an incomplete company profile, but the key operational constraints are 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?

The description is front-loaded with the core purpose and scope, then adds view, pagination, alternative, and auth details. It is dense but nearly every clause earns its place; the semicolon-chained structure is slightly run-on.

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 search with no output schema, the description provides enough to call correctly: scope, views, pagination, Polish query expectation, auth/plan prerequisites, and the return shape by reference to list_matched_tenders. Minor gaps remain around behavior when the company profile is absent.

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 only 33%, so the description carries extra weight. It explains that the query is in Polish and gives an example, clarifies the 'recommended' view as filtered by what the company does when its profile says so, and notes 50 per page; only the page maximum is left 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?

The description states a specific verb and resource ('Search the signed-in company's matched tenders by words') and bounds the scope to tenders that fit the company profile. It names the sibling it is not (search_tenders for all Polish tenders) and ties results to list_matched_tenders, so an agent can distinguish it 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?

It explicitly routes the agent to search_tenders when all Polish tenders are wanted and explains the 'recommended' vs 'all' views. It does not explicitly say when to prefer list_matched_tenders over this search, so the alternative guidance is clear but not 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 already cover read-only, idempotent, non-destructive traits, yet the description adds substantial behavior: the semantic fallback and mode/hint fields, the degraded search with unapplied_filters, has_summary=false cards, the 10-page/25-card pagination cap, and OAuth plus trial/paid plan requirements. The matching semantics are described carefully enough that an agent can predict result loss from extra query words.

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 purpose, which is good, but the text becomes a dense wall of em-dash clauses, and some material (summary ordering, trial plan, has_summary behavior) is lengthy relative to what an agent needs to invoke the tool. Structure is serviceable but not tight.

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?

Complete for an 18-parameter search with an output schema: it covers query construction, filter families, semantic fallback, degraded mode, auth and plan requirements, and pagination. 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 89% (baseline 3), but the description genuinely adds value: it explains what a good query looks like (1–3 Polish subject keywords, not sentences), that every extra word removes tenders, and it maps the filter families (CPV with sub-codes, voivodeships, kind, buyer type, notice type, deposit, date ranges, value). It doesn't clarify sort direction or the `region` vs `regions` distinction.

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 (search Polish public tenders) with the exact matching model — all words, any inflection, in title or contracting authority, with the whole query also in CPV and description. It clearly distinguishes itself from search_archived_tenders, list_tenders and list_matched_tenders, the latter of which it names explicitly.

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 guidance: 'For the tenders that fit the user's company use list_matched_tenders', 'take CPV codes from cpv_search', and 'Narrow with the filters instead' of extra words. It also states a when-not rule — extra query words remove results — which is a real selection constraint.

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 annotations, the description discloses partial-update semantics ('Only the given fields change'), the NIP exclusion, that the response includes saved fields and missing fields, and that OAuth plus a trial or paid plan are required. These are substantial operational details for a mutation tool.

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 purpose and partial-update behavior, then quickly covers the NIP exclusion, return value, and auth requirements. It is efficient, though the product-specific phrasing 'that Janusz writes' could be slightly clearer for a general agent.

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 13 optional parameters, no output schema, and destructive/idempotent annotations, the description supplies the missing context: partial update behavior, return content, auth and plan requirements, and the NIP exception. An agent has enough information to invoke it correctly without surprises.

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 13 parameters are already documented in the input schema. The description adds only a broad exclusion for NIP and does not expand on individual field meanings, which is acceptable given the complete schema 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 states a specific verb ('Sets') and resource ('signed-in company's details') and scopes it to data used in offer documents, matching 'Profil firmy'. It also explicitly distinguishes the operation from NIP handling, which is app-only and GUS-verified.

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 clear context for when to use the tool: updating company profile data as stated by the user. It explicitly excludes NIP and points to the app for that field, but it does not name sibling alternatives such as get_company_profile for reading current values.

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 destructiveHint=true, idempotentHint=true and readOnlyHint=false, so safety is partly pre-communicated. The description usefully adds OAuth and trial/paid plan requirements, the partial-update behavior, and that it returns the list of still-missing fields. However, it never explains what destructiveHint means here — whether previously stored values are overwritten — leaving the main risk unaddressed.

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?

Core purpose is front-loaded in the first clause, with secondary constraints (partial update, return value, auth/plan) following in short sentences. The opening sentence is long and dash-laden, but every sentence carries distinct 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?

With no output schema, the description correctly discloses the return value (what is still missing) and the auth/plan prerequisites, and it scopes the VAT/price split to confirm_bid_price. The one gap is destructive/overwrite behavior, which matters for a tool flagged destructiveHint=true.

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 80% and the enum on vat_rate is documented in-schema with a fallback default of 23. The description lists the same three field groups but adds no format, ordering, or syntax detail beyond what the schema already supplies, so 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 (Sets) and resource (details Janusz needs to fill in tender documents), enumerates the exact fields (completion deadline, signatory name/role, VAT rate), and names the product surface 'Moje przetargi'. It also names the sibling that handles the offer price, so the agent can distinguish it from confirm_bid_price 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?

Explains the workflow position: it reports what is still missing before start_fill, and explicitly routes price-setting to confirm_bid_price. It also clarifies partial-update semantics ('Only the given fields change'). No explicit when-not-to-use case (e.g. before add_to_my_tenders), which keeps it below 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?

Goes well beyond the destructiveHint/idempotentHint annotations: discloses company-wide blast radius ('for EVERY user of the company'), a hard rate limit (10 changes/day per company), a propagation timeline (score within ~1 hour, AI summaries several hours), and that 'only the given fields change'. It also states auth and plan requirements and that the tool returns before/after profiles.

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 what the tool does, then layers preconditions, side effects and limits; every sentence carries real information. It is dense and long-ish for one definition, but the length is justified by the number of non-obvious behaviors (delay, rate limit, company-wide scope) that an agent must know before calling.

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

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

For a destructive 8-parameter mutation with no output schema, the description supplies everything an agent needs: prerequisites (OAuth, plan, user_confirmed), scope of effect, rate limits, post-change propagation, and return payload ('the profile before and after'). Nothing material 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 description coverage is 100% and each parameter already documents its replacement vs. additive semantics, so the schema carries the burden. The description adds only marginal orientation — pointing at cpv_search as the source for CPV codes and restating the user_confirmed meaning already present in 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?

Names a specific verb+resource ('Changes the signed-in company's MATCHING PROFILE') and enumerates the exact fields touched (CPV codes, voivodeships, budget, does/does-not). It also anchors the concept to a UI location ('Settings → Profil'), which removes ambiguity about which object is being mutated, and separates it from list_matched_tenders and search_tenders.

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 the profile 'is set ONCE and then stays as it is' and that changes require 'a concrete reason the user gives', which steers the agent away from casual edits. It names the alternative for out-of-profile browsing ('Tenders outside the profile are found with search_tenders, without changing it') and states the user_confirmed=true precondition.

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

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

Goes well beyond the annotations (readOnly=false, idempotent=true, destructive=false): discloses that Odpuszczam requires a reason, that Wygrana requires a contract value, that a refused move returns allowed_statuses, that changes are written to status history and notify the team, and that OAuth plus a trial/paid plan are required. This is exactly the operational context an agent needs before mutating state.

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 verb and resource, then the allowed transitions, then side effects and auth. It is dense and long for a single block, but nearly every clause carries distinct information; light restructuring into sentences would improve scanability.

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 and four parameters, the description covers preconditions (auth, plan), valid targets, conditional parameters, and the failure shape (allowed_statuses). The only gap is the success response, which an agent might want to know since no output schema exists.

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 75%, so the baseline is 3, but the description adds value the schema lacks: it names list_my_tenders as the source of valid status names and enumerates the full closing/appeal status vocabulary, which the schema cannot express because there are no enums. The reason/winning_price conditions largely restate the schema fields, keeping 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 specific verb and resource ('Moves a tender ... to another status') and immediately scopes it to the signed-in company's 'Moje przetargi' kanban. It is unmistakably distinct from siblings like list_my_tenders or get_my_tender, which only read tender state.

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 enumeration of permitted transitions (own stages, 'Do wysłania', 'Oczekiwanie na wynik', closing statuses, appeals, back-moves) tells an agent exactly when the call will succeed. It also points to list_my_tenders as the source of valid status names. It stops short of naming an alternative tool for cases outside these transitions, so not a full 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?

Goes well beyond annotations: discloses that the operation takes minutes, that progress is polled via get_my_tender (last_fill) and results via list_tender_files, that it consumes the plan's fill limit, and the 8/day per-person rate limit. It enumerates terminal statuses (started, missing_facts, nip_required, fill_limit, rate_limit) and states OAuth plus trial/paid plan requirements — none of which 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?

Purpose and the app-equivalent name are front-loaded, and every clause carries information (prerequisites, statuses, progress, limits). It is a dense single paragraph with semicolon-chained clauses, which slightly hurts scannability but wastes nothing.

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 supplies exactly what would otherwise be missing: the status vocabulary to interpret the result, where to poll progress, and where the produced files appear. For a long-running, quota-consuming mutation, nothing essential is absent.

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?

allow_missing is fully explained in both schema and prose, including the prerequisite status that motivates it. tender_id carries only format/pattern in the schema with no prose meaning, but it is self-evident as the target tender; coverage is 50% yet the description compensates well for the parameter that actually needs semantics.

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 ('Starts filling in the documents of a tender ... with the company's data') and enumerates what gets filled (forms, declarations, price form), plus maps it to the recognizable in-app action 'Wypełnij'. An agent can distinguish it from set_fill_details or get_tender_documents 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?

Explicitly names prerequisites (offer price, completion deadline, signatory name/role) and routes the agent to the exact tools that satisfy them (confirm_bid_price, set_fill_details) via status missing_facts. It also explains allow_missing=true as the user's deliberate choice ('Wypełnij z tym co jest'), so use-vs-not is unambiguous.

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