mtgmon Mortgage Analytics

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

The description goes beyond the annotations by detailing read-only, idempotent, no-auth, no-PII behavior, rate limits, and the meta.available flag including cache-warming retry instructions. This fully discloses behavior 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 comprehensive but slightly redundant in the 'Returns' list, which repeats the same fields in a paragraph and bullet-like form. However, the structure is logical and front-loaded with purpose, making it efficient for an agent.

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's complexity, the description covers all necessary context: input requirements, output structure, meta fields, error conditions (unavailable, cache warm), and rate limits. No critical operational detail 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?

All three parameters have thorough descriptions in the schema (top_n bounds, lender_a/b canonical key requirements with examples). The description augments the schema by explaining why legal names fail and how to resolve them, exceeding the baseline coverage.

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 performs a side-by-side comparison of two lender groups across multiple dimensions (volume, loans, rank, market share, loan type/purpose/occupancy mix, top states). This distinguishes it from siblings like get_lender_profile (single lender) and search_lenders (search).

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 instructs users to call search_lenders first to obtain canonical keys and pass exact `name` values. Also notes that for a single lender, get_lender_profile should be used instead, providing clear alternation guidance.

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, openWorldHint, idempotentHint, and destructiveHint=false. The description goes beyond these by adding concrete details: no auth or API key, no PII, idempotent and safe to retry. It also discloses rate limits (60 req/min, 250 calls/day), the full response shape including meta fields (available, as_of, source_scope, weighting, units, cache_status, caveats, truncated), and the specific meaning of meta.available=false (data unavailable or cache warming, retry after a few seconds, never report as zero). This significantly enhances behavioral understanding beyond the structured 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 comprehensive yet efficiently structured. It opens with a one-line summary, then lists explicit use cases, then details the return structure and behavior. Every sentence earns its place: rate limits, meta fields, and error handling all add value without redundancy. The front-loading of the core purpose and use cases ensures an agent immediately understands when to invoke this tool.

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

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

Given the tool has no inputs, the description fully covers what an agent needs: what data is returned (data.datasets with specific fields), the shape of the response (data and meta), and how to interpret meta.available=false. It even includes operational details like rate limits and retry behavior. The output schema is marked as present, so the description complements it without over-explaining. Nothing is missing for correct invocation and interpretation.

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 tool has zero parameters, and the description explicitly states 'No arguments.' The input schema is empty, so schema coverage is trivially 100%. With no parameters, there is nothing to explain, and the description correctly communicates this. It instead focuses on the output and behavior, which is appropriate. No gap exists in parameter semantics.

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 explicitly states the tool's function: 'Coverage, freshness, and build metadata for every mtgmon dataset.' It names the specific resource (mtgmon datasets) and the kind of information returned. It also distinguishes itself from siblings by positioning itself as a meta-tool for dataset status, with use cases like checking data currency and diagnosing meta.available=false, which none of the sibling tools (e.g., get_market_snapshot, get_hmda_product_analytics) cover.

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 explicit use cases: 'how current is the data', finding latest available month/HMDA year before quoting figures, and diagnosing another tool's meta.available=false. It also gives behavioral guidance: refresh cadences differ, read each row's coverage and last_updated. While it doesn't explicitly say 'don't use for X', the context is clear enough that an agent can decide when this tool is appropriate versus the other data-specific 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?

Beyond the read-only and idempotent hints in annotations, the description adds significant behavioral detail: no auth or API key, no PII, rate limits (60 req/min, 250 calls/day), the exact result shape ({data, meta}), and semantics for meta.available including cache warming and retry advice. This far exceeds the annotation baseline.

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 well-structured with clear sections: summary, use cases, do-not-use cases, important caveats, return format, and behavior. Each sentence serves a purpose and the content is front-loaded with the primary function. Despite its length, it remains efficient given the tool's complexity.

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 all necessary operational context: data source (FFIEC/CFPB HMDA Snapshot), time range (2018 onward), output fields and their units (USD, percentages), special HELOC semantics, rate limits, error handling (meta.available false), and retry behavior. The output schema is present, but the description clarifies field meanings and edge cases, making it fully complete for a caller.

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 covers 100% of parameters with descriptions, the description adds critical context that the schema cannot convey, such as the default product_family being 'heloc', lender names needing to match search_lenders results exactly, and state meaning property state not lender HQ. This additional guidance is essential for correct usage.

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 returns HMDA origination counts, dollar amounts, averages, and YoY growth for a product family, optionally filtered by state or lender. It also explicitly distinguishes it from siblings by listing what it is not for, such as lender rankings or GSE performance.

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 'Use for' and 'Do not use for' sections provide explicit when-to-use and when-not-to-use guidance, including references to sibling tools. The 'Important' section further clarifies the product_family default and the distinction between property state and lender headquarters, leaving no ambiguity about appropriate contexts.

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, openWorldHint, idempotentHint, and destructiveHint. The description goes further by stating there is no auth or API key, no PII, and it is safe to retry. It also details the public endpoint rate limits (60 req/min, 250 calls/day) and explains the meta.available false case, adding substantial behavioral context beyond 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 lengthy but every sentence earns its place: it front-loads the tool's output, then addresses key requirements, behavior, and result shape. It is well-structured, with clear paragraphs for output, canonical key, behavior, and meta handling, without 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?

Given the tool's complexity, the description is exceptionally complete. It covers all essential aspects: return data fields, required canonical key acquisition, alternative tools, rate limits, error/retry semantics, and result shape. The output schema exists, but the description further explains the meaning of meta.available and units, making it fully self-sufficient 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 schema description coverage is 100%, the description enhances both parameters. For lender, it clarifies it must be the exact `name` from search_lenders and provides examples and pitfalls (legal names fail). For top_n, the schema already defines it, but the description contextually ties it to the return structure (top_states and state_market_multiples). This adds meaning beyond the schema alone.

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 retrieves an HMDA profile for one lender group and enumerates the specific metrics returned (volume, counts, denial rate, rank, market share, mixes). It distinguishes itself from siblings by explicitly naming search_lenders for canonical keys and compare_lenders for side-by-side comparisons, so an agent can easily differentiate it.

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 explicit when-to-use guidance: it requires a canonical key obtained via search_lenders, warns that alternative spellings fail, and directs to compare_lenders for two-lender comparisons. It also discloses rate limits and retry behavior, leaving no ambiguity about appropriate invocation context.

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, destructiveHint=false, but the description adds substantial non-obvious behavior: no auth/PII, public endpoint rate limits (60 req/min, 250 calls/day), the result shape {data, meta}, meta field semantics (available, as_of, source_scope, weighting, units, cache_status, caveats, truncated), and critical guidance on handling meta.available=false (retry, never report as zero). This goes well beyond the annotations and is essential for correct invocation.

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?

Despite its length, the description is tightly structured: a one-line purpose, a bulleted list of nine topics each with its data payload, a compact use/do-not-use section, and a concise behavior paragraph. Every sentence adds unique value—rate limits, meta handling, and cache-warming are all critical and not stated elsewhere. There is no fluff or repetition; 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?

The tool is complex (nine topics, six parameters, one required) and the description fully equips an agent to call it correctly. It covers all topics and their data shapes, parameter scoping, behavioral constraints (read-only, rate limits, retry logic), result meta semantics, and how to handle unavailable data. An output schema exists (indicated by 'Has output schema: true'), so return-value details are already structured; the description complements rather than duplicates it. Nothing essential is missing.

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

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

Schema coverage is 100% with each parameter individually described (e.g., gse enum with defaults, from_date/to_date ISO dates, top_n and max_points with ranges). The description adds cross-cutting meaning: which parameters apply to which topics (from_date applies to credit/prepayment/delinquency/loss/transitions history; top_n applies to transitions/modification/lock_in; max_points applies to time-series/vintage/transitions). It also clarifies topic-specific output shapes (data.series, data.latest, data.flows, etc.), which the schema does not cover. This enriches beyond the structured fields.

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 statement: 'Fannie Mae and Freddie Mac single-family loan-performance analytics for exactly one topic.' It then enumerates nine distinct topics, each with its own data shape, and explicitly names sibling tools (search_lenders, get_lender_profile, get_market_snapshot, get_servicer_analytics) to say what it is not. An agent can immediately understand the resource, scope, and how it differs from alternatives.

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 an explicit 'Use for' list (agency credit quality, prepayment speeds, delinquency, roll and cure rates, modification outcomes, losses, lock-in effect) and a 'Do not use for' list that names the exact sibling tools to route to instead (originator volume -> search_lenders/get_lender_profile, today's rates -> get_market_snapshot, per-servicer -> get_servicer_analytics). This leaves no ambiguity about when to select this 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?

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description adds meaningful behavioral context: no auth or API key required, no PII, idempotent and safe to retry, public endpoint rate limits, and detailed meta.available handling with retry guidance. It also warns against reporting unavailable data as zero, which is valuable operational behavior not captured in 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 but well-structured: a one-sentence summary, followed by usage guidance, then behavior and response-shape details. Every sentence adds operational value, and the most important scoping information is front-loaded. Despite its length, nothing feels redundant given the no-parameter, output-rich nature of the tool.

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

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

For a no-argument tool with an output schema and annotations, the description is fully complete: it names all return series, explains units, warns that series have different observation dates, documents the result envelope, and explains how to handle meta.available=false. An agent has everything needed to call the tool and interpret the 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?

The tool has zero parameters, so the baseline is 4. The description explicitly states 'No arguments' and the input schema confirms an empty properties object, leaving no ambiguity about how to invoke the 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 opens with a specific, resource-rich statement: 'Latest U.S. mortgage rates, TBA par coupons, Treasury and SOFR benchmarks, and mtgmon's fitted MBS basis in one call.' It also distinguishes itself from sibling tools by explicitly naming get_loan_performance as the alternative for GSE loan performance. An agent can confidently know what this tool returns and what it does not.

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 explicit 'Use for' and 'Do not use for' sections, listing concrete example queries such as 'what are mortgage rates today' and naming get_loan_performance as the alternative for GSE loan performance. This gives an agent clear selection criteria with no inference required.

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 beyond the readOnlyHint and idempotentHint annotations by stating 'read-only, no auth or API key, no PII, idempotent and safe to retry.' It discloses rate limits (60 req/min, 250 calls/day) and explains the meta.available flag behavior, including that a false value means the cache is warming and to retry rather than reporting zero.

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 structured with a clear purpose sentence, a prerequisite instruction, a detailed return shape, and a behavior section. Every sentence adds operational information; no filler. The most critical usage guidance (obtain ID from search_sec_filings) 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?

The description fully equips an agent to call the tool: it specifies the return structure with field examples, explains the meta wrapper and its fields, addresses error conditions (meta.available false), and notes list caps. Combined with the output schema, nothing necessary 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?

The schema already provides 100% coverage for filing_id, including format and examples. The description adds value by telling the agent to obtain the ID from search_sec_filings, ensuring correct source. Since the schema is exhaustive, the description's contribution is supplementary but useful.

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 'Full detail for one SEC filing' and enumerates the exact content areas (metadata, EDGAR link, machine-generated summary, associations, people, financials, ownership). It clearly distinguishes itself from search_sec_filings and other analytics siblings by focusing on a single filing's detailed 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?

It explicitly instructs 'Get the filing_id from search_sec_filings first,' establishing the prerequisite workflow and when to use this tool. It also advises to 'Verify summaries against the linked filing before relying on them,' adding a caution about usage context.

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, destructiveHint=false; the description adds substantial context beyond them: read-only, no auth/API key, no PII, idempotent and safe to retry, rate limits (60 req/min, 250 calls/day per IP), the {data, meta} response shape, and the critical meta.available=false cache-warming caveat with the instruction to never report it as zero. 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 long, but every sentence earns its place — modes, output shapes, use cases, exclusions, coverage limits, rate limits, response shape. It is front-loaded with the purpose and mode overview before behavioral details. Slightly verbose, but nothing is 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 three-mode, six-parameter tool with an output schema present, the description is exceptionally complete: per-mode return structures are spelled out, edge cases (cache warming, canonical key mismatch, coverage scope) are covered, and error interpretation (meta.available=false) is explained. An agent has everything needed 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it explains that `lender` must be a canonical key from search_lenders and that legal names fail with meta.available=false, and it clarifies cross-parameter interactions (lender required only for transfers, vintage/max_points only for performance, gse ignored by transfers). This materially improves call correctness.

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 ('Agency (Fannie Mae / Freddie Mac) servicer analytics') and immediately enumerates three concrete modes with distinct output shapes (scorecard/performance/transfers). It names sibling alternatives (get_lender_profile, get_loan_performance) it is not, so an agent can disambiguate 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?

Provides explicit 'Use for:' examples ('largest servicers', 'which servicer prepays fastest...', 'who services Rocket's loans now') and explicit 'Do not use for:' exclusions naming the correct alternatives for each case. Nothing is left to inference.

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. The description adds substantial behavioral context beyond those: no auth/API key, no PII, rate limits (60 req/min, 250 calls/day), result shape ({data, meta}), meta fields (available, as_of, source_scope, etc.), and explicit guidance on handling meta.available=false (retry, don't report as zero). This is rich, non-contradictory behavioral disclosure.

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 well-structured and front-loaded: purpose, then use cases, then downstream integration, then return shape, then behavior. It is longer than average but every sentence carries information—rate limits, meta handling, and result semantics are all needed. It could be tightened slightly (e.g., some repetition of 'read-only' with annotations), 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?

For a tool with 6 optional parameters, a rich output schema, and many siblings, the description is exceptionally complete. It explains the return fields, the meta structure, error/retry behavior, rate limits, and how to chain results into other tools. It also clarifies the meaning of canonical keys vs. legal names. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% with detailed per-parameter descriptions and examples, so the baseline is 3. The description adds value by explaining the parameters' roles in the overall workflow (query for name resolution, sort for ranking, charter/state for filtering) and by clarifying result-field semantics (recent_volume is USD, keys roll up subsidiaries). It goes beyond the schema's literal parameter docs, though not dramatically.

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 ('Find'), a precise resource ('HMDA lenders'), and the core outcome ('resolve names to canonical lender keys'). It clearly distinguishes itself from siblings by positioning itself as the entry point ('Call this before any other lender tool') and by giving concrete example queries. This leaves no ambiguity about what the 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 explicit when-to-use guidance: 'Use for: turning a company name... into its canonical key, ranking lenders... or listing lenders by charter type or headquarters state.' It also gives when-not-to-use context ('Legal names such as... are not keys') and points to alternative tools by telling the agent to pass results to get_lender_profile, get_hmda_product_analytics, or get_servicer_analytics. This fully routes the agent to the correct workflow.

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, etc., and the description goes far beyond them by specifying no auth/PII, rate limits (60 req/min, 250 calls/day), the exact result shape with meta fields, and the meaning of meta.available (cache warming vs. real zero). It also warns that summaries are machine-generated and should be checked against edgar_url. No contradictions.

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 structured logically: purpose, usage, returns, behavior. It is comprehensive but each sentence carries distinct information. It front-loads the core purpose and distinguishes from siblings, then moves to operational details. No filler or 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?

For a complex tool with 9 parameters, an output schema, and a paginated response, the description covers everything an agent needs: scope, filtering options, return fields, cursor semantics, rate limits, and handling of unavailable data. It also explains the relationship with get_sec_filing and the limitation to summaries. Nothing essential is missing.

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

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

Schema coverage is 100%, so parameters are well-documented. The description adds value beyond schema by explaining how limit affects returned rows, how cursor works for pagination, and the meaning of summary_status values (though schema covers those too). It also ties parameters to use cases. This exceeds the baseline for high schema coverage.

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 searches SEC EDGAR filings of mortgage-related public companies, with specific detail on the types of companies and the mtgmon summarization scope. It distinguishes itself from get_sec_filing by mentioning the filing_id output and explicitly excludes full-text search and non-mortgage sectors, making it 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?

The description has an explicit 'Use for' section listing exact use cases (finding filings by ticker, CIK, form, keyword, date window) and a 'Do not use for' section that directs away from full filing text and non-mortgage companies. It also references get_sec_filing as the intended downstream tool, providing clear routing.

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