get_fixed_price_contract_details

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

With no annotations, the description carries the full burden. It does disclose the source of the contract value (from payment plan), the behavior of hourly rates for FP contracts (typically 0), and a recommendation to use financial data for effective rates. This is useful behavioral context, but it does not describe read-only nature (though 'get' implies it), error conditions, or any side effects. It adds moderate transparency but not comprehensive.

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 concise, consisting of two sentences. The first sentence front-loads the core purpose and contents, the second provides a practical note about hourly rates. No filler or redundant information. It is well-structured and earns its keep.

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 description covers the main elements an agent needs: what data is returned (value, schedule, tasks, rates), a key caveat about FP hourly rates, and a hint on how to calculate effective rates. There is no output schema, so the description effectively communicates the data scope. Minor omissions like return format or pagination are not critical for a get-details tool. Overall, it is reasonably complete for the tool's complexity.

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 100%, so both parameters (contractId, projectId) are already described in the schema. The description adds no new meaning to the parameters themselves; it only says contractId comes from get_project_contracts (which is already in the schema). The description does not compensate with additional parameter context, so the baseline of 3 is appropriate.

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 clearly states the tool's purpose: it retrieves complete details for a fixed-price contract, enumerating the specific data components (contract value, payment schedule, tasks/phases, hourly rates). This is a specific verb+resource. It does not explicitly differentiate from sibling tools like get_contract_hourly_rates or get_project_contracts, but the enumeration of contents makes the purpose distinct enough.

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 provides some implicit usage guidance: it indicates that for fixed-price contracts hourly rates are typically zero and suggests leveraging overall project financial data for effective rates. However, it does not explicitly state when to choose this tool over its siblings (e.g., get_project_contracts for list vs. this for details). The guidance is implied (it's for FP contracts), but not formally stated as usage criteria or alternatives.

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