Skip to main content
Glama

Summarize contract awards

summarize_awards
Read-onlyIdempotent

Count award notices and sum their Canadian-dollar values by supplier, buyer, or award year using procurement filters, so you can rank suppliers, profile buyers, or track spending over time.

Instructions

Count award notices and total their value by supplier, buyer or award year, using the same filters as search_awards. Use it to rank the suppliers winning a kind of work, see which organizations buy it, profile one supplier or buyer, or follow spending over time. Totals add Canadian-dollar values only and are indicative: standing offers and supply arrangements have no value, a supplier spelled two ways counts as two, and values are as last amended. The buyer is the contracting organization, often Public Services and Procurement Canada acting for another department.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "group_by": "<group_by>"
    },
    "name": "summarize_awards"
  }
}

Input Schema

NameRequiredDescriptionDefault
langNoOutput language.en
sortNoRank by total Canadian-dollar value or by number of awards. Years are always listed newest first.total_value
buyerNoWords from the contracting or end-user organization name, in either language. Public Services and Procurement Canada buys on behalf of other departments, which then appear as end users.
limitNoResults per page (1-50).
matchNoWhether a notice must contain all query terms or any of them. An explicit OR in the query always applies.all
queryNoKeywords searched in titles, descriptions, commodity names, supplier and buyer names, and solicitation and contract numbers. Words match in English and French, ignoring case and accents. Use "double quotes" for an exact phrase, a trailing * for a prefix (engineer*), and uppercase OR between alternatives.
offsetNoResults to skip, for paging.
regionNoText contained in a region of delivery, e.g. "Ontario" or "National Capital Region".
unspscNoUNSPSC commodity code or prefix. A segment or family code such as 43000000 or 4323 also matches every code beneath it.
categoryNoProcurement categories; an award matching any listed category is returned.
group_byYesWhat each row of the summary is.
supplierNoWords from the winning supplier's legal name, e.g. "Deloitte".
max_valueNoOnly awards with a stated value of at most this amount.
min_valueNoOnly awards worth at least this amount, in the contract currency (almost always CAD). Above zero, this drops awards with no stated value.
competitiveNotrue for competitively awarded contracts only; false for non-competitive awards and advance contract award notices only. Awards with no stated method match neither.
awarded_afterNoOnly contracts awarded on or after this date (YYYY-MM-DD).
awarded_beforeNoOnly contracts awarded on or before this date (YYYY-MM-DD).
include_cancelledNoAlso return cancelled award notices.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.2.1

TDQS

A4.4/5.0
Behavior5/5

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

Annotations already cover read-only, idempotent and non-destructive, so the description is free to spend its words on data semantics that annotations cannot express: totals count Canadian-dollar values only, standing offers and supply arrangements carry no value, name variants split into separate rows, and values reflect the last amendment. It also clarifies that the buyer is the contracting organization, often Public Services and Procurement Canada acting for another department, which prevents a common misreading of the grouped results.

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

Conciseness4/5

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

Four sentences, front-loaded with what the tool returns and how to use it, then the caveats. Each sentence earns its place, though the buyer-definition sentence partially duplicates the schema's buyer description and could be trimmed.

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

Completeness5/5

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

For an 18-parameter aggregation tool with no output schema, the description supplies what is otherwise missing: the returned metrics (count and total value), the row grain set by group_by, and the accuracy caveats about unvalued vehicles and name variants. An agent can predict both the shape and the reliability of results before calling.

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

Parameters3/5

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

Schema description coverage is 100%, so the baseline is a 3 and the schema already documents grouping, sorting, filtering and query syntax. The description adds only marginal meaning beyond that, mainly reinforcing what group_by produces (one row per supplier, buyer or year) and restating the buyer-as-contracting-organization nuance the schema already contains.

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

Purpose5/5

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

States a specific verb-and-resource pair plus the shape of the result: counts award notices and totals their value, grouped by supplier, buyer or award year. It explicitly ties itself to the sibling search_awards by saying it uses the same filters, so an agent can tell the aggregate tool apart from the raw-search tool without opening either schema.

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

Usage Guidelines4/5

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

Gives four concrete usage scenarios (ranking suppliers, seeing which organizations buy, profiling one supplier or buyer, tracking spending over time) and anchors the filter set to search_awards. It stops short of an explicit when-not statement, e.g. that individual notice details require search_awards or get_award, so the alternative is implied rather than spelled out.

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