Seventeen read only tools over cited company, portfolio and country data for bank credit desks.
Scored across 17 tools
Most tools target clearly distinct data surfaces, and the descriptions carefully flag id-space differences such as node_id versus entity_id. The only likely confusions are adjacent pairs like company_financials versus company_financing and developments versus screening_lookup, but their descriptions resolve those boundaries.
Names are uniformly lowercase snake_case and mostly follow a resource/domain pattern such as company_*, portfolio_*, *_profile, and *_book. The two search_* tools and the noun-plus-lookup form of screening_lookup are minor deviations, but the overall naming pattern remains predictable.
At 17 tools the set sits just above the typical 3-15 sweet spot, but the breadth of the Stonewake domain justifies the count: registry data, financials, debt, ownership, country risk, deals, research, screening, and portfolio monitoring. Each tool has a distinct role and none feels redundant.
The surface covers the main read-and-monitor workflows: company discovery, registry records, events, financials, financing, ownership, country risk, deal book, developments, screening, portfolio health, and scoring. Minor gaps exist, such as no registry-participant name search feeding company_profile's entity_id and no direct deal-by-company filter, but these can be worked around.
The register event feed of one company: filings, status changes, and other register happenings, grouped into display rows and ordered by significance tier, each row citing its evidencing record where one exists. Takes node_id, the graph node id from search_companies hits. Related events arrive folded into one rollup row with a member_count and a group_key; pass that group_key as group to expand one rollup into its member events.
| Name | Required | Description | Default |
|---|---|---|---|
| group | No | A group_key from a previous response; expands that one rollup into its member events. | |
| node_id | Yes | The graph node id, as returned by search_companies hits. Not the entity_id of company_profile. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavioral detail beyond the readOnly/idempotent annotations: events are grouped into display rows, ordered by significance tier, each row cites an evidencing record where one exists, and related events are folded into rollup rows with member_count and group_key. This gives the agent a strong mental model of the tool's behavior.
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 dense sentences that front-load the core purpose and then provide the necessary input and rollup-expansion instructions. Every sentence contributes meaningful information with no filler or repetition.
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 there is no output schema, the description does a good job explaining the expected return structure: display rows, significance tiers, evidence citations, and rollup expansion. It covers both parameters and gives enough context for an agent to call the tool correctly and interpret its results.
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?
The input schema already describes both parameters with 100% coverage. The description adds extra value by contextualizing node_id as coming from search_companies and by explaining that group is a group_key from a previous response used to expand a rollup. This goes slightly beyond the schema's field-level documentation.
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 clearly identifies the tool as a register event feed for one company, listing specific content types (filings, status changes, other register happenings). It also describes the output structure (display rows, significance ordering, evidencing record citations), which distinguishes it from sibling tools like company_financials or company_profile.
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 clear input guidance by stating that node_id must come from search_companies hits and explicitly warns against using the entity_id of company_profile. It also explains how to use the group parameter for expanding rollup rows. It does not explicitly name alternative tools or state when not to use it, but the usage context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Every financial figure for one company, newest reporting period first, each figure citing the source record it came from (a public register, a public filing repository, or the annual financial report the issuer published on its own website). Takes node_id, the graph node id carried by search_companies hits (not the entity_id of company_profile). Figures are served as filed at the source, except a figure with derived true, which the filing does not state and which was calculated from two figures the same filing states; its derivation says how in plain words. A missing period means nothing was filed, not zero.
| Name | Required | Description | Default |
|---|---|---|---|
| node_id | Yes | The graph node id, as returned by search_companies hits. Not the entity_id of company_profile. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and idempotentHint annotations, the description adds important behavior: figures are served as filed (no adjustments), except derived figures which are calculated and explained. It also clarifies that a missing period means 'nothing filed', not zero. This is valuable context on data provenance and interpretation. Slight deduction because it doesn't mention rate limits or error cases, but it's strong.
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 a single, dense paragraph but is well-structured: it starts with the core purpose, then input specifics, then data semantics. It's front-loaded with the purpose. All sentences add value, but it could be broken into bullet points for easier scanning, hence 4 rather than 5.
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 is simple (one parameter, annotations for read-only/idempotent) and the schema is fully descriptive of the parameter, the description covers the essential semantics: data ordering, source citations, derived figures, and missing period handling. It doesn't describe the output structure but no output schema is provided; however, the nature of financial figures is understandable. It's complete enough for an agent to call correctly.
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 the schema already describes node_id as the graph node id from search_companies (100% coverage), the description reinforces the distinction from company_profile's entity_id and explains the source of the id. This adds clarity beyond the schema, making it more than just a baseline 3.
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 clearly states it provides financial figures for a single company, ordered by reporting period, with source citations. It distinguishes itself from siblings like company_profile by focusing on financials, and from search_companies by being a per-company data tool rather than a search tool. However, it does not explicitly name a sibling for contrast, so it falls short of a 5.
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 explicitly tells the agent when to use this tool: when financial figures for one company are needed, and it gives a precise input instruction: use node_id from search_companies, not entity_id from company_profile. This is a clear when-to-use and what-not-to-use, which is excellent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The debt surface of one company: registered charges with status lines and bound lenders, listed debt instruments, filed debt position facts, derived aggregates, a maturity wall, and per section coverage states saying how complete each section is. Takes node_id, the graph node id from search_companies hits. Long instrument books fold into the maturity wall; pass bucket (within_12m, 1_to_2y, 2_to_5y, beyond_5y, or no_maturity) to expand one maturity slice, and include_matured true to also list matured instruments.
| Name | Required | Description | Default |
|---|---|---|---|
| bucket | No | Expand one maturity-wall slice into its instruments. | |
| node_id | Yes | The graph node id, as returned by search_companies hits. Not the entity_id of company_profile. | |
| include_matured | No | Also list matured instruments, default false. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: long instrument books fold into the maturity wall, bucket expands one slice, and include_matured defaults to false. It does not describe pagination or response shape, but with no output schema and a read-only tool, the description carries the burden well.
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 dense but well-organized: it front-loads the tool's purpose, then explains the key parameter semantics in two sentences. Every sentence earns its place, and the optional-parameter guidance is compact and unambiguous.
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 read-only tool with 3 parameters and no output schema, the description covers the purpose, the required input, the optional parameters, and the key behavioral nuance (folding into maturity wall). It could mention what the response looks like or whether results are paginated, but the description is strong enough that an agent can call it correctly without further context.
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%, so the schema already documents all three parameters. The description adds meaning by explaining the relationship between bucket and the maturity wall, and by clarifying that node_id is the graph node id from search_companies hits, not the entity_id. This goes beyond the schema's field-level descriptions.
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 precise noun phrase ('The debt surface of one company') and enumerates the distinct sections: registered charges, listed debt instruments, filed debt position facts, derived aggregates, a maturity wall, and per-section coverage states. This clearly distinguishes it from sibling tools like company_financials (financial statements) and company_profile (general company data).
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 explicitly states the required input ('Takes node_id, the graph node id from search_companies hits') and clarifies it is not the entity_id of company_profile. It also gives concrete usage guidance for optional parameters: pass bucket to expand a maturity slice, and include_matured true to list matured instruments. This is actionable and complete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One registry row's identity from the closed Stonewake registry of named market participants (export credit agencies, multilaterals and banks, plus the trade publications deals cite): slug, display name, full name, kind, country, aliases, and group memberships. Takes entity_id from the registry's own id space. This is NOT the node_id that search_companies returns and entity_risk_profile takes; the two id spaces are different, and an id from the wrong space answers not_found.
| Name | Required | Description | Default |
|---|---|---|---|
| entity_id | Yes | The registry entity id. Not a graph node_id from search_companies. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, non-destructive behavior. The description adds useful behavioral context: the registry is closed, a wrong-space id returns not_found, and the response is a single identity row with named fields.
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 the resource and returned fields, followed by a critical id-space warning. There is no repetition 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 single-parameter read tool with no output schema, this is complete: it describes the returned data, the required id space, the failure behavior, and the relevant siblings. No missing information blocks a correct call.
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, but the description goes beyond the schema by naming both tools that use the node_id and stating the failure mode for a wrong id-space. That extra context helps the agent know exactly what entity_id to pass.
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 the resource ('one registry row's identity from the closed Stonewake registry') and lists the exact fields returned. It also explicitly distinguishes this tool from search_companies and entity_risk_profile, so an agent can tell it apart from siblings.
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 clearly states the input contract (registry entity_id, not node_id) and names the sibling tools that use the other id space. It doesn't spell out a positive 'use when...' rule, but the id-space warning makes the selection condition unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The register records behind one company, a page at a time. Each row is a citation (register, record type, identifier, source URL, retrieval date), newest first. Takes node_id, the graph node id from search_companies hits. Every page states records_total, the company's whole count, and registers, each register's connector_id, name and count; pass one connector_id to page that register alone. A company listed in a securities register can hold over 100,000 records, so page with limit (default and maximum 25) and offset, and read registers first to decide what to page.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Page size, default and maximum 25. | |
| offset | No | Rows to skip, default 0. | |
| node_id | Yes | The graph node id, as returned by search_companies hits. Not the entity_id of company_profile. | |
| connector_id | No | One register to page, as a registers row names it; omit it to page every register newest first. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnly, idempotent, and non-destructive behavior, and the description builds on this by adding ordering, pagination shape, records_total and registers counts, and a scale warning about securities registers exceeding 100,000 records. It also discloses default and maximum limits. No contradiction with annotations.
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 front-loaded with the core purpose, followed by input requirements, pagination behavior, and a scale caveat. Every sentence adds operational information, and there is no filler or repetition of the schema.
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 carries the full burden of explaining the return shape, and it does so thoroughly: row fields, newest-first ordering, records_total, registers entries with connector_id and counts, and how to page a single register. This is sufficient for correct 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%, with defaults and constraints already documented for all four parameters. The description paraphrases the node_id source and connector_id selection, but it does not add new semantic meaning beyond the schema, which is the baseline 3 case.
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 clearly identifies the tool's resource and operation: retrieving the register records behind one company, a page at a time. It specifies the row shape (register, record type, identifier, source URL, retrieval date) and ordering (newest first), which differentiates it from sibling tools like company_events and company_financials.
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 actionable guidance: use node_id from search_companies hits, read the registers list first to choose a connector_id, and page with limit and offset. It does not explicitly name alternative tools, but it supplies enough context to know when and how to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Country intelligence for export finance. Without iso3 this returns the index of covered countries with each one's risk score and the caller team's live deal rollup. With iso3 (a three letter ISO 3166-1 alpha-3 code such as TUR) it returns one country in depth: the risk score with its cited component breakdown, indicator values, membership lists with legal citations, reference events, and the team's deals there. Indicator and dataset entries carry attribution fields such as attribution_text stating the data licence terms; preserve that attribution whenever values are quoted onward.
| Name | Required | Description | Default |
|---|---|---|---|
| iso3 | No | ISO 3166-1 alpha-3 country code; omit to list every covered country. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the bar is lower. The description adds genuine non-obvious behavior beyond those annotations: the dual-mode response shape, the presence of legal citations, and the actionable attribution obligation ('preserve that attribution whenever values are quoted onward'). No contradiction with annotations 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?
The description is front-loaded with the domain purpose and flows logically from the no-arg mode to the arg mode to the attribution obligation. It is longer than the minimal case but every sentence carries distinct information with no repetition of schema fields. Each clause earning its place earns it a strong score.
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 carries the full burden of explaining return values, and it does so thoroughly for both modes, including the attribution field requirement. Given the low parameter count and simple schema, little is missing; only finer details like pagination or response size limits are absent, which are minor for a single-country 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?
Schema coverage is 100%, so the baseline is 3, but the description adds real value beyond the schema: a concrete example value (TUR), the exact format constraint (three-letter ISO 3166-1 alpha-3), and the behavioral consequence of omitting versus supplying the parameter. The schema describes what the parameter is; the description explains what changes based on it.
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 scope statement, 'Country intelligence for export finance,' and precisely defines two return modes (index versus in-depth country report) tied to parameter presence. The resource is unambiguous and the content lists are concrete (risk score, indicators, memberships, reference events, deals). It does not explicitly name a sibling to differentiate from, though country-level scope is clearly distinct from the company/entity/deal siblings.
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 clear conditional guidance on how to invoke the tool: omit iso3 for the index, supply it for the deep dive, including an example code (TUR). However, it never states when to choose this tool over alternatives such as entity_risk_profile or screening_lookup, nor any exclusions. Mode-level guidance is strong, but cross-tool routing is absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The deal book of the one team the caller's key reads; every row names that team (team_id, team_name). Without deal_id this lists deals ordered by their ranking window first (financing open, early stage, not confirmed, financing closed, cancelled) and the chosen sort inside it, filterable by stage, window, country_code (ISO country codes), sector, status, eca, eca_named (only deals naming an export credit agency), minimum contract value (min_value_usd), and free text (q); sort by score (default), last_activity, value, or first_seen; paged with limit (default 50, maximum 100) and offset, with the exact total. Dismissed deals are excluded unless status asks for them, and the portfolio rows a desk holds back by default (closed, cancelled, older than the stale window of 18 months by default, own bank, domestic; score_hidden true) are off the page unless include_hidden is true, and score_own_bank marks the rows where your own bank is a lender. A row carrying merged_into was found to be a duplicate and folded into the deal that field names: read that deal instead, and expect this one to be dismissed. Each row carries its window (score_window and its label), the band word and reason count behind its score (score_band, score_reason_count), the confirmed state over its linked findings (state, state_label), the newest quote backed event date (event_date, null when no source stated one), the lender names on the deal (lenders), and the two derived sentences a desk reads first: angle (why the row is on the list) and ask (what is still to be financed, read from the confirmed state, the window, the agencies and the lenders; a row whose state no source confirmed reads State not confirmed by a source yet). With deal_id (the deal_id field of list rows) it returns one deal in full: score_reasons, one plain sentence per scoring component saying which fact it matched, alongside parties carrying entity_id and node_id where bound, the cited timeline with press quotes (each entry also carrying the state its quote confirmed, the confirming passage and the event date), lifecycle events, sources each carrying source_tier (1 a primary source, 2 trade press, 3 an aggregator, which is also where an unclassified publisher lands) and its tier_label, the deal summary (summary_lines: three lines generated from the cited findings by fixed rules, not by a model, each with the finding and quote behind every field it states), the analyst's own next_action, and economics.
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Free-text filter over deal names and summaries. | |
| eca | No | Keep only deals naming this export credit agency. | |
| sort | No | Ranking, default score. | |
| limit | No | Page size, default 50, maximum 100. | |
| stage | No | Keep only these lifecycle stages. | |
| offset | No | Rows to skip, default 0. | |
| sector | No | Keep only these sectors. | |
| status | No | Keep only these statuses; dismissed deals appear only when asked for here. | |
| window | No | Keep only these ranking windows: financing_open, early_stage, not_confirmed, financing_closed, cancelled. | |
| deal_id | No | A deal_id from the list; when present the other arguments are not used. | |
| eca_named | No | Keep only deals naming an export credit agency. | |
| country_code | No | Keep only deals in these ISO country codes. | |
| min_value_usd | No | Keep only deals at or above this contract value in USD. | |
| include_hidden | No | Also serve the rows a desk holds back by default (closed, cancelled, older than the stale window, own bank, domestic); off by default. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even though annotations already indicate read-only, idempotent, non-destructive behavior, the description adds substantial behavioral context: dismissed-deal exclusion, hidden-portfolio-row defaults, merged_into duplicate handling, null event dates, source tier semantics, and summary_lines generated by fixed rules rather than a model. None of this contradicts the annotations.
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 information-dense and nearly every clause matters, but it is a single unbroken paragraph with long enumerations and semicolons. It would be easier for an agent to parse if the list-mode and deal-detail-mode behaviors were separated or bulleted, and the opening sentence is awkwardly phrased.
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 carries the full burden of explaining return values, and it does so thoroughly: list-mode ordering, filtering, pagination, row fields, detail-mode fields, source tiers, edge cases for duplicates and hidden rows, and analyst-facing outputs are all covered. This is complete enough for an agent to select and invoke the tool correctly.
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%, but the description still adds meaningful parameter semantics: deal_id overrides all other arguments, status can reveal dismissed deals, include_hidden unlocks portfolio-held rows, min_value_usd is a floor, sort has a default, and limits/offsets are explained. This goes well beyond the schema's basic field labels.
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 clearly identifies the resource (the team's deal book) and the two main operations: listing deals or fetching one deal in full with deal_id. It is specific about behavior and return contents, though it does not explicitly differentiate this tool from siblings like portfolio_book.
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 clear context for when to use each mode: without deal_id it lists/filters/pages; with deal_id it ignores other arguments and returns full deal details. It also explains default exclusions and the include_hidden override, though it never mentions alternative tools or when not to use this one.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Dated, cited developments surfaced by your team's research runs, the runs of the one team the caller's key reads: grounded findings with a headline, category, verification state, and corroborating source count. Without run_id this is a feed paged with limit (default 25, maximum 100) and offset, with the exact total; sort is recent (default) or score. Each row names the run_id it came from and its team (team_id, team_name); pass run_id to load that whole research run with its grounded findings, press quotes, and cited sources. Another team's run_id answers not found, like an unknown one.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Feed order: recent (default) or score. | |
| limit | No | Page size, default 25, maximum 100. | |
| offset | No | Rows to skip, default 0. | |
| run_id | No | A run_id from a development row; when present the other arguments are not used. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds operational behavior beyond annotations: pagination with exact total, sort options, the precedence of run_id over other args, and the not-found behavior for foreign/unknown run_ids. This meaningfully extends the agent's understanding without contradicting annotations.
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 a single, dense paragraph that front-loads the core purpose and then details feed and run behaviors. It is not overly verbose; every sentence contributes functional information. The structure could be slightly clearer with separation of modes, but it remains efficient and scannable.
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 read-only feed tool with no output schema, the description covers the key invocation details: pagination, sorting, run_id override, access restrictions, and row content. It doesn't spell out the exact JSON response structure, but given the tool's simplicity and the description's coverage, an agent has sufficient context to make correct calls and interpret results reasonably.
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%, so each parameter is already documented. The description adds cross-parameter semantics: without run_id it's a pageable feed, with run_id the other arguments are ignored. It also specifies default/max for limit and sort defaults, which the schema already includes but the description reinforces the behavioral interplay, adding value beyond the schema.
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 clearly states the resource (dated, cited developments from research runs) and what it contains (headline, category, verification state, corroborating source count). It distinguishes this tool from the sibling company-focused tools by tying outputs to research runs and the caller's team scope. The dual feed/run modes are explicit, so an agent can infer the tool's purpose without needing the 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?
The description explains the two usage modes (feed vs. run_id lookup) and notes that run_id overrides other parameters. It clarifies that another team's run_id returns not found, setting expectations. However, it does not name any sibling alternatives or explicitly state when to prefer this tool over others, though the context makes it clear this is for research findings rather than company data.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The caller team's credit-risk view of one company, by its graph node_id (the id search_companies hits carry). Answers one of three honest shapes: not in the portfolio (in_portfolio false), held but not yet assessed (assessment null), or the full current assessment with its status band, score, seen_share, explained_share and reachable_share (the figure the insufficient floor reads), a coverage_line of one to three sentences counting covered signals and gaps with their reasons, and every signal with its state (evidenced, register_quiet, gap, awaiting_bank_input, not_applicable), gap_reason, evidence grade (A to D), evidence value, note, and citation ids. A signal no connected source reaches for the company's jurisdiction is a gap, never not_applicable. A held company also carries entity_class: the class its checks route on (a bank is never scored on corporate distress models) and its source, either your team's analyst override or the register rule that derived it. Company nodes only; person lookups answer not_found.
| Name | Required | Description | Default |
|---|---|---|---|
| node_id | Yes | The graph node id, as returned by search_companies. Not the entity_id of company_profile. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/openWorld/idempotent/destructive annotations, the description richly discloses return behavior: the three possible honest response shapes, when assessment is null, the distinction between gap and not_applicable, the meaning of reachable_share, and how entity_class is derived. This is substantial behavioral context that an agent cannot infer from schema or annotations.
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 dense and long, but nearly every clause carries load-bearing meaning about response shapes, signal semantics, or edge cases. The core purpose is front-loaded in the first sentence, and the detail is necessary because there is no output schema. Some restructuring into paragraphs would improve readability, but it earns its length.
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 one parameter, rich annotations, and no output schema, the description is remarkably complete. It explains all major output branches, the coverage line, signal states, evidence grading, gap semantics, entity_class routing, and the company-only limitation. An agent has enough information to invoke the tool correctly and interpret its results.
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?
The schema already documents node_id well, including that it is from search_companies and not company_profile's entity_id. The description adds useful domain semantics on top: the node_id must refer to a company node, and person nodes will produce not_found. Since schema coverage is 100%, the baseline is 3, and this extra company-only constraint justifies a 4.
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 ('credit-risk view of one company') and the exact keying mechanism ('graph node_id ... the id search_companies hits carry'). It differentiates from siblings by specifying that it is not the company_profile entity_id and that persons answer not_found, so the agent knows exactly what this tool is and is not for.
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 concrete usage context: use it for company nodes with a graph node_id, and explicitly says person lookups answer not_found. It also tells the agent where the node_id comes from (search_companies) and what not to pass (entity_id from company_profile). It does not explicitly name alternatives like scoring_rubric, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The upward ownership chains of one company, composed across registers and cited hop by hop, with per register coverage notes. Takes node_id, the graph node id from search_companies hits. threshold is the minimum ownership percentage a chain must keep to be followed, default 25; max_depth caps the number of hops, default and maximum 8. Served owners are organizations; a chain reaching an individual terminates there with a stated terminal reason. Hop values are served verbatim from the registers, never synthesized.
| Name | Required | Description | Default |
|---|---|---|---|
| node_id | Yes | The graph node id, as returned by search_companies hits. Not the entity_id of company_profile. | |
| max_depth | No | Maximum hops to walk, default and maximum 8. | |
| threshold | No | Minimum ownership percentage a chain must keep, default 25. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: hop values are served verbatim from registers, never synthesized; chains terminate at individuals with a terminal reason; per-register coverage notes are included. This goes beyond the annotations.
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 compact and front-loaded: it opens with the core purpose, then explains parameters and behavioral guarantees in a logical order. Every sentence earns its place; no fluff or repetition of schema details.
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 read-only, idempotent tool with no output schema, the description covers the input semantics, the traversal behavior, the termination condition, and the data provenance guarantee. It doesn't describe the exact output shape, but with no output schema and a clear behavioral description, this is adequate. A minor gap is not stating what happens when no chain is found, but that's not critical.
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%, so the schema already documents all three parameters. The description adds meaning by explaining the semantics of threshold ('minimum ownership percentage a chain must keep to be followed') and max_depth ('caps the number of hops'), and clarifies node_id is the graph node id from search_companies hits, not entity_id. This is above the baseline 3.
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 ('Takes', 'Served', 'followed') and resource ('upward ownership chains of one company, composed across registers and cited hop by hop, with per register coverage notes'). It clearly distinguishes from siblings like company_profile or search_companies by focusing on ownership chains and graph node ids.
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?
Explicitly says 'Takes node_id, the graph node id from search_companies hits' and contrasts with 'Not the entity_id of company_profile' in the schema. It also explains threshold and max_depth semantics, and notes that chains terminate at individuals with a stated terminal reason. This gives clear when-to-use and what-to-avoid guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The monitored book itself: one row per exposure with the team whose book holds it (team_id, team_name), its label, register identifier, entity class (corporate, sovereign_or_public_body, bank, spv or fund, derived from register-stated facts and null when none has been derived yet), desk, current status band, score, completeness, seen_share (the weight share of applicable signals actually observed), explained_share and reachable_share (the observed share of what a connected source can serve, the figure the insufficient floor reads), the top contributing signals with their citation ids, the most recent status change, and the standing credit review (disposition, note, next review date, and whether that date has passed). Ordered most severe first (red, amber, insufficient, not_assessed, green). Paged with limit and offset; the response carries the exact total. Set include_inactive true to include exposures no longer actively monitored.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Page size, default 50, maximum 100. | |
| offset | No | Rows to skip, default 0. | |
| include_inactive | No | Include exposures no longer actively monitored. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds meaningful behavioral context beyond annotations: ordering by severity, pagination with limit/offset, exact total in the response, and the effect of include_inactive. This is useful and non-redundant.
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 dense and informative but structured as one long run-on sentence that lists many fields. Every piece of information is relevant, but the lack of clear separation between output fields, ordering, and paging makes it harder to parse quickly.
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 full burden of explaining the return value. It thoroughly enumerates the fields, explains derived values like entity class and seen_share, specifies ordering, and covers pagination and the include_inactive behavior. Nothing critical for calling 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?
Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining how limit/offset control paging, that the response carries the exact total, and what include_inactive does. This goes beyond the schema's basic parameter descriptions.
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 clearly identifies the resource as 'the monitored book itself' and specifies that it returns one row per exposure with a detailed set of fields. It is distinct from sibling tools like portfolio_overview by focusing on the book's exposure-level data, though it does not explicitly name an alternative.
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 implies usage as a list/read operation for the monitored book and gives specific guidance on the include_inactive parameter. However, it does not state when to choose this tool over siblings such as portfolio_overview or deal_book, and there are no explicit exclusions or alternative conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Preview adding a book of companies to the caller team's monitored portfolio. Pass the book as CSV text whose header is identifier_type,identifier plus, optionally, name, currency, limit_amount and drawn_amount; at most 2,000 rows. Every row is matched by its registry identifier alone, where identifier_type is lei, uk_crn, de_register (register type, number and court, for example HRB 275806 München), us_cik or another national register scheme. The name column is echoed back and never used to match. Each row answers its outcome (add, reactivate, in_book, duplicate, ambiguous, unresolved, invalid), a reason, and the matched node_id and register name. Rows are paged with limit and offset in file order; counts and total always cover the whole file, so page on until offset reaches total. Nothing is written, and applying an import happens in the Stonewake dashboard.
| Name | Required | Description | Default |
|---|---|---|---|
| csv | Yes | The book as CSV text, header row first. | |
| limit | No | Page size, default 100, maximum 100. | |
| offset | No | Rows to skip, default 0. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent/non-destructive annotations, the description explicitly states 'Nothing is written' and names the external place where the actual write occurs. It also reveals useful behavior: name is only echoed and never used to match, and paging counts are file-wide rather than page-scoped.
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 dense but well organized: purpose, input format, matching behavior, per-row output, paging, and side effects each get one clear clause. No sentence is filler or redundant with the schema.
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 complex tool with no output schema, it lists the per-row outcome categories (add, reactivate, in_book, duplicate, ambiguous, unresolved, invalid), reason, matched node_id and register name, plus paging totals. The agent has what it needs to call the tool correctly and interpret the preview results.
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 the schema already describes the three parameters, the description adds critical semantics for csv: header requirements, allowed identifier types with an example, the 2,000-row limit, and the meaning of the optional columns. It also enriches limit/offset with the file-order and whole-file-count semantics, which the schema does not mention.
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 and object: 'Preview adding a book of companies to the caller team's monitored portfolio.' It distinguishes the tool from siblings by framing it as a preview rather than an applied mutation and closes by noting the actual import happens in the Stonewake dashboard.
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 specifies the exact input format (CSV text with required header and optional columns), the 2,000-row cap, how rows are matched, and the paging rule ('page on until offset reaches total'). It also gives an explicit when-not: nothing is written and applying happens in the dashboard.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Current health of the monitored portfolio: how many exposures sit in each status band (green, amber, red, insufficient, not_assessed), the active exposure count, the number of transitions in the last 30 days and how many of them are status changes (an exposure's first assessment is an addition to the book, a transition but not a change), and how many exposures have an overdue credit review. Optionally pass transitions_since (an ISO 8601 date-time) to also list the individual status transitions since that moment, newest first, each with its cause: the signals whose change moved the status, their citation ids, and the register record behind the lead one. Start here for questions like how the book is doing or what changed since a date and why.
| Name | Required | Description | Default |
|---|---|---|---|
| transitions_since | No | Also return status transitions at or after this ISO 8601 date-time, newest first. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond the annotations: it explains the subtle distinction that an exposure's first assessment is a transition but not a status change, and it details what the transitions_since mode returns (causes, citation ids, register record). This is meaningful behavioral disclosure that helps the agent interpret results correctly.
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 a single dense paragraph that front-loads the core purpose and then expands into the optional mode. It is longer than ideal but every clause adds information: the status bands, the transition/change distinction, the overdue review count, and the transitions_since behavior. The final sentence acts as a usage guide. It could be split into two sentences for readability, but it is not bloated.
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 read-only tool with one optional parameter and no output schema, the description covers the key information an agent needs: what the tool returns, the meaning of the optional parameter, and the semantic distinction between transitions and changes. It does not describe the exact response shape, but with no output schema and a read-only annotation, the description carries the burden well. A perfect score would require explicit mention of pagination or response format, but those are minor gaps.
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%, so the schema already documents the transitions_since parameter. The description adds value by explaining what the parameter triggers (listing individual transitions with causes) and the ordering ('newest first'), which goes beyond the schema's basic description. The baseline is 3 for full coverage, and the description earns a 4 by adding behavioral meaning to the parameter.
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 and resource ('Current health of the monitored portfolio') and enumerates the exact metrics returned: status bands, active exposure count, transitions, status changes, overdue reviews. It also distinguishes the optional transitions_since mode, which lists individual transitions with causes. This clearly differentiates it from siblings like portfolio_book and company_events.
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 explicitly says 'Start here for questions like how the book is doing or what changed since a date and why.' This gives the agent a clear trigger condition and implies it is the first tool to try for portfolio health questions. It also explains when to use the optional parameter, making the usage context unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
How scores are produced for the caller's team: the live scoring configuration (signal weights, status thresholds, evidence-coverage floor; version null means the built-in desk default is active) together with the team's stored rubric versions, newest first. Use this to interpret the status bands and scores that the portfolio and risk tools return.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a read-only, idempotent, non-destructive operation. The description adds valuable behavioral context by explaining the version null meaning, the ordering of rubric versions (newest first), and the distinction between live configuration and stored versions. This goes beyond what annotations alone provide.
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 concise and well-structured, with the primary purpose stated upfront and supporting details provided in a compact parenthetical. The second sentence gives a clear usage directive without redundancy. Every sentence contributes meaningful 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?
Given there is no output schema, the description sufficiently enumerates what the tool returns: live scoring configuration (signal weights, status thresholds, evidence-coverage floor, version) and stored rubric versions newest first. It also explains the intended interpretation use case. No critical information is missing for an agent to invoke and understand this tool effectively.
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?
The input schema has zero parameters, so there are no parameter semantics to clarify. The description appropriately focuses on the tool's return content instead. This matches the baseline for a no-parameter tool.
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 clearly states the tool's purpose: it explains how scores are produced for the caller's team by returning the live scoring configuration and stored rubric versions. It identifies specific content elements (signal weights, status thresholds, evidence-coverage floor) and distinguishes itself from sibling tools focused on search, profiles, and portfolio data.
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 explicitly tells the agent when to use this tool: to interpret status bands and scores returned by portfolio and risk tools. While it does not name alternative tools or state when not to use it, the provided context is clear enough for an agent to select it appropriately among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Adverse media screenings run for the caller's team, covering organizations and countries; each row names its team (team_id, team_name; both null on a workspace wide screening every team reads). Without screening_id this lists screening runs newest first, filterable by subject_type (entity or country), by the subject's ids (node_id for a company from search_companies, entity_id for a registry institution from company_profile, iso3 for a country), or by subject name; paged with limit (default 20, maximum 100) and offset, and the response carries the exact total. With screening_id it returns that one run in full: per category verdicts with rationale and review state, the drafted summary, grounded findings with their press quotes, and the sources behind them. Findings quote reported coverage, not established fact.
| Name | Required | Description | Default |
|---|---|---|---|
| iso3 | No | Filter by the screened country's ISO alpha-3 code. | |
| limit | No | Page size, default 20, maximum 100. | |
| offset | No | Rows to skip, default 0. | |
| node_id | No | Filter by the subject's graph node id. | |
| subject | No | Filter by subject name, matched on its normalized form. | |
| entity_id | No | Filter by the subject's registry entity id. | |
| screening_id | No | A screening id from the list; when present the other arguments are not used. | |
| subject_type | No | Filter the list by subject kind. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is clear. The description adds significant behavioral context: it warns that findings quote reported coverage, not established fact, and explains that a workspace-wide screening has null team fields. It also discloses pagination behavior and that the list is newest first.
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 a single, dense paragraph but well-structured: purpose first, then the two modes. It is not overly verbose given the complexity, but could benefit from bullet points for clarity. Still, it is efficient.
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?
The description covers both modes comprehensively, lists all filter options, explains pagination, and provides a high-level view of the response contents. It even includes the caveat about findings. For a tool with no output schema and 8 optional parameters, this is complete.
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 baseline is 3. The description adds value by mapping node_id to search_companies, entity_id to company_profile, and iso3 to country, plus clarifying that screening_id overrides other arguments. It also explains the meaning of limit/offset pagination and the exact total in response.
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 (lookup of adverse media screenings) and clearly distinguishes two modes (list vs. full run). It also explains the scope (caller's team) and that it covers organizations and countries. This differentiates it from sibling tools like company_profile or search_companies.
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 explains the two modes: without screening_id it lists runs, with it returns full details. It also specifies which filter parameters apply to which subject types (e.g., node_id for a company from search_companies). However, it does not explicitly mention when to use this tool over alternatives or provide exclusions, so it falls short of a full usage guide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find a company by name or identifier. The query can be a scheme-prefixed identifier such as lei:5493001KJTIIGC8Y1R12, a bare registration number (CRN, CIK, LEI and similar shapes), or a company name (matched exact, then prefix, then token, then fuzzy). Hits carry the graph node_id that entity_risk_profile takes, plus jurisdiction, status fields, and register identifiers. connected_sources names the registers an empty result was searched against. Companies only; persons are never returned.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum hits, default 10, maximum 25. | |
| query | Yes | Company name, scheme:value identifier, or bare number. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds behavioral insight beyond annotations: the exact matching order, that connected_sources is populated for empty results, and that persons are excluded. It also clarifies that hits include jurisdiction/status/register identifiers. This goes beyond structured hints, though it doesn't disclose return structure in detail (no output schema), so a 4 is appropriate.
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 a single paragraph of moderate length (about 90 words). It front-loads the core purpose in the first sentence, then efficiently covers matching behavior, output fields, and exclusion criteria. While dense, every sentence contributes value; it is structured and avoids fluff. Could be split for readability but remains appropriate and not overwritten.
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 compensates by explicitly enumerating the fields returned (node_id, jurisdiction, status, register identifiers) and the behavior of connected_sources on empty results. It also states the limitation to companies. Combined with a complete input schema and clear annotations, an agent has all necessary information to know what the tool returns and how to use it effectively.
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%, with both 'query' and 'limit' described. The description enhances understanding by detailing query syntax variations (scheme-prefixed, bare number, exact/prefix/token/fuzzy matching) and by noting that limit defaults to 10 with max 25 (already in schema, but reinforced). It adds semantic nuance beyond raw parameter names, such as that bare registration numbers are accepted and how matching is prioritized.
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 clearly states the tool's purpose: 'Find a company by name or identifier.' It specifies the accepted query forms (scheme-prefixed identifier, bare number, company name), distinguishes itself from sibling search tools by noting 'Companies only; persons are never returned,' and explicitly mentions the output's key field (node_id) for downstream use. This is a specific verb plus resource, effectively differentiating from related tools.
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 detailed usage context for the query parameter: matching precedence (exact, prefix, token, fuzzy), accepted input shapes, and the result structure. It implicitly guides when to use the tool (to obtain a node_id for entity_risk_profile) but does not explicitly contrast with alternative search or profile tools. While not stating 'when not to use,' the clear resolution and output semantics imply appropriate contexts, so it is slightly above average but missing explicit alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the Stonewake API documentation at docs.stonewake.ai: authentication and the swk_live_ key format, quickstart, key management, error bodies, status codes, and rate limits. Deterministic text search over the official pages; returns the best matching excerpts with each page's URL. This tool needs no Stonewake API key.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | What to look up, for example: rate limits. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark read-only, idempotent, and non-destructive behavior. The description supplements this with deterministic text search, best-matching excerpts with page URLs, and the no-API-key requirement. No contradiction with annotations.
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?
Three sentences; each carries content: scope/topics, behavior/output, and auth requirement. No filler, and the key information is front-loaded.
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?
Single-parameter read-only search with no output schema; the description tells the agent what it searches, what it returns, and that no key is needed. Nothing essential is missing for correct 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?
The only parameter, query, is fully documented in the schema with an example. The description reiterates topic scope but adds no meaning beyond what the schema already provides, so the baseline of 3 is appropriate.
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 (Search) and resource (Stonewake API documentation), enumerates concrete topics, and clarifies deterministic search with excerpt/URL returns. Unlike sibling tools that search company data, this clearly targets docs.
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?
Explicitly tells the agent this tool needs no Stonewake API key, which is a useful usage condition. It does not explicitly name alternatives or exclusions, but the target context is clearly distinguishable from sibling data-search tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
company_eventscompany_financialscompany_financingcompany_profilecompany_recordscountry_profiledeal_bookdevelopmentsentity_risk_profileownership_chainportfolio_bookportfolio_import_previewportfolio_overviewscoring_rubricscreening_lookupsearch_companiessearch_stonewake_docsResearchOracle - 11 financial research tools: 10-K parsing, equity, macro, citation graph.
Financial and covenant data for public and private credit: statements, cap stacks, covenants.
Financial market, fundamental, valuation, risk, ownership, forecast, and portfolio tools.
ReportingOracle — 16 regulatory reporting tools: BaFin, ESMA, FINREP, COREP, ICAAP, ILAAP.
Add one secure layer between your agents and this server.
