Get Contract

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses the response shape: top-level sibling keys (`contract`, `transaction_rollup`, `subaward_rollup`), the fact that subaward_rollup is Pro-only, and the important edge case that a legitimate `subaward_count: 0` means no subs, not an error. This adds behavioral context that annotations do not provide, without any contradiction.

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 somewhat long but efficiently packed: the core purpose is front-loaded, then usage alternatives, then parameter guidance, and finally response structure. Each section earns its place. It could be slightly tightened, but it remains well-organized and scannable.

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 a single required parameter and the presence of an output schema (which handles full return details), the description provides everything necessary for correct invocation: purpose, alternative tools, piid source, top-level response keys, and caveats (Pro-only subaward_rollup, zero-count meaning). No critical context 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 the only parameter `piid` is merely typed as a string. The description compensates by explaining that piid is the 'award PIID' and listing its possible sources (search_contracts, search_recompetes, or a company's award history). This gives the agent a clear understanding of what value to supply, far exceeding the schema 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 states a specific verb ('Get'), a specific resource ('one contract's LATEST transaction'), and the summary roll-up of totals. It explicitly names sibling tools (get_contract_modifications, get_contract_vehicle) and clarifies this is the 'SUMMARY view', making the tool's purpose unambiguous and distinguishable from alternatives.

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 provides explicit guidance on when to use this tool versus alternatives: 'for every individual modification row use get_contract_modifications; for what vehicle it's under use get_contract_vehicle.' It also tells the agent where the piid comes from (search_contracts, search_recompetes, or a company's award history), giving clear context for invocation.

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