search_mca_companies

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

No annotations are provided, so the description carries the full burden. It mentions fuzzy matching, optional filters, and pagination, which is useful, but it does not disclose rate limits, return format, result count limits, or whether the search is case-insensitive or how pagination behaves. For a read/search tool this is acceptable but far from transparent.

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?

One sentence with a clear subject and qualifiers. It front-loads the core behavior ('fuzzy company-name search') and packs in optional filters plus pagination. No wasted words, though it could have added a sentence on usage alternatives.

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?

With no annotations and no output schema, the description is the only guidance. It explains the searching behavior, but lacks explicit guidance on when to use search vs lookup_mca_company, expected result shape, and any behavioral details like limit or ordering. Given the sibling set and the existence of a very similar 'lookup' tool, this is a notable gap.

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 only 50%: state and status have descriptions, but name and page do not. The description adds meaning by clarifying that the search is fuzzy and that state/status are optional filters, and pagination is paginated. It does not add detail on the page parameter's semantics beyond the schema, but the overall behavior is clarified enough for an agent to use the parameters correctly.

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 ('search') over a specific resource ('MCA registry') with fuzzy matching, optional state/status filters, and pagination. It does not explicitly differentiate from sibling lookup_mca_company, but the word 'search' vs 'lookup' and 'fuzzy' implies it. A clear purpose statement overall.

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?

No explicit guidance on when to use this tool vs alternatives. Siblings include lookup_mca_company (exact lookup) and other registry tools, but the description does not mention them or exclusion criteria. The context implies a fuzzy search use case, but nothing is stated.

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