Corridome

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds useful scope information by saying the record includes sector, ownership history, and deals, but says nothing about behavior when the id is unknown or about result size.

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?

A single compact sentence with the resource stated first and the returned fields enumerated after. No filler, nothing redundant.

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?

There is no output schema, so the description carries the burden of describing the return value, and it does so at a useful level of detail (sector, owners, deals). It falls short only on edge cases such as a missing company or the shape of the nested deal/ownership data.

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?

With a single parameter at 100% schema description coverage, the schema already explains that company_id accepts an id or a corridome.com address. The description adds no further meaning about the identifier, so the baseline of 3 applies.

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 names a specific resource (one portfolio company from the Corridome register) and enumerates what it returns: sector, owning firms, and deals. That distinguishes it clearly from get_deal and get_firm, which fetch other entity types. The only weakness is that the retrieval verb is implied by the name rather than stated.

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 gives no guidance on when to call this versus search_firms or search_people, nor any prerequisite such as needing an id from a prior lookup. The only routing hint (company_id comes from get_deal or get_firm) lives in the schema, not the description.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior, so the safety profile is covered. The description adds value beyond that by disclosing the shape of what comes back (parties, roles, value basis, provenance), which matters since no output schema exists. It stops short of noting behavior for an unknown or invalid deal_id.

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?

A single front-loaded sentence with no filler; the enumerated field list is dense but each item carries information. Slightly list-heavy prose, but nothing is redundant.

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 output schema, the return-value description is essential and present, and the single-param schema is fully documented. The only real gap is operational behavior for missing/invalid ids and no routing guidance to sibling tools, both minor for a simple lookup.

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?

There is a single parameter with 100% schema description coverage, including accepted id formats and where to obtain the id, so the schema already does the work. The description adds no additional meaning about deal_id, which is appropriate but earns only the baseline.

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 resource ('One deal from the Corridome register') and enumerates exactly which fields it returns (company, date, type, parties, value, filing), so an agent knows precisely what it retrieves. It implies a single-object fetch distinct from the search siblings, though it never names search_deals explicitly.

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?

There is no explicit when-to-use guidance, no exclusion rules, and no named alternative. The contrast with search_deals/get_firm is only inferable from the phrase 'One deal' and from the schema's mention that the id comes from search_deals or get_firm, which lives outside the description.

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

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

The credit-consumption rule is the key behavioral fact and it is disclosed twice, including the edge cases (no contact, LinkedIn-only, already opened this month). Auth requirements and error/not-found behavior are not covered, and the readOnlyHint=false plus a billing side effect is left for the agent to reconcile.

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?

Two sentences, both front-loaded with the highest-value information (what you get, then the optional paid expansion). The first sentence is a long semicolon-delimited list, which is dense but each item maps to a real returned section.

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?

There is no output schema, and the description compensates by enumerating the response sections, and the one costly parameter is fully explained. Nothing an agent needs to call this 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?

Schema coverage is 100%, so the baseline is 3; the description earns a notch by stating what include_contacts actually adds to the response (published business contacts for the named people) and by framing the credit rule at the tool level rather than only per-field.

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 opens with a specific verb+resource ("One firm from the Corridome register") and then enumerates the record's contents: identifiers, ADV funds, deals, relationships, portfolio companies, people. An agent can distinguish this single-firm detail fetch from search_firms without opening either schema.

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?

It gives clear conditional guidance on include_contacts (only when published contacts are needed, since each opened contact costs a credit). It never explicitly says to obtain firm_id from search_firms or when to prefer this over the sibling get_company/search_firms, so there is no named alternative.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed world), so the burden is lower. The description still adds real value by disclosing result ordering ("newest first") and the returned fields (company, date, type, value, parties, roles), which annotations do not carry.

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?

Two sentences, zero filler: the first carries all filter dimensions, the second carries return shape and ordering. It is front-loaded on the action and sized appropriately for a 14-parameter tool.

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 output schema, the description usefully spells out the return payload and ordering, which is the biggest gap it had to fill. It leaves pagination and total-result behaviour to the schema, which handles page/limit adequately, but says nothing about result-set size limits or empty-result semantics for a search tool this broad.

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% and every parameter carries a detailed schema description, including the subtle firm-state vs company distinction and the disclosed-value caveat. The description restates the filter axes at a high level ("the disclosed value and the year") without adding syntax or edge-case information beyond the schema, so baseline 3 applies.

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?

States a specific verb and resource ("Find deals in the Corridome register") and enumerates every filter axis, so the agent knows exactly what dimension set this tool spans. It does not name a sibling, so it never explicitly says why this rather than get_deal or search_firms, but the multi-filter framing makes the distinction inferable.

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?

Usage is implied by the filter list ("by company name, by a firm and its role and side..."), which tells an agent how to narrow results, but there is no explicit when-to-use, when-not-to-use, or alternative named. Nothing tells the agent to prefer get_deal when it already has an identifier.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds real value by projecting the response fields (id, name, kind, city, state, corridome.com address) in the absence of an output schema, but says nothing about matching behavior, result ordering, or empty-result handling.

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?

Two sentences, zero waste, with the searchable dimensions front-loaded and the return shape summarized second. Every clause carries information.

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 output schema, the description usefully compensates by describing the returned fields, and annotations cover the safety profile. The remaining gap is guidance on result limits/pagination and on choosing this tool over get_firm for detail lookups.

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 coverage is 100% and the property descriptions are rich, including the kind enum meanings and the SEC-number formats accepted by query. The description only restates the same dimensions and omits the limit parameter entirely, so it does not meaningfully exceed the schema baseline.

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?

States a specific verb and resource ("Find firms in the Corridome register") and enumerates the searchable dimensions: name, short name, SEC number, kind, state. It is clearly a search/list tool versus the get_firm sibling, though it never names get_firm to draw that contrast explicitly.

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?

Usage is only implied by the verb "Find" and the searchable fields; there is no explicit statement of when to use this versus get_firm (which presumably returns full firm detail) or the other search_* siblings. No exclusions or prerequisites are given.

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

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

Discloses the non-obvious cost model in detail: one credit per contact opened under include_contacts, with explicit exemptions (no contact, LinkedIn-only contact, already opened this month) — which also explains why annotations mark readOnlyHint=false despite a search. It also discloses return shape (id, name, title, firm, title-source document, published contact kinds) where no output schema exists.

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?

Two sentences, front-loaded with purpose then return/cost information, with no filler. Slightly dense in the second sentence, but every clause carries actionable content.

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 nine parameters, no required fields, no output schema, and a credit-consuming option, the description covers what is searched, what comes back, and the billing consequence. Nothing an agent needs to call it safely 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?

Schema coverage is 100%, so all nine parameters are already documented, and the description largely restates them at a summary level. It adds a small amount of connective meaning (firm_id sourced from search_firms or a corridome.com address, include_contacts being the credit-consuming path), so baseline 3 is right.

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?

States a specific verb+resource ('find people at firms in the Corridome register') and enumerates the filter axes (name, title, firm, firm kind, state, contact kind) plus what is returned. The people-vs-firms-vs-deals distinction from siblings (search_firms, search_deals, get_firm, get_company) is unambiguous from the resource named.

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?

Usage is implied rather than stated: the agent can infer this is the filtered-list tool for people, and firm_id's description points to search_firms as the source of an id. But there is no explicit when-to-use/when-not or guidance on choosing paginated search versus get_firm for a known firm's roster.

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