Get Contract Modifications

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds critical behavioral context: the data only covers FY2025 onward, so history may start mid-sequence, and earlier modifications are 'never ingested, not filtered out'. It also tells the agent to check the response's 'window' block for clamped/earliest_searchable/reason. This goes well beyond 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 well-structured and information-dense: core purpose in the first sentence, data caveat and response guidance in the second paragraph, then a bullet list for parameters. Every sentence earns its place with no fluff.

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 tool is complex due to its data completeness caveat and window block, and the description addresses both comprehensively. An output schema exists, so return values need no explanation. Offset is the only minor omission, but the rest of the context is complete for correct invocation.

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. It explains piid as 'award PIID' and limit as 'max 500', adding practical constraints not in the schema. However, the offset parameter is not described, leaving a small gap given the zero 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?

The description states a specific verb ('Get EVERY transaction row'), a resource ('contract'), and explicitly distinguishes itself from the 'latest snapshot get_contract gives you'. It names the sibling get_contract and clarifies the difference, making the tool's purpose 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?

The description clearly indicates when to use this tool: when you need the full modification trail rather than the latest snapshot. It contrasts with get_contract and provides important context about no per-request date filter. However, it does not explicitly say when NOT to use it or list alternative sibling tools beyond get_contract.

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