check_crm

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

With no annotations, the description carries the full disclosure burden. It goes beyond a basic summary by revealing exact case-sensitive matching, the indistinguishable {'found': False} failure mode, and instructions to never normalize or guess the name. It does not describe broader return details or explicitly state read-only behavior, but 'Look up' and the output schema partially cover that.

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 main description is a concise two-clause sentence with no filler. The parameter description is longer but every sentence earns its place by documenting matching rules, failure behavior, and usage constraints. The critical instruction about using lookup_lead is front-loaded in the parameter documentation.

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 single-parameter tool with an output schema, the description is complete. It explains what data is returned conceptually, how to source and format the parameter, what happens on a mismatch, and what failure looks like. No critical operational detail needed to call the tool correctly 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?

Although schema coverage is 100%, the description adds substantial meaning: the value must be the exact company.name from lookup_lead, matching is case-sensitive, common invalid forms like 'acme robotics' or 'Acme' are matched exactly and case-sensitively against CRM', and 'a ghost contain' will return {'found': False}' and is indistinguishable from no record. It also says to pass a name, not an id. This is far beyond the schema's basic string declaration.

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 ('Look up') and resource ('a company's CRM history') and names the concrete data areas ('deals and support tickets'). It clearly distinguishes check_crm from siblings like lookup_lead, score_lead, and search_knowledge by scope.

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 clear context: use this to retrieve CRM history. The parameter description adds strong operational guidance, explicitly requiring the company name to come verbatim from lookup_lead and forbidding guessing or deriving from email domains. It does not explicitly state when not to use it versus specific alternatives, but the purpose and sibling names make the intended use clear.

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