Get Contract Modifications

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

Annotations already cover read-only, open-world, idempotent, and non-destructive behavior. The description adds critical behavioral detail beyond annotations: there is no per-request date filter, data only exists from FY2025 onward, and sequences may start mid-way (e.g., P00026 instead of P00001) due to non-ingested history. It also tells the agent to inspect specific response fields (clamped, earliest_searchable, reason) to verify completeness.

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 organized with a front-loaded purpose statement, a critical caveat, a clear instruction for handling response incompleteness, and a concise parameter list. Every section earns its place and the format is easy to scan.

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?

The output schema and annotations cover return values and safety traits, and the description provides the key data-floor caveat and window-block guidance. The only notable gap is the lack of pagination guidance via offset given the explicit 500-row limit on limit, which would be helpful for contracts with long modification trails.

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 0% schema description coverage, the description must compensate for parameter meaning. It clarifies that piid is the 'award PIID' and notes limit has a max of 500, but it fails to mention offset at all and does not explain that limit controls the number of rows returned. This is partial compensation but not complete.

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 ('Get') and resource ('EVERY transaction row for a contract') and explicitly contrasts itself with get_contract, which returns only the latest snapshot. This clearly distinguishes the tool from its sibling and conveys the exact scope of what it returns.

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 explicitly says this tool provides the full modification trail 'not just the latest snapshot get_contract gives you', which tells an agent when to choose this tool over get_contract. It also gives a practical usage caveat about the FY2025 data floor and instructs checking the response's window block before treating results as complete.

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