calculate_hourly_cost

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

No annotations are provided, so the description must carry the full burden. It fails to disclose that the tool expects annual (not monthly) salary, working days per year (not billable hours per month), or any underlying assumptions (e.g., French social charges). This is a significant omission given the mismatch with the schema.

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 short and front-loaded with the purpose, which is good for conciseness. However, the inclusion of incorrect parameter descriptions (e.g., 'monthly salary') negates its efficiency. Brevity without accuracy is not valuable.

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 the tool has 3 parameters, no annotations, and an output schema (though content unknown), the description is insufficient. It fails to correctly list inputs, does not explain the calculation formula or assumptions, and provides no information about output format beyond 'true hourly cost.' This is inadequate for correct tool 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 100% (all three parameters have descriptions). The tool description should add value beyond the schema, but instead it introduces contradictory information (monthly vs annual, billable hours vs work days). This actively harms understanding and is worse than providing no additional info.

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 'Compute fully-loaded hourly cost-to-company,' which indicates the tool's purpose. However, it then lists inputs as 'monthly salary' and 'billable hours/month,' which directly contradict the actual input schema (annual_gross, work_days per year). This mismatch severely undermines clarity and could mislead the agent.

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 advises use for 'project pricing or freelance rate' and references 'list_bundles for related calculators.' This provides contextual guidance. However, it lacks explicit when-not-to-use instructions or alternatives beyond the bundle, and the input mismatch may cause the agent to misuse the tool in those scenarios.

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