Rafid Property Intelligence

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature. The description adds value by specifying that the tool returns evidence signals rather than a safe/unsafe verdict, and that signals are 'evidence-tiered'. This clarifies the output's nature 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 a single, information-dense sentence. It front-loads the core purpose, enumerates the signal scope, and ends with the caveat. No wasted words, though the length is justified by the content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 4 parameters with no schema descriptions and no required fields, the description should explain parameter usage and optionality. It provides a high-level purpose and usage context but omits operational details like how to specify checks, whether country/website are optional, or how they relate to the company parameter. The presence of an output schema helps but does not cover input semantics.

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 0%, so the description must compensate for parameter documentation. It lists signal types (corporate_identity, domain, etc.) that map to the 'checks' enum, but never explicitly says that the 'checks' parameter selects these. It also does not explain the 'company', 'country', or 'website' parameters. This is a significant gap.

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 ('gather') and a clear resource ('evidence-tiered risk signals for a company'), enumerates the signal categories, and explicitly disclaims a verdict output. This distinguishes it from potential siblings like research_company or due_diligence_oman_company.

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 when-to-use context ('when an agent needs risk evidence to weigh before a transaction, partnership, or onboarding decision') and an explicit exclusion ('not a substitute for compliance/legal sign-off'). It clearly frames the tool's role without naming alternatives, which is sufficient.

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, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context beyond these by stating the output is 'deterministic' and by naming the kinds of results produced ('signals, risk flags and positive signals'). This gives the agent a good sense of call-to-call behavior and output scope without contradicting 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 two sentences with no filler. The action and primary scope are front-loaded, and the second sentence earns its place by adding the usage context. Every word contributes to the agent's understanding.

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 a rich output schema present and annotations covering the safety profile, the description does not need to explain return formats or side effects. It correctly focuses on the two required parameters and the decision context. The only gap is lack of explicit differentiation from the due_diligence_oman_company sibling, but that does not block 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 0%, so the description must compensate for what the schema does not explain. It does reference companyId and purpose ('by companyId, for a stated evaluation purpose') and gives examples of purpose values (supplier, customer, partner, investment target) that mirror the enum. However, it does not explain how each purpose value changes the analysis or what companyId format is expected, leaving some ambiguity.

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 ('Generate') and a precise resource: 'deterministic commercial-intelligence signals, risk flags and positive signals for one Oman company by companyId'. It clearly scopes the operation to a single company and a stated purpose. However, it does not differentiate this tool from its sibling due_diligence_oman_company, so it stops 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?

The description provides a clear use-when condition: 'when an agent needs to assess whether an Oman company looks like a serious, established operating business — as a supplier, customer, partner or investment target.' This gives the agent strong situational context. It does not explicitly name alternatives or give when-not-to-use conditions, which prevents 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds methodological context—local rental comparables, market context, investment metrics—but doesn't detail data sources, freshness, or failure conditions, so it only partially supplements 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?

Two tight sentences, front-loaded with the action and scope, followed by a use-when trigger. No wasted words or redundancy—every clause 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?

For a tool with 11 parameters and zero schema descriptions, the description covers purpose and domain but leaves parameter semantics unaddressed. The presence of an output schema and read-only annotations reduces the burden on return-value and safety documentation, yet the missing parameter guidance is a real gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With schema_description_coverage at 0%, the description must compensate, but it only names output dimensions (rental, yield, price-position, operating-cost) and says nothing about how inputs like governorate, area, propertyType, sizeSqm, or the optional maintenance/service-charge parameters affect the analysis. The description adds almost no meaning beyond what the bare parameter names already imply.

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 ('Analyze') plus a resource ('Oman residential property') and lists concrete analysis dimensions: rental, yield, price-position, operating-cost. The 'Oman-specific' qualifier clearly distinguishes it from the generic sibling analyze_property, and the scope is unambiguous.

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 a clear 'Use when...' clause that identifies eligible scenarios: Oman-specific rental, yield, price-position or operating-cost analysis. It doesn't explicitly name alternatives or exclusions, but the usage trigger is concrete enough to route an agent correctly in most cases.

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

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

Annotations already cover readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is handled. The description adds a useful boundary beyond annotations: this tool performs calculations only, with no broader analysis or external data lookup, and returns OMR-denominated metrics. No contradiction.

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 short sentences with the calculation scope front-loaded and the usage condition in the second sentence. No filler, repetition, or irrelevant detail.

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?

An output schema exists, so not explaining return values is acceptable. The description covers purpose, scope, and currency, but for a 7-parameter calculator it leaves optional-parameter semantics and formula behavior unstated, so an agent cannot fully anticipate how inputs affect the metrics. Adequate but with clear 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 only 14%, so the description must compensate, but it names no input parameters and explains no unit or formula semantics (e.g., whether vacancyRatePct reduces gross rent or how maintenance aliases resolve). The output terms weakly imply mapping to propertyValue and annualRent, but this is far short of the needed guidance.

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 ('Calculate'), a resource ('a single property'), a defined output set (gross/net rental yield, income, operating costs, simple payback), and an explicit scope ('Calculations only'). The 'Calculations only' phrase and 'single property' scope distinguish it from broader siblings such as analyze_oman_property and compare_properties.

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 to use: 'Use when an agent needs financial metrics (yield, income, payback) for a single property.' It does not name sibling alternatives or provide when-not-to-use conditions, but the selection cue is clear.

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

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

Annotations already cover safety (readOnlyHint, idempotentHint, destructiveHint). The description adds behavioral detail on ordering and tie-breaking ('order by rounded net yield, preserving input order for ties'), which is valuable. It does not disclose the exact net yield formula, but that may be in the output schema.

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 concise sentences, front-loading the core action and use case. Every word adds value, with no redundancy.

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 purpose, usage, and key behavioral traits. The output schema exists, so return format is not required. The only missing piece is the net yield formula, but the tool's scope and input constraints are well conveyed.

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 0%, so the description must compensate for parameter meaning. It only mentions 'uniquely named properties' and the 2-20 range, but does not explain which fields (e.g., propertyValue, annualRent, maintenanceCost) feed into the net yield calculation. The agent gets no guidance on how to populate the input beyond the schema's structural constraints.

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 ('compare'), a resource ('properties in OMR'), and a clear outcome ('order by rounded net yield, preserving input order for ties'). It distinguishes itself from sibling analysis tools by focusing on multi-property ranking rather than single-property analysis.

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 'Use when an agent must rank or choose between 2-20 candidate properties by net yield.' This gives a clear trigger condition, though it does not name alternative tools or state when not to use it. The guidance is sufficient for most cases.

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 establish read-only, idempotent, non-destructive behavior. The description adds useful context beyond that: it is 'source-backed', returns 'known information gaps', and is positioned as a structured decision-support pass. This communicates investigative rather than authoritative-exhaustive 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?

Two sentences, front-loaded with the core action and outputs, followed by concrete use cases. The text is compact and every clause adds selection or invocation value, despite minor repetition of 'structured' and 'ahead of'.

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 tool with an output schema and read-only/idempotent annotations, the description covers the main invocation decision well: what it does, what it returns, and when to use it. It could be more complete by addressing the optional transactionValueOMR parameter and explicitly steering away from lighter-weight siblings like get_oman_company_profile.

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 0%, so the description must compensate. It directly names companyId and indirectly explains transactionType by mapping 'contract, partnership, extending credit, investing' to the enum values. However, it says nothing about transactionValueOMR, leaving one parameter without added semantic guidance.

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 uses a specific verb-resource pair: 'Perform structured commercial due diligence on one Oman company by companyId.' It also names the concrete outputs—identity verification, risk assessment, prioritized checklist, and known information gaps—which clearly distinguishes it from profile-retrieval or general-analysis 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 explicit use contexts: before awarding a contract, entering a partnership, extending credit, or investing, when a structured due-diligence pass is needed. It does not explicitly mention when not to use it or name alternative sibling tools, so it falls just 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?

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds a valuable caveat—'Uncalibrated heuristic, not a survey'—which helps an agent calibrate trust in the result, and it notes the role of optional assumptions.

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 core operation and inputs, followed by a caveat and a usage trigger. No filler or redundant 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 an output schema present and safety annotations already covering idempotence and read-only behavior, the description completes the picture: what it estimates, its reliability, and when to use it. The nested assumptions object is referenced, leaving schema details to do the remaining work.

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 low at 20%, but the description compensates by mapping the main parameters to real-world meaning: value, age, and unit count, plus optional assumptions. It does not flesh out the nested assumption fields, but the schema documents annualRent separately.

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 operation (estimate), a concrete resource (annual maintenance reserve in OMR), and the key inputs (value, age, unit count). It also distinguishes itself from analysis/inspection tools by calling itself an uncalibrated heuristic, not a survey.

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 an explicit trigger: use when an agent needs an annual maintenance reserve estimate for a property. It also provides a when-not by stating 'not an actual inspection,' though it does not name a specific alternative sibling tool.

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 and idempotentHint, but the description adds valuable behavioral context: results are cited, never fabricated, and come with a confidence score. It also says sources are public web sources. This goes beyond annotations, though it could mention rate limits or sorting 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 a single, front-loaded sentence with no wasted words. It states the core action first, then criteria, output guarantees, and usage context. Every clause 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?

Given 8 parameters, zero schema descriptions, and an output schema, the description covers purpose, usage, and high-level output guarantees. However, it does not explain all parameters (query, limit) or how filters interact. While the output schema defines return format, parameter semantics are incomplete, leaving an agent to infer details.

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 0% schema description coverage, the description must explain parameters. It mentions industry, location, size, and keywords, which map to industry, city/country, employeeMin/Max, and keywords. However, it omits 'query' (free-text search) and 'limit' (result cap), and does not clarify how criteria combine (AND/OR). It partially compensates but leaves gaps.

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 action ('Discover companies'), the resource ('companies'), and the filtering criteria (industry, location, size, keywords). It differentiates from siblings by explicitly contrasting with analyzing an already-known company, making it distinct from tools like research_company or get_oman_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?

It provides explicit when-to-use guidance ('Use when an agent needs to discover a list of candidate companies') and a when-not ('rather than analyze one already-known company'), but does not name specific alternative sibling tools. The contrast is clear enough, though referencing a specific alternative would strengthen it.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description only needs to add behavioral context beyond that. It adds 'digital-presence detection' and 'full source provenance', which are meaningful behavioral traits not present in the annotations or schema. 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 two tightly packed sentences: the first states exactly what is returned and for which entity, and the second gives workflow position. There is no filler, no repetition of schema structure, and 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?

With one parameter, an output schema, and annotations covering idempotency and non-destructiveness, the description provides the operational guidance needed to call the tool correctly. It tells the agent what to retrieve, how to obtain the required companyId, and when in the workflow to invoke it.

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 0% description coverage, so the description must compensate. It explains that companyId is resolved by search_oman_company, giving useful provenance for the parameter. It does not detail the ID format, but with a single self-explanatory identifier and schema constraints (minLength/maxLength), 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 names a specific verb and resource: 'Return a structured profile for one Oman company by companyId', and enumerates concrete content areas (identity, registration, location, contact, digital presence, provenance). It also distinguishes itself from siblings by positioning search_oman_company as the ID-resolution step and analysis/due-diligence tools as later stages.

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 tool should be used after search_oman_company resolves a companyId, and before deciding whether deeper analysis or due diligence is warranted. This gives clear workflow placement and tells the agent where this tool fits among its siblings.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: it uses public web sources, produces cited sources and a confidence score, and covers risk flags. It doesn't mention rate limits or latency, but for a read-only research tool with strong annotations, the added context is solid.

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, information-dense sentence followed by a use-case clause. It front-loads the core purpose and content areas before the usage guidance. It earns its length by covering scope, output characteristics, and usage context without redundancy, though it is slightly long.

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 tool has an output schema, so return values are documented elsewhere. The description covers what the tool does, when to use it, and what it produces (cited sources, confidence score). It doesn't mention that the company parameter is required or that depth has a default, but the schema handles that. For a read-only research tool with rich annotations and an output schema, this is nearly 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 description coverage is 0%, so the description must compensate. It does not explain individual parameters, but it names the content areas that map to focusAreas enum values (overview, products, leadership, funding, competitors, technology, recent_news, market_position, risks). The description's mention of 'overview, products, leadership, funding, competitors, technology signals, recent developments and risk flags' directly mirrors the focusAreas enum, giving agents a semantic anchor. However, it doesn't clarify depth, country, or website parameters, so it's not a 5.

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 ('Research') and resource ('a company from public web sources'), and enumerates the content areas covered (overview, products, leadership, funding, competitors, technology signals, recent developments, risk flags) plus cited sources and a confidence score. It clearly distinguishes itself from a structured company registry, which differentiates it from sibling tools like get_oman_company_profile or find_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 explicitly says 'Use when an agent needs a structured research brief on a named company' and lists use cases: sales/investment/partnership research, competitive analysis, or general company background. It also states when NOT to use it: 'beyond what a structured company registry alone provides,' which routes agents away from registry-style siblings.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior, so the description's main contribution is the disclosure that results are 'ranked by deterministic identity-match confidence' and that it returns candidate matches. This adds meaningful behavioral context beyond the structured annotations and reassures the agent about stability and ordering.

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 with no filler. The core action, resource, fields, output, and usage timing are all front-loaded and each 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?

Given that an output schema exists and the annotations cover safety semantics, the description is complete enough for invocation. It explains the tool's role relative to analysis and due diligence, though it could have explicitly contrasted it with get_oman_company_profile for fully unambiguous sibling routing.

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 0%, so the description carries the burden of explaining parameters. It explains that query can be a name or registration number and explicitly mentions governorate, wilayat, and industry as filter fields. Only 'limit' is not described, but its purpose is reasonably inferable from the schema's min/max constraints.

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 uses a specific verb ('Search'), names the resource ('structured Oman business records'), lists the searchable fields, and states the output ('candidate companies ranked by deterministic identity-match confidence'). It clearly differentiates itself from analysis/profile tools by framing this as the identity-lookup step before analysis or due diligence.

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 to use this tool before company analysis or due diligence when the exact company identity is uncertain, and for finding candidates by name or registration number. It provides strong context for when to invoke it, though it does not explicitly name sibling tools or describe when to use get_oman_company_profile instead.

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