Conversion Ledger (RAD)

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

Annotations already cover readOnly, idempotent, non-destructive, and closed-world, so the bar is lower. The description still adds the key operational fact an agent would otherwise worry about: it only produces a link and submits nothing. It omits whether the link expires or requires authentication, keeping it short of a 5.

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 compact clauses with zero filler, and the non-submitting guarantee is front-loaded enough to be read before invocation. Minor awkwardness in opening with "The page where..." when the tool actually returns a link, not the page.

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 zero-required-parameter link generator with no output schema, the description covers what it produces (a link), what it does not do (submit), and the deal types in scope. 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 67% — pha and topic carry descriptions, units does not. The description contributes the framing that all three are optional prefills, which clarifies intent, but adds no syntax or format detail for the undocumented units 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?

States a concrete verb and resource — returns a link to a Janover Capital LLC financing-quote request page — and enumerates the eligible deal types (RAD conversion, Section 18 blend, PRAC, Component 2, refinance). The financing-quote focus is clearly distinct from the sibling tools get_rad_program_facts, size_rad_debt, and search_conversions.

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 audience and use case are explicit: a housing authority, developer or owner seeking a financing quote for a listed deal type. It does not name alternatives or state when-not to use it, but the domain is narrow enough that the intended trigger is unambiguous.

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 readOnly, idempotent, non-destructive, closed-world behavior, so the description's job is mainly to describe the payload, which it does in detail (unit counts, financing type breakdowns, weighted 2026 rent). It omits what happens on a partial/ambiguous name match or a failed lookup, which matters with no output schema and all-optional params.

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: the first front-loads the resource and its contents, the second covers identification inputs. Dense but each clause carries information; the long field enumeration is slightly list-heavy but not padded.

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 does the necessary work of telling the agent what comes back, and it explains input alternatives for a zero-required-param tool. Missing only edge-case behavior (ambiguous name, unknown code) that an agent would want before calling.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema: it signals that code, url, and name+state are interchangeable identification routes and that name pairs with state. Examples (IL002, rad.loans page URL) reinforce the expected formats.

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?

Names a specific resource (a single housing authority's RAD record) and enumerates exactly what that record contains: closed conversions with units/PBV/PBRA/tax credits/FHA, CHAP-to-closing deals, remaining public housing units with weighted 2026 RAD rent, and a conversions list. It is clearly a single-entity lookup rather than a search, which implicitly separates it from search_conversions, but no sibling is named explicitly.

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

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

Gives concrete invocation guidance: 'Give the HUD PHA code (IL002), the rad.loans page URL, or name + state,' which is valuable because all four params are optional and an agent otherwise wouldn't know which key to supply or that name needs a state alongside it. It stops short of saying when to prefer this over search_conversions or get_rad_rents.

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 this a safe, idempotent, closed-world read, so the safety profile is covered and the description correctly doesn't repeat it. It instead adds meaningful behavioral context: each fact is returned with its primary source, with citations and dates given inline (PL 119-101 §212, July 2026; 2026 LIHTC bond test), which tells the agent the response is provenance-bearing and temporally scoped.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with a nominal overview followed by a flat topic list; no filler or throat-clearing. It is dense and slightly list-like, but every clause names a distinct content area, so nothing is wasted.

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 zero-parameter, read-only reference tool with no output schema, the description does the essential job: it scopes the content by topic and tells the agent that answers come with sources and dates. What is missing is minor — no statement of the as-of date for the whole snapshot or of what topics fall outside its coverage.

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 takes zero parameters, so there is nothing for the description to disambiguate; the baseline applies. Nothing in the description misleads about inputs.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific resource ('the current state of RAD law and terms') and enumerates the concrete subject areas covered — permanence and the unit cap, governing notices, PBV/PBRA contract terms, FHA premium, LIHTC bond test — so an agent knows exactly what payload it is asking for. It does not explicitly differentiate itself from siblings like get_rad_rents or size_rad_debt, which keeps it from 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?

Usage is only implied: the enumerated subject list signals 'call this for authoritative RAD program/law facts,' but there is no explicit statement of when to prefer it over get_rad_rents, size_rad_debt, or search_conversions, nor any prerequisites. An agent can infer the fit, but must reason it out from topic overlap rather than being routed.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds domain context about what the returned figures mean (caps at 110%/120% FMR, 90/10–60/40–30/70 blends), but says nothing about what happens on ambiguous name matches, empty results, or how `limit` truncates output.

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?

Purpose and returned fields are front-loaded in one dense sentence, followed by a compact input sentence; nothing is wasted. The enumeration of rent components is long but each item is substantive rather than 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?

With no output schema, the description usefully enumerates returned fields, and annotations cover the read-only safety profile. The main gaps are result-set behavior (pagination when `limit` applies, handling of multiple PHA matches), which an agent would want for a 5-parameter search tool.

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 60%, and the description compensates by clarifying the conditional lookup modes: a PIC number alone, or project/pha name together with state — a combination rule the schema does not state. The `limit` parameter and its 1–25 cap remain undocumented in the description, keeping it short of 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?

States a specific verb+resource ('HUD's 2026 RAD contract rent for unconverted public housing projects') and enumerates the exact figures returned (PBV/PBRA caps, blend estimates, utility allowance, operating and tenant rent per unit month). This is clearly distinguishable from siblings like get_rad_program_facts (policy facts) and size_rad_debt (debt sizing).

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 final sentence gives input modes ('Give a PIC project number, or project/pha name with state'), which implies a lookup use case, but there is no explicit when-to-use/when-not guidance or routing to alternatives such as get_rad_program_facts or search_conversions. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful context about the HUD export source and newest-first ordering, but it does not disclose pagination behavior, rate limits, or authentication requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single dense sentence that front-loads the resource and source before listing fields. It is efficient, though the long field list makes it slightly harder to scan.

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

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

With no output schema, the description usefully lists the returned fields and ordering. However, for a 9-parameter search tool it omits important context about filter combinations, default limit behavior, and pagination, leaving 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 67%, so the schema already documents most parameters. The description enumerates returned fields rather than filter semantics and does not clarify how query, limit, or closed_after should be used, so it adds only limited meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the resource as RAD public housing conversions from HUD's RAD Resource Desk export and notes ordering and included fields. It is specific enough to distinguish the tool's data domain, though it does not explicitly name a verb or contrast with 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?

There is no explicit guidance on when to use this tool versus alternatives such as get_housing_authority or get_rad_program_facts. The description implies it is for finding RAD conversions, but it provides no when-to-use or when-not-to-use conditions.

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 read-only, idempotent, closed-world behavior, so the description's job is to add context — and it does: it discloses that debt service includes FHA's 0.25% premium, that the output identifies which coverage/loan-ratio test binds, and that defaults are drawn from named official sources. The 'sketch, not a loan offer' disclaimer usefully signals the output is indicative, not binding.

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 purpose is front-loaded and every clause carries information, but the core sentence is a tangled run-on ('the loan each execution supports by coverage and by loan ratio, which test binds, and annual debt service...') that is hard to parse. The citation list (90 FR 45789, term sheets, URL path) consumes a full sentence that could be compressed.

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 10 parameters and no output schema, the description must explain what comes back, and it does: a loan amount per execution under coverage and loan-ratio tests, the binding constraint, and annual debt service. Missing only detail on what happens when `execution` is omitted (returns all four), which lives in the schema rather than 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?

Schema description coverage is 90%, so the schema already carries most parameter meaning and the baseline is 3. The description adds that defaults (rate, vacancy, opex, reserves) are sourced from ML 2025-03, the MAP Guide, and agency term sheets with HUD median FHA note rates, which tells the agent the omitted values are authoritative rather than arbitrary — but it adds nothing per-parameter beyond that.

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 computation (first-mortgage sizing for a RAD property) and enumerates the four executions it covers, so the agent knows exactly what it produces. It does not explicitly contrast with the sibling tools (get_rad_rents, get_financing_quote_link), but their purposes are far enough apart that confusion is unlikely.

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

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

Usage is only implied: the agent can infer this is the tool to run when it needs sized debt rather than rents or program facts. There is no statement of preconditions (e.g., that units and monthly_rent must be known first), no when-not-to-use, and no pointer to an alternative sizer. The closing 'A sketch, not a loan offer' is a caveat, not routing guidance.

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