Stipple — Government Tenders

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

With only readOnlyHint=true in annotations, the description carries the real behavioral burden and does so richly: anonymous callers see counts/values/dates but supplier and incumbent names are withheld with a withheld_reason, links require an API key or sign-in, values are published amounts never converted, and computed_at states the freshness date. It even instructs the agent to relay the withholding sentence verbatim.

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 summary line, the USE THIS WHEN block, and the parameter guidance are front-loaded before the long return/visibility caveats, so the essential routing information is read first. The remaining prose is dense and mostly earns its place, though the coverage/attribution sentence is borderline boilerplate.

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?

Although an output schema exists, the description usefully names every returned array (expiring, planned, recent_awards, top_suppliers, open_tenders, computed_at, sources), discloses the anonymous-caller redaction, the link restriction, and AU/NZ source coverage. An agent has everything needed to call it and to explain the result accurately.

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 states that buyer is 'the organisation name as published' and that buyer_key comes 'from a tender's buyer, or a previous answer', which tells the agent where each value originates. It does not clarify whether the two are mutually exclusive or what happens if both are omitted.

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

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

Opens with a specific verb+resource summary — 'What a buyer has awarded, what is ending, and what they plan' — that names the exact slice of data returned. It is clearly distinguishable from siblings like find_tenders and find_signals because it is scoped to a single organisation rather than a market-wide search.

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

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

Gives an explicit trigger ('USE THIS WHEN someone asks about a specific buyer before a bid') followed by three concrete query phrasings that map directly to the returned arrays. It stops short of naming alternatives or a when-not condition, so an agent must infer when to prefer find_tenders or find_signals 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 only declare readOnlyHint=true, so the description carries the rest and does so well: it is FREE, anonymous callers get everything except incumbent name and evidence link, `withheld_reason` explains the omission and must be relayed verbatim, and `confidence` is explicitly 'a vocabulary, not a score'. It also commits that windows are 'never invented', which prevents an agent from fabricating precision.

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 one-line definition and the routing sentence before any parameter detail, and every sentence carries distinct information. It is dense and the all-caps emphasis is heavy, but nothing is redundant or padding.

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?

Despite an output schema existing, the description adds what the schema cannot: the shape of results, the `derived` label, the confidence vocabulary, and the authentication-dependent redaction. For a zero-required-param discovery tool with no schema documentation, an agent has everything needed to call and interpret it.

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

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

Schema description coverage is 0%, so the description must compensate, and it does for four of six parameters: `kind`'s three values, `jurisdiction`'s ten values, `window_before` as an ISO date with 'window starts on or before it' semantics, and `q` searching subject/buyer/incumbent. `buyer` and `limit` are never explained, which is the only 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?

The opening line defines the resource precisely and positions it against siblings: signals are 'what may be tendered before it is', which is exactly the distinction from find_tenders/match_tenders. The three `kind` values are enumerated with parenthetical definitions, so an agent knows the exact scope 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?

'USE THIS WHEN someone asks what is coming' plus three concrete example queries gives strong positive routing. It never states when NOT to use it or names a sibling as the alternative, so the exclusions are left to inference, keeping it at 4 rather than 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 readOnlyHint, so the description does real work: reveals FREE within a weekly cap, explains the NZ default-off behavior, discloses that anonymous calls lose portal links while API-key/signed-in calls gain them, and carefully flags derived promotional fields (stipple_url, prepare_bid_url) with 'never invent one that is not in the result.' That is far more than the annotation carries.

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 scope and usage gate, then parameter notes. It is dense and long, but nearly every line earns its place; minor redundancy in vendor-URL explanation keeps it from a 5.

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

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

Despite an output schema, it usefully summarizes the return shape ({total, results[], coverage}), how results indicate tender-vs-grant, the link and coverage caveats, and the critical rule to quote coverage rather than overclaim emptiness. Complete enough for correct invocation and correct reporting.

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 does: defines kind values, the full jurisdiction enum set, tier values, the ISO date format for closing_before, the exact semantics of first_seen_after ('when WE first saw the tender'), and even justifies the deliberate absence of a location filter with the 84%-empty rationale. This is essential explanatory content the schema lacks.

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+resource with explicit scope: search tenders across AU with NZ only on request. It distinguishes itself from match_tenders right in the text, telling the agent which does the ranking/bidding check.

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 example queries that fit ('any council drainage tenders in Victoria') and names the alternative tool with the exact condition that selects it ('which of these could MY company actually bid for'). Explicit when/when-not routing.

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?

readOnlyHint=true already tells the agent this is a safe read, and the description goes well beyond that: 'Free, inside the weekly cap' (a rate/quota constraint), the anonymous-call withholding behavior, the `degraded` fallback semantics, and the exact rule for a 'high' band. It also discloses that `checks` and duplicate pairing are heuristics rather than hard facts, which is exactly the kind of caveat annotations cannot carry.

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

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

Front-loaded with the purpose, then broken into capped blocks ('USE THIS WHEN', 'TELL THE USER WHAT THE SCORE IS') that scan well. The paragraph enumerating every returned field is heavier than needed given an output schema exists, which costs it the top mark.

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 no-required-param ranking tool with an output schema, this covers the risky parts an agent must relay: the withheld/anonymous path, the degraded ordering, and the fact that `score` is relative fit not win probability. The only real hole is the unmentioned `jurisdiction` and `closing_before` filters.

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 carry the full burden, and it explains two of four parameters well: `company_url` ('a plain domain is fine, we resolve it') and `example` (built-in civil/it/facilities profile, no site read). `jurisdiction` and `closing_before` are named nowhere in the description, leaving half the parameters undocumented anywhere.

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: 'Rank open tenders against what a company actually does,' and the two-word scope (per-company matching) inherently separates it from a plain lister like find_tenders. It never names a sibling, so the differentiation is inferable rather than explicit.

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 'USE THIS WHEN' block gives concrete trigger phrasings ('what could we bid for', 'work for acme.com.au') and explains the `example` mode versus a real site read, which is strong routing guidance. It stops short of naming an alternative tool or stating when NOT to use it, so it lacks explicit 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?

Annotations only declare readOnlyHint=true; the description adds substantial context beyond that — it is FREE, it exposes sources behind login walls, sources whose robots.txt refuses access, and why a source returned nothing. It also flags the snapshot-vs-nightly distinction and the access-gated source_url, none of which is in the annotations.

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

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

Front-loaded with the one-line scope and the usage trigger before the field list. The return-value enumeration is somewhat long relative to an existing output schema, making one section partially redundant, but nothing is padded.

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 no-argument, read-only listing tool with an output schema, the description covers triggers, cost, access caveats, and data freshness. An agent has everything needed to decide 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?

The tool takes zero parameters, so there is nothing for the description to clarify; the baseline for a no-argument tool is 4. The description instead spends its budget on return semantics, which is the right allocation.

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

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

States a specific resource and scope: every source searched, what it is allowed to do, and what the last run returned. An agent can distinguish this provenance/coverage tool from the search tools (find_tenders, match_tenders) 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?

'USE THIS WHEN someone asks where the data comes from, whether a particular portal is covered, or why a search came back empty' gives three concrete trigger conditions. It stops short of naming a sibling as the alternative path, but the invocation context is unambiguous.

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