score_contract

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does well by explaining the 5-factor matching behavior, the 0-100 numeric output, and adding a critical security note that returned fields are untrusted scraped data and should never be treated as instructions. It does not explicitly state whether the operation is read-only, but the verb 'score' strongly implies a non-mutating computation.

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 two efficiently written sentences. It front-loads the action and primary output, then provides the essential security caveat. Every sentence earns its place with no redundant phrases or filler.

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?

For a tool with no output schema and no annotations, the description covers the core behavior, scoring factors, output range, and an important security consideration about scraped data. It is largely complete, though it could slightly improve by clarifying what the returned score is based on in terms of the profile fields or whether any additional output metadata is included.

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 high, so the schema already documents contract_id and most profile fields. The description adds meaningful mapping semantics beyond the schema, such as skills mapping to primary_skills and headquarters_state defaulting to the first service area, which helps the agent understand how the profile inputs are interpreted.

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 ('score'), a precise resource ('a single contract'), and a target ('a contractor profile'), and names the concrete method ('GCS's 5-factor AI matching') with an explicit output ('Returns a 0-100 score'). This clearly distinguishes it from siblings like search_contracts or get_contract by emphasizing single-contract scoring.

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 use case is implied: call this when you have a specific contract_id and a contractor profile and want a fit score. However, there is no explicit guidance about when not to use it or how it relates to the similar-looking sibling win_likelihood, leaving the agent to infer the selection boundary.

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