Scrutica

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

Beyond the readOnlyHint annotation, the description discloses bounded results, the 24-event cap, truncation in metadata, separate date-keyed removal events, zero-count week semantics, and the derivation of event dates with authority tier. These are exactly the non-obvious behaviors an agent needs to 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 long but proportionally so for a complex tool; it front-loads purpose and routing, organizes return semantics into labeled paragraphs, and every sentence carries operational meaning. No filler is present.

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 burden of explaining return values, and it does: event composition, counts, samples, rollup, truncation, and removal handling. It also clarifies zero-count weeks and authority sourcing, so an agent has enough context to call and interpret 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%, so the baseline is 3. The description still adds value by explaining that 'count field always reports the full total in scope,' that truncation appears in metadata, and that company_id only matches entities in the cross-reference id space — avoiding false scoping assumptions.

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 first sentence defines a specific operation and resource: 'What CHANGED in the BIS Entity List, as bounded change-log summaries.' It also names the sibling it competes with (scrutica_query_export_controls) and the freshness scenario, so an agent can tell them apart without opening schemas.

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 explicit routing: 'PREFER this over scrutica_query_export_controls for freshness questions' and 'Do NOT use this to look up one entity's designation rows — use scrutica_query_export_controls.' It also scopes company_id to an already-resolved organization, clarifying when the parameter is appropriate.

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 description goes well beyond the readOnlyHint annotation. It discloses the calculation model (dense peak × unit_count × utilization), the fixed bounds (0.7 and 1.15), the instruction to retain the bounds and is_estimated flag, and its limitations regarding facility verification. This is rich behavioral context that a caller needs.

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, zero filler. The purpose is front-loaded, the calculation and bounds follow, and the retention/limitations are compactly stated. Every sentence earns its place.

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 the purpose, the calculation method, output bounds, the is_estimated flag, and points to methodology for named-facility edge cases. It lacks an explicit description of the full output structure (e.g., units, exact fields), but since the bounds and flag are mentioned, and no output schema exists, this is a minor gap. It is sufficiently complete for an agent to call it 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?

With 80% schema description coverage, the baseline is 3. The description adds meaning to unit_count and utilization via the formula, and mentions precision and hardware configuration. However, it does not explain sparsity or precision beyond what the schema enums already convey, and the precision parameter lacks a schema description. The added formula justifies a 4, but it does not fully compensate for the undocumented precision 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 clearly states the tool's purpose: 'Estimate hypothetical peak and sustained throughput for a user-specified hardware configuration and precision.' It names the specific verb (estimate) and resource (throughput), and it is distinct from all sibling tools, which handle entities, facilities, or search. No ambiguity about what this tool does.

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 context for when to use it: it's for hypothetical estimates, and it explicitly states what it does NOT do (verify facility inventory/availability/compliance) and points to separate requirements for named-facility estimates. However, it does not name alternative tools or provide an explicit 'use this when...' statement, leaving some inference to the agent.

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 readOnlyHint annotation already indicates a safe read operation. The description adds useful behavioral context by listing the concrete fields returned and warning that only summary edge counts are included, not full graphs, which prevents unrealistic expectations. It also explains the resolver prerequisite without contradicting any 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: purpose first, then return fields, then explicit alternatives. Every sentence carries useful information with no 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?

There is no output schema, but the description lists the key return fields, notes parent/subsidiary references and edge counts, and warns about using a different tool for full graphs. Together with the parameter schema, the agent has enough to call the tool and interpret its result 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 description coverage is 100%, and the schema already documents the alias relationship and the required format 'org-<slug>'. The description reinforces "canonical Scrutica ID" and the need to resolve via search, but most parameter nuance is already present in the schema, so the description adds little beyond 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 clearly states the verb and resource — "Fetch complete details for a single organization" by canonical Scrutica ID — and explicitly distinguishes itself from siblings by naming what to use instead for BIS details and full edge graphs. This lets an agent immediately recognize the tool's niche.

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 explicit routing guidance: use scrutica_query_export_controls for BIS designation details, and scrutica_get_supply_chain for full edge graphs. The parameter docs also instruct agents to resolve the ID via scrutica_search first and not to guess slugs, which is essential when to use and how to prepare.

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?

While annotations declare readOnlyHint=true, the description goes far beyond that. It explains the nuanced semantics of roles[] (source-established relationships), withheld_roles[], present_inventory vs. catalogue scalars, and clarifies that a recorded organisation is not evidence of title. This rich behavioral detail helps the agent interpret results correctly and avoid common misconceptions.

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-structured. It front-loads the core purpose, then enumerates return fields, then adds critical clarifications and usage notes. Every sentence contributes value—no fluff or redundancy. The length is justified by the complexity of the data returned.

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 lack of an output schema, the description thoroughly documents the return structure (roles, withheld_roles, inventory, scalars, etc.) and the semantics of each. It also addresses the prerequisite (ID resolution) and the tool's limitations. An agent has everything needed to call it correctly and interpret the response accurately.

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?

Even with 100% schema coverage, the description adds crucial parameter guidance: it explains that facility_id is required, gives the format pattern ('fac-<slug>'), clarifies the alias mechanism, and mandates that exactly one of the three aliases must be supplied. This is essential practical information that the schema itself does not convey.

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 verb+resource: 'Fetch complete details for a single Scrutica facility by canonical ID.' It clearly distinguishes from siblings by explicitly stating it does not compute BIS exposure (unlike scrutica_query_export_controls) and that it requires a resolved ID (unlike scrutica_search). The purpose is unambiguous and well-separated.

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?

Provides explicit usage instructions: 'Resolve facility IDs first via scrutica_search' and warns 'do NOT guess slugs.' It also directs BIS-related queries to scrutica_query_export_controls and clarifies that this tool does not handle ownership-chain BIS exposure. This gives clear when-to-use and when-not-to-use guidance, plus a direct pointer to the 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?

ReadOnlyHint is true, and the description adds valuable detail about the return shape (canonical URL + section anchor + summary). This exceeds the annotation's simple safety signal, though it doesn't describe edge cases or additional 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 compact and front-loaded: purpose in the first sentence, topics in the second, and return/usage in the third. No filler words, and every sentence adds distinct 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?

For a one-parameter tool with a clear enum and a read-only action, the description covers purpose, usage trigger, topic list, and return format. Even without an output schema, the agent knows what to expect. It is complete for the tool's simplicity.

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 0%, so the description must compensate. It does by listing all enum values in prose and explaining that the topic refers to a 'metric or index,' which adds context beyond the bare enum. Given the single parameter's simplicity, this is sufficient.

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: 'Return methodology documentation for a Scrutica metric or index.' It clearly distinguishes this from sibling tools focused on entities, scenarios, or searches. The explicit list of topics further clarifies scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides an explicit when-to-use instruction: 'Use this when a user asks "how did you calculate X".' However, it does not mention when not to use it or name alternative tools, so it falls short of a full 5.

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?

While annotations already declare readOnlyHint=true, the description adds substantial behavioral context: returns summary plus serialized substrate with per-item sources and authority tiers, notes capped lists shipping true totals, and explicitly states the propagation simulation is interactive-only. This goes well beyond the annotation.

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 three well-structured sentences: purpose, available values with inline explanations, and return behavior. Every sentence adds necessary information, and the critical limitations are front-loaded in the final sentence.

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 fully covers what the tool returns (summary + substrate), what it does not return (simulation), and the capping behavior. The single parameter is completely explained via the listed scenario IDs, making the tool self-contained.

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 provides only an enum of scenario_id values with zero descriptions. The description compensates by explaining each value (e.g., 'taiwan-strait (4 TSMC disruption scenarios)'), giving the agent full semantic understanding of the only 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: 'Fetch geopolitical compute risk scenarios.' It then lists the available scenarios with their unique contents, which clearly distinguishes this tool from sibling get_* tools for companies, facilities, supply chains, etc.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context that this tool is for risk scenarios, but it does not explicitly name alternative tools or state when not to use it. The sibling tool names imply the domain, yet the guidance is not fully explicit.

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 only declare readOnlyHint=true. The description adds substantial behavioral context: explains the meaning of announced_usd vs announced_govt_only_usd, the exact calculation of reality_ratio with fallback logic, the handling of null denominators, the inclusion of transfers in disbursements, and the existence of reality_ratio_unavailable_reason. This goes far beyond annotations and helps the agent understand edge cases and data limitations.

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 lengthy but well-structured. It opens with the core purpose, then lists returned fields, followed by explanatory paragraphs on semantic nuances. Each sentence contributes to understanding the tool's behavior, with no fluff. While it could be trimmed, the complexity of the data justifies the detail. Front-loaded purpose and field list aid quick scanning.

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 absence of an output schema and the tool's complexity (multiple currency fields, ratio calculations, edge cases), the description is remarkably complete. It documents all return fields, explains calculation logic, notes reporting scopes and limitations, and provides a reason field for missing ratios. An agent can confidently invoke this tool and interpret results without external documentation.

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% with detailed descriptions for all three parameters (country, list_all, program_id). The description adds minor context, such as list_all returning a summary table and program_id accepted formats, but these are largely already present in the schema. For high schema coverage, the baseline of 3 is appropriate; the description does not significantly augment parameter understanding beyond what the schema provides.

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 fetches detailed data on a national sovereign AI compute program, with a specific verb and resource. It distinguishes from siblings by scope (sovereign programs) but does not explicitly name an alternative tool, relying on the tool name and context. The mention of list_all for all programs adds to purpose clarity.

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 does not explicitly state when to use this tool versus alternatives. It mentions that program_id is returned by scrutica_search and list_all, implying a workflow, but gives no direct guidance on when to prefer this tool over search or other get_* tools. No exclusions or alternative routing are provided.

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?

Beyond the readOnlyHint annotation, the description discloses data provenance, partial attribute presence ('appear only where the edge's cited source states them'), and the reason field attribute_withholding. It also quantifies the snapshot size and the licensed-layer limitation, which an agent needs to 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 text is information-dense but front-loaded: purpose first, then parameter behavior, then output semantics, then provenance caveats. Every sentence adds operational value and none repeats 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 specifies the core edge fields and the conditions under which optional attributes appear, so an agent knows what to expect. Collection size, snapshot date, and license restrictions cover the main interpretation risks. The input side is already covered by the schema and full enum semantics in the description.

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 leaves the direction enum values undefined, and the description fills that gap exactly with supplier/customer semantics. It also orients the record-level fields, though it relies on the schema for org_id/limit mechanics and does not compensate for all 40% of undocumented parameters.

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 opening sentence names the exact resource ('supply-chain relationships') and a specific action ('Return'), immediately distinguishing it from sibling tools like scrutica_get_company and scrutica_get_facility. The direction values further clarify the purpose by naming the two relationship orientations.

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 a clear usage model: choose 'upstream' to trace suppliers, 'downstream' for customers, or 'both'. It does not name alternatives or provide when-not-to-use guidance, so it stops short of a 5.

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?

Beyond readOnlyHint, the description reveals matching semantics (case-insensitive substring, no alias expansion), the non-implemented entity_id filter and its response flag, output field list, authority tier, coverage class distinctions, and data_quality_flags semantics. No contradictions 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 longer than average, but the length is earned because it must compensate for no output schema and explain output interpretation. It is front-loaded with purpose and exclusions, though it partially repeats input-schema text for entity_name and entity_id.

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, it enumerates all returned fields and gives load-bearing interpretation for bis_coverage_class and data_quality_flags. It also covers dataset scope, authority tier, and the behavior of entity_id, so an agent can invoke and interpret results without further 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 already documents entity_name, entity_id, and country; the description largely restates those semantics rather than adding new parameter meaning. It adds the one-of usage rule ('Provide entity_name or country'), but limit remains self-explanatory from schema min/max/default.

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?

Opens with a specific verb and resource: 'Look up BIS Entity List designations' and immediately draws the boundary against OFAC SDN and Wassenaar CCL, naming scrutica_get_company as the alternative. This clearly separates it from all nine sibling 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?

Explicitly states when not to use it ('does NOT cover OFAC SDN or Wassenaar CCL') and provides the alternative (scrutica_get_company for OFAC/NS-CMIC/1260H). It also gives the required input pattern ('Provide entity_name or country') and the entity_id caveat.

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=true, so the safety profile is known. The description adds context about search scope (facilities/companies/sovereign programs), return format (ranked results with id/name/type/summary/URL), and explicit exclusions, which go beyond the annotation but don't cover rate limits or pagination.

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?

Four sentences, all substantive: purpose, return type, filters, and exclusions. Front-loaded with the main action, no 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 search tool with no output schema, the description covers purpose, return fields, filters, and exclusions well. It lacks pagination/limit behavior details, but the schema covers limits, and the exclusions make it quite complete for selection.

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 covers 75% of parameters with descriptions (query, country, entity_type). The description reinforces the filtering semantics ('Filter by entity_type', 'Filter by ISO 3166-1 alpha-2 country code') but adds no new details beyond schema, and limit remains undocumented in both.

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?

Description clearly states 'Search facilities, companies, or sovereign programs by free-text query' with a specific verb and resource scope. It also lists return fields and explicitly distinguishes from sibling tools like scrutica_get_company and scrutica_query_export_controls.

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?

Provides explicit when-to-use context ('by free-text query') and clear when-not-to-use with named alternatives: 'Do NOT use this for BIS Entity List / export-control lookups — use scrutica_query_export_controls' and 'Do NOT use this for supply-chain traversal — resolve an entity ID first via this tool, then call scrutica_get_supply_chain'.

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