Portravo Construction Takeoff

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

Goes well beyond the annotations by disclosing the 25 MiB size cap, that existing plans and review work are protected, that the PDF is stored privately in the connected account, that it does not extract or consume credits, and that the idempotency key should be reused on retry. This is exactly the extra behavioral context annotations cannot convey.

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 tight sentences, each carrying a distinct constraint (scope, size limit, side-effect safety, idempotency) with the core action front-loaded. 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?

An output schema exists so return values need not be described, and the description covers the mutation's side effects and retry behavior. It is nearly complete, only missing light clarification of the project_id/download_url parameters.

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 carry parameter meaning. It explains idempotency_key semantics well ('stable', 'reuse on retry') and clarifies the plan source, but never explains project_id, download_url, or file_id, leaving the nested object largely undocumented.

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 (attach) and resource (a PDF as the first plan) plus the target (a new Portravo project), which no sibling tool does. An agent can distinguish it from create_project or run_takeoff immediately.

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 clear context that this is for the FIRST plan of a NEW project and that only PDFs up to 25 MiB qualify, but names no alternative tool or explicit when-not path (e.g., what to use for adding a subsequent plan).

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 idempotentHint=true and destructiveHint=false. The description adds meaningful context by explaining that reusing the same idempotency_key on retry creates exactly one project and by clarifying that the call does not run extraction or consume estimate credits.

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 are tightly structured and front-loaded with the core action. Every sentence contributes distinct value: purpose, required/optional inputs, idempotency behavior, and side-effect scoping.

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 need not be described. Annotations cover safety, and the description covers purpose, all four parameters, idempotency, and credit/extraction behavior. Minor gaps around auth or error behavior remain, but the definition is largely 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?

With 0% schema description coverage, the description must compensate and largely does: it identifies name and idempotency_key as required, address and metro_code as optional, and explains idempotency_key's retry semantics. It does not detail format constraints, but those are present in 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 states a specific verb and resource: creating a new construction estimate project in the Portravo account. It also distinguishes itself from the extraction-oriented sibling tools by explicitly saying it does not run extraction or consume estimate credits.

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 implied by the create action and the note that extraction is not included, but the description does not explicitly say when to use this tool versus alternatives such as list_projects, run_takeoff, or get_takeoff. The boundary around extraction is helpful but not a full when-to-use guide.

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, and the description goes well beyond them: the download link is short-lived, exports are gated on a review state, the estimate must be owned, and the incomplete-review branch returns a link instead of a file. These are exactly the behavioral traits an agent needs, and none of them contradict the read-only 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?

Three sentences, front-loaded with the output artifact and its precondition, then the fallback, then the hard constraint. No filler, and the operative rule ('Never exports unreviewed estimates') is placed last for emphasis.

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 return values need not be enumerated, and the description still discloses the two possible return shapes (XLSX download vs. review link). For a single-parameter export tool the description covers preconditions, eligibility, fallback and constraints completely.

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?

There is one parameter (project_id) at 0% schema description coverage, so the schema contributes no semantic detail and the description compensates with nothing about it — no format, no source of the ID, no note that it must reference an owned project (the ownership constraint is stated only generically). The parameter name is largely self-explanatory, but the description adds no value here.

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 ('Get an Excel XLSX download') and a precise resource ('an owned Portravo estimate'), and qualifies it with the exact precondition state (reviewed, priced or final). This is distinguishable from every sibling tool, none of which produce a workbook export.

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 gives the when ('after every takeoff line has been reviewed and the estimate is priced or final') and the when-not with an alternative path ('if review is incomplete, return the Portravo review link and let the user complete quantities, assembly mappings and pricing there'). An agent knows both the gate condition and the fallback without inferring anything.

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, and destructiveHint=false, so the safety profile is fully covered structurally. The description adds only that this reflects post-OAuth-linked state, which is modest extra context; it says nothing about behavior when no account is linked or the session is expired. With annotations carrying the burden, a 3 is appropriate.

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

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

A single twelve-word sentence with the subject and action front-loaded and zero filler. Nothing could be removed without losing meaning.

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 return values need not be explained, and annotations cover the safety profile for a read-only zero-param call. The description is sufficient to invoke the tool correctly, though a note on behavior when no account is linked would complete 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 tool takes zero parameters, so there is no parameter semantics for the description to clarify. Baseline 4 applies; the description correctly adds no parameter claims that could mislead.

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 (Identify) and resource (the signed-in Portravo account), and adds the triggering condition (after OAuth account linking). It does not explicitly distinguish itself from siblings, but the sibling list (project/takeoff tools) is entirely unrelated, so differentiation is not a real risk.

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 phrase 'after OAuth account linking' implies the context in which the tool is relevant, which is useful for a zero-parameter tool. However, it never states when an agent should call this versus any other account-related step, nor any preconditions such as an active session or completed auth flow.

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, so the bar is lower; the description adds real value with the 'owned project' access scope and the caveat that quantities require estimator review before pricing or bidding. It stops short of describing pagination or freshness of the extracted data.

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 zero waste; the resource and return contents are front-loaded and the review caveat follows. 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?

An output schema exists, so return-format detail is unnecessary, and the description still enumerates the key returned fields along with the access scope and data-reliability caveat. Nothing essential for correct invocation 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 defines project_id's type, pattern and length but provides 0% description coverage, and the description never explains that parameter. It only implies scope via 'owned construction project,' so it partially compensates without giving format or ownership 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?

States a specific verb (read) and resource (plan files plus extracted takeoff quantities, trades, confidence, review status) with precise scope. It is clearly distinguishable from the write-oriented siblings run_takeoff and export_reviewed_estimate.

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

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

Explicitly says to use it 'to summarize quantities or identify pending review,' giving clear triggering contexts. It does not, however, name alternatives such as run_takeoff or export_reviewed_estimate or state when not to use 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 declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds only the workflow prerequisite role and nothing about result shape, size, or freshness, so it is adequate but not rich.

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 no filler; verb, resource, and purpose all appear before the reader has to scan further. 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?

With no input parameters and an output schema already defined, the description needs only to explain what the tool is and when to reach for it, which it does. 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?

The tool takes zero parameters, which is the baseline case for a 4. The description helpfully references metro_code, the value this tool informs, even though that field belongs to a different tool's 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?

States a specific verb (list) plus resource (regional construction pricing markets) and names the provider, Portravo. The agent immediately knows this is a discovery/ lookup of supported regions, distinct from the sibling tools like create_project or run_takeoff.

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 positions the call in a workflow: invoke it before choosing a metro_code for a new estimate. That gives a clear when-to-use signal, though it names no alternatives or exclusions, 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?

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so safety is covered. The description adds real behavioral context beyond that: page size (50 projects per page) and how to advance through results. It stops short of describing ordering or total counts.

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: scope first, then pagination mechanics. No filler, everything 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?

An output schema exists, so return-value detail is unnecessary, and pagination is the main gap an agent would need — which the description covers. Only the offset/nextOffset naming inconsistency and absent ordering/limits keep it from being fully complete for a read-only listing 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?

The schema's single 'offset' parameter has 0% description coverage, so the description must compensate. It explains the pagination model and the 50-per-page size, which gives 'offset' meaning, but it refers to the continuation value as 'nextOffset' rather than the actual parameter name 'offset' — a naming mismatch that could confuse invocation.

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 plus resource ('Find construction projects') and enumerates the statuses it covers (draft, review, priced, final estimates). It is distinguishable from create_project and the takeoff siblings, though 'Find' is slightly weaker than 'List' given the tool name.

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 implied (enumerate projects in the account) and it gives pagination guidance ('Use nextOffset to continue'), but it never states when to prefer this over siblings like create_project or list_pricing_markets, nor any exclusions.

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 non-read-only, idempotent and non-destructive, and the description adds substantial extra behavior: it consumes one estimate from the user's balance, requires explicit credit confirmation, refunds the reservation on provider failure, and cannot overwrite existing review work. These are exactly the side effects an agent must know before calling a metered mutation.

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 dense sentences, front-loaded with the action and its cost implication, then confirmation, retry, and failure semantics. No filler and nothing repeated from the annotations.

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 return shape need not be spelled out, and the description still clarifies the output is extracted quantities for review rather than a bid-ready estimate. Billing, idempotency, refund, and overwrite behavior are all covered for a 3-param metered mutation.

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 carry parameter meaning, and it explains two of three: confirm_credit_use (must be true only after explicit user confirmation) and idempotency_key (reuse on retry to prevent duplicate charge). project_id is only implied by 'a new project', leaving a minor 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?

States a specific verb ('run the initial AI takeoff') and resource ('a new project with an attached plan PDF'), which cleanly separates it from get_takeoff (retrieve) and attach_plan_pdf (attach). An agent can identify this as the initiating extraction call without opening the schema.

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

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

Gives clear context for use (new project, plan already attached, initial run) and a concrete precondition for the confirm flag plus retry guidance for the idempotency key. It does not explicitly name sibling alternatives for the retrieve/re-export cases, but the scenario framing makes the routing inferable.

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